@mastra/e2b 0.0.0

package/dist/index.cjs

@@ -0,0 +1,858 @@
+'use strict';
+
+var workspace = require('@mastra/core/workspace');
+var e2b = require('e2b');
+var crypto = require('crypto');
+
+// src/sandbox/index.ts
+
+// src/utils/shell-quote.ts
+function shellQuote(arg) {
+  if (/^[a-zA-Z0-9._\-/@:=]+$/.test(arg)) return arg;
+  return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+var MOUNTABLE_TEMPLATE_VERSION = "v1";
+function createDefaultMountableTemplate() {
+  const aptPackages = ["s3fs", "fuse"];
+  const config = { version: MOUNTABLE_TEMPLATE_VERSION, aptPackages };
+  const hash = crypto.createHash("sha256").update(JSON.stringify(config, Object.keys(config).sort())).digest("hex").slice(0, 16);
+  const template = e2b.Template().fromTemplate("base").aptInstall(aptPackages);
+  return {
+    template,
+    id: `mastra-${hash}`,
+    aptPackages
+  };
+}
+
+// src/sandbox/mounts/types.ts
+var LOG_PREFIX = "[@mastra/e2b]";
+var SAFE_BUCKET_NAME = /^[a-z0-9][a-z0-9.\-]{1,61}[a-z0-9]$/;
+function validateBucketName(bucket) {
+  if (!SAFE_BUCKET_NAME.test(bucket)) {
+    throw new Error(
+      `Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, hyphens, or dots.`
+    );
+  }
+}
+function validateEndpoint(endpoint) {
+  try {
+    new URL(endpoint);
+  } catch {
+    throw new Error(`Invalid endpoint URL: "${endpoint}"`);
+  }
+}
+
+// src/sandbox/mounts/s3.ts
+async function mountS3(mountPath, config, ctx) {
+  const { sandbox, logger } = ctx;
+  validateBucketName(config.bucket);
+  if (config.endpoint) {
+    validateEndpoint(config.endpoint);
+  }
+  const checkResult = await sandbox.commands.run('which s3fs || echo "not found"');
+  if (checkResult.stdout.includes("not found")) {
+    logger.warn(`${LOG_PREFIX} s3fs not found, attempting runtime installation...`);
+    logger.info(
+      `${LOG_PREFIX} Tip: For faster startup, use createMountableTemplate() to pre-install s3fs in your sandbox template`
+    );
+    await sandbox.commands.run("sudo apt-get update 2>&1", { timeoutMs: 6e4 });
+    const installResult = await sandbox.commands.run(
+      "sudo apt-get install -y s3fs fuse 2>&1 || sudo apt-get install -y s3fs-fuse fuse 2>&1",
+      { timeoutMs: 12e4 }
+    );
+    if (installResult.exitCode !== 0) {
+      throw new Error(
+        `Failed to install s3fs. For S3 mounting, your template needs s3fs and fuse packages.
+
+Option 1: Use createMountableTemplate() helper:
+  import { E2BSandbox, createMountableTemplate } from '@mastra/e2b';
+  const sandbox = new E2BSandbox({ template: createMountableTemplate() });
+
+Option 2: Customize the base template:
+  new E2BSandbox({ template: base => base.aptInstall(['your-packages']) })
+
+Error details: ${installResult.stderr || installResult.stdout}`
+      );
+    }
+  }
+  const idResult = await sandbox.commands.run("id -u && id -g");
+  const [uid, gid] = idResult.stdout.trim().split("\n");
+  const hasCredentials = config.accessKeyId && config.secretAccessKey;
+  const credentialsPath = "/tmp/.passwd-s3fs";
+  if (!hasCredentials && config.endpoint) {
+    throw new Error(
+      `S3-compatible storage requires credentials. Detected endpoint: ${config.endpoint}. The public_bucket option only works for AWS S3 public buckets, not R2, MinIO, etc.`
+    );
+  }
+  if (hasCredentials) {
+    const credentialsContent = `${config.accessKeyId}:${config.secretAccessKey}`;
+    await sandbox.commands.run(`sudo rm -f ${credentialsPath}`);
+    await sandbox.files.write(credentialsPath, credentialsContent);
+    await sandbox.commands.run(`chmod 600 ${credentialsPath}`);
+  }
+  const mountOptions = [];
+  if (hasCredentials) {
+    mountOptions.push(`passwd_file=${credentialsPath}`);
+  } else {
+    mountOptions.push("public_bucket=1");
+    logger.debug(`${LOG_PREFIX} No credentials provided, mounting as public bucket (read-only)`);
+  }
+  mountOptions.push("allow_other");
+  if (uid && gid) {
+    mountOptions.push(`uid=${uid}`, `gid=${gid}`);
+  }
+  if (config.endpoint) {
+    const endpoint = config.endpoint.replace(/\/$/, "");
+    mountOptions.push(`url=${endpoint}`, "use_path_request_style", "sigv4", "nomultipart");
+  }
+  if (config.readOnly) {
+    mountOptions.push("ro");
+    logger.debug(`${LOG_PREFIX} Mounting as read-only`);
+  }
+  const mountCmd = `sudo s3fs ${config.bucket} ${mountPath} -o ${mountOptions.join(" -o ")}`;
+  logger.debug(`${LOG_PREFIX} Mounting S3:`, hasCredentials ? mountCmd.replace(credentialsPath, "***") : mountCmd);
+  try {
+    const result = await sandbox.commands.run(mountCmd, { timeoutMs: 6e4 });
+    logger.debug(`${LOG_PREFIX} s3fs result:`, {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to mount S3 bucket: ${result.stderr || result.stdout}`);
+    }
+  } catch (error) {
+    const errorObj = error;
+    const stderr = errorObj.result?.stderr || "";
+    const stdout = errorObj.result?.stdout || "";
+    logger.error(`${LOG_PREFIX} s3fs error:`, { stderr, stdout, error: String(error) });
+    throw new Error(`Failed to mount S3 bucket: ${stderr || stdout || error}`);
+  }
+}
+
+// src/sandbox/mounts/gcs.ts
+async function mountGCS(mountPath, config, ctx) {
+  const { sandbox, logger } = ctx;
+  validateBucketName(config.bucket);
+  const checkResult = await sandbox.commands.run('which gcsfuse || echo "not found"');
+  if (checkResult.stdout.includes("not found")) {
+    const codenameResult = await sandbox.commands.run("lsb_release -cs 2>/dev/null || echo jammy");
+    const codename = codenameResult.stdout.trim() || "jammy";
+    await sandbox.commands.run(
+      `curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/gcsfuse.gpg && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-${codename} main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list && sudo apt-get update && sudo apt-get install -y gcsfuse`,
+      { timeoutMs: 12e4 }
+    );
+  }
+  const idResult = await sandbox.commands.run("id -u && id -g");
+  const [uid, gid] = idResult.stdout.trim().split("\n");
+  const uidGidFlags = uid && gid ? `--uid=${uid} --gid=${gid}` : "";
+  const hasCredentials = !!config.serviceAccountKey;
+  let mountCmd;
+  if (hasCredentials) {
+    const keyPath = "/tmp/gcs-key.json";
+    await sandbox.commands.run(`sudo rm -f ${keyPath}`);
+    await sandbox.files.write(keyPath, config.serviceAccountKey);
+    await sandbox.commands.run(`sudo chown root:root ${keyPath} && sudo chmod 600 ${keyPath}`);
+    mountCmd = `sudo gcsfuse --key-file=${keyPath} -o allow_other ${uidGidFlags} ${config.bucket} ${mountPath}`;
+  } else {
+    logger.debug(`${LOG_PREFIX} No credentials provided, mounting GCS as public bucket (read-only)`);
+    mountCmd = `sudo gcsfuse --anonymous-access -o allow_other ${uidGidFlags} ${config.bucket} ${mountPath}`;
+  }
+  logger.debug(`${LOG_PREFIX} Mounting GCS:`, mountCmd);
+  try {
+    const result = await sandbox.commands.run(mountCmd, { timeoutMs: 6e4 });
+    logger.debug(`${LOG_PREFIX} gcsfuse result:`, {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`Failed to mount GCS bucket: ${result.stderr || result.stdout}`);
+    }
+  } catch (error) {
+    const errorObj = error;
+    const stderr = errorObj.result?.stderr || "";
+    const stdout = errorObj.result?.stdout || "";
+    logger.error(`${LOG_PREFIX} gcsfuse error:`, { stderr, stdout, error: String(error) });
+    throw new Error(`Failed to mount GCS bucket: ${stderr || stdout || error}`);
+  }
+}
+
+// src/sandbox/index.ts
+var SAFE_MOUNT_PATH = /^\/[a-zA-Z0-9_.\-/]+$/;
+function validateMountPath(mountPath) {
+  if (!SAFE_MOUNT_PATH.test(mountPath)) {
+    throw new Error(
+      `Invalid mount path: ${mountPath}. Must be an absolute path with alphanumeric, dash, dot, underscore, or slash characters only.`
+    );
+  }
+}
+var SAFE_MARKER_NAME = /^mount-[a-z0-9]+$/;
+var E2BSandbox = class extends workspace.MastraSandbox {
+  id;
+  name = "E2BSandbox";
+  provider = "e2b";
+  // Status is managed by base class lifecycle methods
+  status = "pending";
+  _sandbox = null;
+  _createdAt = null;
+  _isRetrying = false;
+  timeout;
+  templateSpec;
+  env;
+  metadata;
+  configuredRuntimes;
+  connectionOpts;
+  // Non-optional (initialized by BaseSandbox)
+  /** Resolved template ID after building (if needed) */
+  _resolvedTemplateId;
+  /** Promise for template preparation (started in constructor) */
+  _templatePreparePromise;
+  constructor(options = {}) {
+    super({ name: "E2BSandbox", onStart: options.onStart, onStop: options.onStop, onDestroy: options.onDestroy });
+    this.id = options.id ?? this.generateId();
+    this.timeout = options.timeout ?? 3e5;
+    this.templateSpec = options.template;
+    this.env = options.env ?? {};
+    this.metadata = options.metadata ?? {};
+    this.configuredRuntimes = options.runtimes ?? ["node", "python", "bash"];
+    this.connectionOpts = {
+      ...options.domain && { domain: options.domain },
+      ...options.apiUrl && { apiUrl: options.apiUrl },
+      ...options.apiKey && { apiKey: options.apiKey },
+      ...options.accessToken && { accessToken: options.accessToken }
+    };
+    this._templatePreparePromise = this.resolveTemplate().catch((err) => {
+      this.logger.debug(`${LOG_PREFIX} Template preparation error (will retry on start):`, err);
+      return "";
+    });
+  }
+  generateId() {
+    return `e2b-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+  get supportedRuntimes() {
+    return this.configuredRuntimes;
+  }
+  get defaultRuntime() {
+    return this.configuredRuntimes[0] ?? "node";
+  }
+  /**
+   * Get the underlying E2B Sandbox instance for direct access to E2B APIs.
+   *
+   * Use this when you need to access E2B features not exposed through the
+   * WorkspaceSandbox interface (e.g., files API, ports, etc.).
+   *
+   * @throws {SandboxNotReadyError} If the sandbox has not been started
+   *
+   * @example Direct file operations
+   * ```typescript
+   * const e2bSandbox = sandbox.instance;
+   * await e2bSandbox.files.write('/tmp/test.txt', 'Hello');
+   * const content = await e2bSandbox.files.read('/tmp/test.txt');
+   * const files = await e2bSandbox.files.list('/tmp');
+   * ```
+   *
+   * @example Access ports
+   * ```typescript
+   * const e2bSandbox = sandbox.instance;
+   * const url = e2bSandbox.getHost(3000);
+   * ```
+   */
+  get instance() {
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    return this._sandbox;
+  }
+  // ---------------------------------------------------------------------------
+  // Mount Support
+  // ---------------------------------------------------------------------------
+  /**
+   * Mount a filesystem at a path in the sandbox.
+   * Uses FUSE tools (s3fs, gcsfuse) to mount cloud storage.
+   */
+  async mount(filesystem, mountPath) {
+    validateMountPath(mountPath);
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    this.logger.debug(`${LOG_PREFIX} Mounting "${mountPath}"...`);
+    const config = filesystem.getMountConfig?.();
+    if (!config) {
+      const error = `Filesystem "${filesystem.id}" does not provide a mount config`;
+      this.logger.error(`${LOG_PREFIX} ${error}`);
+      this.mounts.set(mountPath, { filesystem, state: "error", error });
+      return { success: false, mountPath, error };
+    }
+    const existingMount = await this.checkExistingMount(mountPath, config);
+    if (existingMount === "matching") {
+      this.logger.debug(
+        `${LOG_PREFIX} Detected existing mount for ${filesystem.provider} ("${filesystem.id}") at "${mountPath}" with correct config, skipping`
+      );
+      this.mounts.set(mountPath, { state: "mounted", config });
+      return { success: true, mountPath };
+    } else if (existingMount === "mismatched") {
+      this.logger.debug(`${LOG_PREFIX} Config mismatch, unmounting to re-mount with new config...`);
+      await this.unmount(mountPath);
+    }
+    this.logger.debug(`${LOG_PREFIX} Config type: ${config.type}`);
+    this.mounts.set(mountPath, { filesystem, state: "mounting", config });
+    try {
+      const checkResult = await this._sandbox.commands.run(
+        `[ -d "${mountPath}" ] && [ "$(ls -A "${mountPath}" 2>/dev/null)" ] && echo "non-empty" || echo "ok"`
+      );
+      if (checkResult.stdout.trim() === "non-empty") {
+        const error = `Cannot mount at ${mountPath}: directory exists and is not empty. Mounting would hide existing files. Use a different path or empty the directory first.`;
+        this.logger.error(`${LOG_PREFIX} ${error}`);
+        this.mounts.set(mountPath, { filesystem, state: "error", config, error });
+        return { success: false, mountPath, error };
+      }
+    } catch {
+    }
+    try {
+      this.logger.debug(`${LOG_PREFIX} Creating mount directory for ${mountPath}...`);
+      const mkdirCommand = `sudo mkdir -p "${mountPath}" && sudo chown $(id -u):$(id -g) "${mountPath}"`;
+      this.logger.debug(`${LOG_PREFIX} Running command: ${mkdirCommand}`);
+      const mkdirResult = await this._sandbox.commands.run(mkdirCommand);
+      this.logger.debug(`${LOG_PREFIX} Created mount directory for mount path "${mountPath}":`, mkdirResult);
+    } catch (mkdirError) {
+      this.logger.debug(`${LOG_PREFIX} mkdir error for "${mountPath}":`, mkdirError);
+      this.mounts.set(mountPath, { filesystem, state: "error", config, error: String(mkdirError) });
+      return { success: false, mountPath, error: String(mkdirError) };
+    }
+    const mountCtx = {
+      sandbox: this._sandbox,
+      logger: this.logger
+    };
+    try {
+      switch (config.type) {
+        case "s3":
+          this.logger.debug(`${LOG_PREFIX} Mounting S3 bucket at ${mountPath}...`);
+          await mountS3(mountPath, config, mountCtx);
+          this.logger.debug(`${LOG_PREFIX} Mounted S3 bucket at ${mountPath}`);
+          break;
+        case "gcs":
+          this.logger.debug(`${LOG_PREFIX} Mounting GCS bucket at ${mountPath}...`);
+          await mountGCS(mountPath, config, mountCtx);
+          this.logger.debug(`${LOG_PREFIX} Mounted GCS bucket at ${mountPath}`);
+          break;
+        default:
+          this.mounts.set(mountPath, {
+            filesystem,
+            state: "unsupported",
+            config,
+            error: `Unsupported mount type: ${config.type}`
+          });
+          return {
+            success: false,
+            mountPath,
+            error: `Unsupported mount type: ${config.type}`
+          };
+      }
+    } catch (error) {
+      this.logger.error(
+        `${LOG_PREFIX} Error mounting "${filesystem.provider}" (${filesystem.id}) at "${mountPath}":`,
+        error
+      );
+      this.mounts.set(mountPath, { filesystem, state: "error", config, error: String(error) });
+      try {
+        await this._sandbox.commands.run(`sudo rmdir "${mountPath}" 2>/dev/null || true`);
+        this.logger.debug(`${LOG_PREFIX} Cleaned up directory after failed mount: ${mountPath}`);
+      } catch {
+      }
+      return { success: false, mountPath, error: String(error) };
+    }
+    this.mounts.set(mountPath, { state: "mounted", config });
+    await this.writeMarkerFile(mountPath);
+    this.logger.debug(`${LOG_PREFIX} Mounted ${mountPath}`);
+    return { success: true, mountPath };
+  }
+  /**
+   * Write marker file for detecting config changes on reconnect.
+   * Stores both the mount path and config hash in the file.
+   */
+  async writeMarkerFile(mountPath) {
+    if (!this._sandbox) return;
+    const markerContent = this.mounts.getMarkerContent(mountPath);
+    if (!markerContent) return;
+    const filename = this.mounts.markerFilename(mountPath);
+    const markerPath = `/tmp/.mastra-mounts/${filename}`;
+    try {
+      await this._sandbox.commands.run("mkdir -p /tmp/.mastra-mounts");
+      await this._sandbox.files.write(markerPath, markerContent);
+    } catch {
+      this.logger.debug(`${LOG_PREFIX} Warning: Could not write marker file at ${markerPath}`);
+    }
+  }
+  /**
+   * Unmount a filesystem from a path in the sandbox.
+   */
+  async unmount(mountPath) {
+    validateMountPath(mountPath);
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    this.logger.debug(`${LOG_PREFIX} Unmounting ${mountPath}...`);
+    try {
+      const result = await this._sandbox.commands.run(
+        `sudo fusermount -u "${mountPath}" 2>/dev/null || sudo umount "${mountPath}"`
+      );
+      if (result.exitCode !== 0) {
+        this.logger.debug(`${LOG_PREFIX} Unmount warning: ${result.stderr || result.stdout}`);
+      }
+    } catch (error) {
+      this.logger.debug(`${LOG_PREFIX} Unmount error:`, error);
+      await this._sandbox.commands.run(`sudo umount -l "${mountPath}" 2>/dev/null || true`);
+    }
+    this.mounts.delete(mountPath);
+    const filename = this.mounts.markerFilename(mountPath);
+    const markerPath = `/tmp/.mastra-mounts/${filename}`;
+    await this._sandbox.commands.run(`rm -f "${markerPath}" 2>/dev/null || true`);
+    const rmdirResult = await this._sandbox.commands.run(`sudo rmdir "${mountPath}" 2>&1`);
+    if (rmdirResult.exitCode === 0) {
+      this.logger.debug(`${LOG_PREFIX} Unmounted and removed ${mountPath}`);
+    } else {
+      this.logger.debug(
+        `${LOG_PREFIX} Unmounted ${mountPath} (directory not removed: ${rmdirResult.stderr?.trim() || "not empty"})`
+      );
+    }
+  }
+  /**
+   * Get list of current mounts in the sandbox.
+   */
+  async getMounts() {
+    return Array.from(this.mounts.entries).map(([path, entry]) => ({
+      path,
+      filesystem: entry.filesystem?.provider ?? entry.config?.type ?? "unknown"
+    }));
+  }
+  /**
+   * Unmount all stale mounts that are not in the expected mounts list.
+   * Also cleans up orphaned directories and marker files from failed mount attempts.
+   * Call this after reconnecting to an existing sandbox to clean up old mounts.
+   */
+  async reconcileMounts(expectedMountPaths) {
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    this.logger.debug(`${LOG_PREFIX} Reconciling mounts. Expected paths:`, expectedMountPaths);
+    const mountsResult = await this._sandbox.commands.run(
+      `grep -E 'fuse\\.(s3fs|gcsfuse)' /proc/mounts | awk '{print $2}'`
+    );
+    const currentMounts = mountsResult.stdout.trim().split("\n").filter((p) => p.length > 0);
+    this.logger.debug(`${LOG_PREFIX} Current FUSE mounts in sandbox:`, currentMounts);
+    const markersResult = await this._sandbox.commands.run(`ls /tmp/.mastra-mounts/ 2>/dev/null || echo ""`);
+    const markerFiles = markersResult.stdout.trim().split("\n").filter((f) => f.length > 0 && SAFE_MARKER_NAME.test(f));
+    const managedMountPaths = /* @__PURE__ */ new Map();
+    for (const markerFile of markerFiles) {
+      const markerResult = await this._sandbox.commands.run(
+        `cat "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null || echo ""`
+      );
+      const parsed = this.mounts.parseMarkerContent(markerResult.stdout.trim());
+      if (parsed && SAFE_MOUNT_PATH.test(parsed.path)) {
+        managedMountPaths.set(parsed.path, markerFile);
+      }
+    }
+    const staleMounts = currentMounts.filter((path) => !expectedMountPaths.includes(path));
+    for (const stalePath of staleMounts) {
+      if (managedMountPaths.has(stalePath)) {
+        this.logger.debug(`${LOG_PREFIX} Found stale managed FUSE mount at ${stalePath}, unmounting...`);
+        await this.unmount(stalePath);
+      } else {
+        this.logger.debug(`${LOG_PREFIX} Found external FUSE mount at ${stalePath}, leaving untouched`);
+      }
+    }
+    try {
+      const expectedMarkerFiles = new Set(expectedMountPaths.map((p) => this.mounts.markerFilename(p)));
+      const markerToPath = /* @__PURE__ */ new Map();
+      for (const [path, file] of managedMountPaths) {
+        markerToPath.set(file, path);
+      }
+      for (const markerFile of markerFiles) {
+        if (!expectedMarkerFiles.has(markerFile)) {
+          const mountPath = markerToPath.get(markerFile);
+          if (mountPath) {
+            if (!currentMounts.includes(mountPath)) {
+              this.logger.debug(`${LOG_PREFIX} Cleaning up orphaned marker and directory for ${mountPath}`);
+              await this._sandbox.commands.run(`rm -f "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null || true`);
+              await this._sandbox.commands.run(`sudo rmdir "${mountPath}" 2>/dev/null || true`);
+            }
+          } else {
+            this.logger.debug(`${LOG_PREFIX} Removing malformed marker file: ${markerFile}`);
+            await this._sandbox.commands.run(`rm -f "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null || true`);
+          }
+        }
+      }
+    } catch {
+      this.logger.debug(`${LOG_PREFIX} Error during orphan cleanup (non-fatal)`);
+    }
+  }
+  /**
+   * Check if a path is already mounted and if the config matches.
+   *
+   * @param mountPath - The mount path to check
+   * @param newConfig - The new config to compare against the stored config
+   * @returns 'not_mounted' | 'matching' | 'mismatched'
+   */
+  async checkExistingMount(mountPath, newConfig) {
+    if (!this._sandbox) throw new workspace.SandboxNotReadyError(this.id);
+    const mountCheck = await this._sandbox.commands.run(
+      `mountpoint -q "${mountPath}" && echo "mounted" || echo "not mounted"`
+    );
+    if (mountCheck.stdout.trim() !== "mounted") {
+      return "not_mounted";
+    }
+    const filename = this.mounts.markerFilename(mountPath);
+    const markerPath = `/tmp/.mastra-mounts/${filename}`;
+    try {
+      const markerResult = await this._sandbox.commands.run(`cat "${markerPath}" 2>/dev/null || echo ""`);
+      const parsed = this.mounts.parseMarkerContent(markerResult.stdout.trim());
+      if (!parsed) {
+        return "mismatched";
+      }
+      const newConfigHash = this.mounts.computeConfigHash(newConfig);
+      this.logger.debug(
+        `${LOG_PREFIX} Marker check - stored hash: "${parsed.configHash}", new config hash: "${newConfigHash}"`
+      );
+      if (parsed.path === mountPath && parsed.configHash === newConfigHash) {
+        return "matching";
+      }
+    } catch {
+    }
+    return "mismatched";
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle (overrides base class protected methods)
+  // ---------------------------------------------------------------------------
+  /**
+   * Start the E2B sandbox.
+   * Handles template preparation, existing sandbox reconnection, and new sandbox creation.
+   *
+   * Status management and mount processing are handled by the base class.
+   */
+  async start() {
+    if (this._sandbox) {
+      return;
+    }
+    const [existingSandbox, templateId] = await Promise.all([
+      this.findExistingSandbox(),
+      this._templatePreparePromise || this.resolveTemplate()
+    ]);
+    if (existingSandbox) {
+      this._sandbox = existingSandbox;
+      this._createdAt = /* @__PURE__ */ new Date();
+      this.logger.debug(`${LOG_PREFIX} Reconnected to existing sandbox for: ${this.id}`);
+      const expectedPaths = Array.from(this.mounts.entries.keys());
+      this.logger.debug(`${LOG_PREFIX} Running mount reconciliation...`);
+      await this.reconcileMounts(expectedPaths);
+      this.logger.debug(`${LOG_PREFIX} Mount reconciliation complete`);
+      return;
+    }
+    let resolvedTemplateId = templateId;
+    if (!resolvedTemplateId) {
+      this.logger.debug(`${LOG_PREFIX} Template preparation failed earlier, retrying...`);
+      resolvedTemplateId = await this.resolveTemplate();
+    }
+    this.logger.debug(`${LOG_PREFIX} Creating new sandbox for: ${this.id} with template: ${resolvedTemplateId}`);
+    try {
+      this._sandbox = await e2b.Sandbox.betaCreate(resolvedTemplateId, {
+        ...this.connectionOpts,
+        autoPause: true,
+        metadata: {
+          ...this.metadata,
+          "mastra-sandbox-id": this.id
+        },
+        timeoutMs: this.timeout
+      });
+    } catch (createError) {
+      const errorStr = String(createError);
+      if (errorStr.includes("404") && errorStr.includes("not found") && !this.templateSpec) {
+        this.logger.debug(`${LOG_PREFIX} Template not found, rebuilding: ${templateId}`);
+        this._resolvedTemplateId = void 0;
+        const rebuiltTemplateId = await this.buildDefaultTemplate();
+        this.logger.debug(`${LOG_PREFIX} Retrying sandbox creation with rebuilt template: ${rebuiltTemplateId}`);
+        this._sandbox = await e2b.Sandbox.betaCreate(rebuiltTemplateId, {
+          ...this.connectionOpts,
+          autoPause: true,
+          metadata: {
+            ...this.metadata,
+            "mastra-sandbox-id": this.id
+          },
+          timeoutMs: this.timeout
+        });
+      } else {
+        throw createError;
+      }
+    }
+    this.logger.debug(`${LOG_PREFIX} Created sandbox ${this._sandbox.sandboxId} for logical ID: ${this.id}`);
+    this._createdAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Build the default mountable template (bypasses exists check).
+   */
+  async buildDefaultTemplate() {
+    const { template, id } = createDefaultMountableTemplate();
+    this.logger.debug(`${LOG_PREFIX} Building default mountable template: ${id}...`);
+    const buildResult = await e2b.Template.build(template, id, this.connectionOpts);
+    this._resolvedTemplateId = buildResult.templateId;
+    this.logger.debug(`${LOG_PREFIX} Template built: ${buildResult.templateId}`);
+    return buildResult.templateId;
+  }
+  /**
+   * Resolve the template specification to a template ID.
+   *
+   * - String: Use as-is (template ID)
+   * - TemplateBuilder: Build and return the template ID
+   * - Function: Apply to base mountable template, then build
+   * - undefined: Use default mountable template (cached)
+   */
+  async resolveTemplate() {
+    if (this._resolvedTemplateId) {
+      return this._resolvedTemplateId;
+    }
+    if (!this.templateSpec) {
+      const { template: template2, id } = createDefaultMountableTemplate();
+      const exists = await e2b.Template.exists(id, this.connectionOpts);
+      if (exists) {
+        this.logger.debug(`${LOG_PREFIX} Using cached mountable template: ${id}`);
+        this._resolvedTemplateId = id;
+        return id;
+      }
+      this.logger.debug(`${LOG_PREFIX} Building default mountable template: ${id}...`);
+      const buildResult2 = await e2b.Template.build(template2, id, this.connectionOpts);
+      this._resolvedTemplateId = buildResult2.templateId;
+      this.logger.debug(`${LOG_PREFIX} Template built and cached: ${buildResult2.templateId}`);
+      return buildResult2.templateId;
+    }
+    if (typeof this.templateSpec === "string") {
+      this._resolvedTemplateId = this.templateSpec;
+      return this.templateSpec;
+    }
+    let template;
+    let templateName;
+    if (typeof this.templateSpec === "function") {
+      const { template: baseTemplate } = createDefaultMountableTemplate();
+      template = this.templateSpec(baseTemplate);
+      templateName = `mastra-custom-${this.id.replace(/[^a-zA-Z0-9-]/g, "-")}`;
+    } else {
+      template = this.templateSpec;
+      templateName = `mastra-${this.id.replace(/[^a-zA-Z0-9-]/g, "-")}`;
+    }
+    this.logger.debug(`${LOG_PREFIX} Building custom template: ${templateName}...`);
+    const buildResult = await e2b.Template.build(template, templateName, this.connectionOpts);
+    this._resolvedTemplateId = buildResult.templateId;
+    this.logger.debug(`${LOG_PREFIX} Template built: ${buildResult.templateId}`);
+    return buildResult.templateId;
+  }
+  /**
+   * Find an existing sandbox with matching mastra-sandbox-id metadata.
+   * Returns the connected sandbox if found, null otherwise.
+   */
+  async findExistingSandbox() {
+    try {
+      const paginator = e2b.Sandbox.list({
+        ...this.connectionOpts,
+        query: {
+          metadata: { "mastra-sandbox-id": this.id },
+          state: ["running", "paused"]
+        }
+      });
+      const sandboxes = await paginator.nextItems();
+      this.logger.debug(`${LOG_PREFIX} sandboxes:`, sandboxes);
+      if (sandboxes.length > 0) {
+        const existingSandbox = sandboxes[0];
+        this.logger.debug(
+          `${LOG_PREFIX} Found existing sandbox for ${this.id}: ${existingSandbox.sandboxId} (state: ${existingSandbox.state})`
+        );
+        return await e2b.Sandbox.connect(existingSandbox.sandboxId, this.connectionOpts);
+      }
+    } catch (e) {
+      this.logger.debug(`${LOG_PREFIX} Error querying for existing sandbox:`, e);
+    }
+    return null;
+  }
+  /**
+   * Stop the E2B sandbox.
+   * Unmounts all filesystems and releases the sandbox reference.
+   * Status management is handled by the base class.
+   */
+  async stop() {
+    for (const mountPath of [...this.mounts.entries.keys()]) {
+      try {
+        await this.unmount(mountPath);
+      } catch {
+      }
+    }
+    this._sandbox = null;
+  }
+  /**
+   * Destroy the E2B sandbox and clean up all resources.
+   * Unmounts filesystems, kills the sandbox, and clears mount state.
+   * Status management is handled by the base class.
+   */
+  async destroy() {
+    for (const mountPath of [...this.mounts.entries.keys()]) {
+      try {
+        await this.unmount(mountPath);
+      } catch {
+      }
+    }
+    if (this._sandbox) {
+      try {
+        await this._sandbox.kill();
+      } catch {
+      }
+    }
+    this._sandbox = null;
+    this.mounts.clear();
+  }
+  /**
+   * Check if the sandbox is ready for operations.
+   */
+  async isReady() {
+    return this.status === "running" && this._sandbox !== null;
+  }
+  /**
+   * Get information about the current state of the sandbox.
+   */
+  async getInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      createdAt: this._createdAt ?? /* @__PURE__ */ new Date(),
+      mounts: Array.from(this.mounts.entries).map(([path, entry]) => ({
+        path,
+        filesystem: entry.filesystem?.provider ?? entry.config?.type ?? "unknown"
+      })),
+      metadata: {
+        ...this.metadata
+      }
+    };
+  }
+  /**
+   * Get instructions describing this E2B sandbox.
+   * Used by agents to understand the execution environment.
+   */
+  getInstructions() {
+    const mountCount = this.mounts.entries.size;
+    const mountInfo = mountCount > 0 ? ` ${mountCount} filesystem(s) mounted via FUSE.` : "";
+    return `Cloud sandbox with /home/user as working directory.${mountInfo}`;
+  }
+  // ---------------------------------------------------------------------------
+  // Internal Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Ensure the sandbox is started and return the E2B Sandbox instance.
+   * Uses base class ensureRunning() for status management and error handling.
+   * @throws {SandboxNotReadyError} if sandbox fails to start
+   */
+  async ensureSandbox() {
+    await this.ensureRunning();
+    return this._sandbox;
+  }
+  /**
+   * Check if an error indicates the sandbox itself is dead/gone.
+   * Does NOT include code execution timeouts (those are the user's code taking too long).
+   * Does NOT include "port is not open" - that needs sandbox kill, not reconnect.
+   */
+  isSandboxDeadError(error) {
+    if (!error) return false;
+    const errorStr = String(error);
+    return errorStr.includes("sandbox was not found") || errorStr.includes("Sandbox is probably not running") || errorStr.includes("Sandbox not found") || errorStr.includes("sandbox has been killed");
+  }
+  /**
+   * Handle sandbox timeout by clearing the instance and resetting state.
+   *
+   * Bypasses the normal stop() lifecycle because the sandbox is already dead —
+   * we can't unmount filesystems or run cleanup commands. Instead we reset
+   * mount states to 'pending' so they get re-mounted when start() runs again.
+   */
+  handleSandboxTimeout() {
+    this._sandbox = null;
+    for (const [path, entry] of this.mounts.entries) {
+      if (entry.state === "mounted" || entry.state === "mounting") {
+        this.mounts.set(path, { state: "pending" });
+      }
+    }
+    this.status = "stopped";
+  }
+  // ---------------------------------------------------------------------------
+  // Command Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a shell command in the sandbox.
+   * Automatically starts the sandbox if not already running.
+   * Retries once if the sandbox is found to be dead.
+   */
+  async executeCommand(command, args = [], options = {}) {
+    this.logger.debug(`${LOG_PREFIX} Executing: ${command} ${args.join(" ")}`, options);
+    const sandbox = await this.ensureSandbox();
+    const startTime = Date.now();
+    const fullCommand = args.length > 0 ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+    this.logger.debug(`${LOG_PREFIX} Executing: ${fullCommand}`);
+    try {
+      const mergedEnv = { ...this.env, ...options.env };
+      const envs = Object.fromEntries(
+        Object.entries(mergedEnv).filter((entry) => entry[1] !== void 0)
+      );
+      const result = await sandbox.commands.run(fullCommand, {
+        cwd: options.cwd,
+        envs,
+        timeoutMs: options.timeout,
+        onStdout: options.onStdout,
+        onStderr: options.onStderr
+      });
+      const executionTimeMs = Date.now() - startTime;
+      this.logger.debug(`${LOG_PREFIX} Exit code: ${result.exitCode} (${executionTimeMs}ms)`);
+      if (result.stdout) this.logger.debug(`${LOG_PREFIX} stdout:
+${result.stdout}`);
+      if (result.stderr) this.logger.debug(`${LOG_PREFIX} stderr:
+${result.stderr}`);
+      return {
+        success: result.exitCode === 0,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        executionTimeMs,
+        command,
+        args
+      };
+    } catch (error) {
+      if (this.isSandboxDeadError(error) && !this._isRetrying) {
+        this.handleSandboxTimeout();
+        this._isRetrying = true;
+        try {
+          return await this.executeCommand(command, args, options);
+        } finally {
+          this._isRetrying = false;
+        }
+      }
+      const executionTimeMs = Date.now() - startTime;
+      const errorObj = error;
+      const stdout = errorObj.result?.stdout || "";
+      const stderr = errorObj.result?.stderr || (error instanceof Error ? error.message : String(error));
+      const exitCode = errorObj.result?.exitCode ?? 1;
+      this.logger.debug(`${LOG_PREFIX} Exit code: ${exitCode} (${executionTimeMs}ms) [error]`);
+      if (stdout) this.logger.debug(`${LOG_PREFIX} stdout:
+${stdout}`);
+      if (stderr) this.logger.debug(`${LOG_PREFIX} stderr:
+${stderr}`);
+      return {
+        success: false,
+        exitCode,
+        stdout,
+        stderr,
+        executionTimeMs,
+        command,
+        args
+      };
+    }
+  }
+};
+
+exports.E2BSandbox = E2BSandbox;
+exports.createDefaultMountableTemplate = createDefaultMountableTemplate;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map