@mastra/daytona 0.0.1 → 0.1.0

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var sdk = require('@daytonaio/sdk');
 var workspace = require('@mastra/core/workspace');
+var crypto = require('crypto');
 
 // src/sandbox/index.ts
 
@@ -16,7 +17,237 @@ function shellQuote(arg) {
   return "'" + arg.replace(/'/g, "'\\''") + "'";
 }
 
-// src/sandbox/process-manager.ts
+// src/sandbox/mounts/types.ts
+var LOG_PREFIX = "[@mastra/daytona]";
+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) {
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new Error(`Invalid endpoint URL: "${endpoint}"`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Invalid endpoint URL scheme: "${parsed.protocol}". Only http: and https: are allowed.`);
+  }
+}
+async function runCommand(sandbox, command, options) {
+  const result = await sandbox.process.executeCommand(
+    command,
+    void 0,
+    // cwd
+    void 0,
+    // env
+    options?.timeout !== void 0 ? Math.ceil(options.timeout / 1e3) : void 0
+  );
+  return {
+    exitCode: result.exitCode,
+    output: result.result ?? ""
+  };
+}
+async function mountS3(mountPath, config, ctx) {
+  const { run, writeFile, logger } = ctx;
+  validateBucketName(config.bucket);
+  if (config.endpoint) {
+    validateEndpoint(config.endpoint);
+  }
+  const quotedMountPath = shellQuote(mountPath);
+  const hasAccessKey = !!config.accessKeyId;
+  const hasSecretKey = !!config.secretAccessKey;
+  if (hasAccessKey !== hasSecretKey) {
+    throw new Error("Both accessKeyId and secretAccessKey must be provided together.");
+  }
+  const hasCredentials = hasAccessKey && hasSecretKey;
+  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 (config.endpoint) {
+    const endpoint = config.endpoint.replace(/\/$/, "");
+    const connectivityCheck = await run(`curl -sS --max-time 5 ${shellQuote(endpoint)} 2>&1`, 1e4);
+    const checkOutput = connectivityCheck.stdout.trim();
+    if (connectivityCheck.exitCode !== 0 || checkOutput.toLowerCase().includes("restricted") || checkOutput.toLowerCase().includes("blocked")) {
+      throw new Error(
+        `Cannot reach ${endpoint} from this sandbox. S3-compatible storage mounting requires network access to the configured endpoint, which may be blocked on Daytona's restricted tiers. Upgrade to a tier with unrestricted internet access, or contact Daytona support to remove the network restriction.` + (checkOutput ? `
+
+Sandbox network response: ${checkOutput}` : "")
+      );
+    }
+  }
+  const checkResult = await run('which s3fs 2>/dev/null || echo "not found"', 3e4);
+  if (checkResult.stdout.includes("not found")) {
+    logger.warn(`${LOG_PREFIX} s3fs not found, attempting runtime installation...`);
+    logger.info(`${LOG_PREFIX} Tip: For faster startup, pre-install s3fs in your sandbox image`);
+    await run("sudo apt-get update -qq 2>&1", 6e4);
+    await run("sudo apt-get install -y s3fs fuse 2>&1 || sudo apt-get install -y s3fs-fuse fuse 2>&1 || true", 12e4);
+    const s3fsCheck = await run('which s3fs 2>/dev/null || echo "not found"', 3e4);
+    if (s3fsCheck.stdout.includes("not found")) {
+      throw new Error("Failed to install s3fs: binary not found after install attempt");
+    }
+  }
+  await run("sudo chmod u+s /usr/bin/fusermount3 /usr/bin/fusermount 2>/dev/null || true", 3e4);
+  const idResult = await run("id -u && id -g", 3e4);
+  const [uid, gid] = idResult.stdout.trim().split("\n");
+  const validUidGid = uid && gid && /^\d+$/.test(uid) && /^\d+$/.test(gid);
+  if (!validUidGid) {
+    logger.warn(
+      `${LOG_PREFIX} Unexpected uid/gid format: "${idResult.stdout.trim()}" \u2014 mounted files will be owned by root`
+    );
+  }
+  const mountHash = crypto.createHash("md5").update(mountPath).digest("hex").slice(0, 8);
+  const credentialsPath = `/tmp/.passwd-s3fs-${mountHash}`;
+  await run(
+    `sudo chmod a+rw /dev/fuse 2>/dev/null || true; sudo bash -c 'grep -q "^user_allow_other" /etc/fuse.conf 2>/dev/null || echo "user_allow_other" >> /etc/fuse.conf' 2>/dev/null || true`
+  );
+  if (hasCredentials) {
+    await run(`sudo rm -f ${shellQuote(credentialsPath)}`, 3e4);
+    await writeFile(credentialsPath, `${config.accessKeyId}:${config.secretAccessKey}`);
+    await run(`chmod 600 ${shellQuote(credentialsPath)}`, 3e4);
+  }
+  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 (validUidGid) {
+    mountOptions.push(`uid=${uid}`, `gid=${gid}`);
+  }
+  if (config.endpoint) {
+    const endpoint = config.endpoint.replace(/\/$/, "");
+    mountOptions.push(`url=${shellQuote(endpoint)}`, "use_path_request_style", "sigv4", "nomultipart");
+  }
+  if (config.readOnly) {
+    mountOptions.push("ro");
+    logger.debug(`${LOG_PREFIX} Mounting as read-only`);
+  }
+  const mountCmd = `s3fs ${shellQuote(config.bucket)} ${quotedMountPath} -o ${mountOptions.join(" -o ")}`;
+  logger.debug(`${LOG_PREFIX} Mounting S3:`, hasCredentials ? mountCmd.replace(credentialsPath, "***") : mountCmd);
+  const result = await run(mountCmd, 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}`);
+  }
+}
+async function mountGCS(mountPath, config, ctx) {
+  const { run, writeFile, logger } = ctx;
+  validateBucketName(config.bucket);
+  const quotedMountPath = shellQuote(mountPath);
+  const connectivityCheck = await run("curl -sS --max-time 5 http://storage.googleapis.com 2>&1", 1e4);
+  const checkOutput = connectivityCheck.stdout.trim();
+  if (connectivityCheck.exitCode !== 0 || checkOutput.toLowerCase().includes("restricted") || checkOutput.toLowerCase().includes("blocked")) {
+    throw new Error(
+      `Cannot reach Google Cloud Storage from this sandbox. GCS mounting requires network access to storage.googleapis.com, which may be blocked on Daytona's restricted tiers. Upgrade to a tier with unrestricted internet access, or contact Daytona support to remove the network restriction.` + (checkOutput ? `
+
+Sandbox network response: ${checkOutput}` : "")
+    );
+  }
+  const checkResult = await run('which gcsfuse 2>/dev/null || echo "not found"', 3e4);
+  if (checkResult.stdout.includes("not found")) {
+    logger.warn(`${LOG_PREFIX} gcsfuse not found, attempting runtime installation...`);
+    logger.info(`${LOG_PREFIX} Tip: For faster startup, pre-install gcsfuse in your sandbox image`);
+    await run("sudo apt-get update -qq 2>&1", 6e4);
+    const prepResult = await run("sudo apt-get install -y curl gnupg 2>&1", 12e4);
+    if (prepResult.exitCode !== 0) {
+      throw new Error(
+        `Failed to install gcsfuse prerequisites (curl, gnupg): ${prepResult.stderr || prepResult.stdout}`
+      );
+    }
+    const distroIdResult = await run(
+      'cat /etc/os-release 2>/dev/null | grep "^ID=" | cut -d= -f2 || echo debian',
+      3e4
+    );
+    const distroId = distroIdResult.stdout.trim().replace(/"/g, "") || "debian";
+    const fallbackCodename = distroId === "ubuntu" ? "jammy" : "bookworm";
+    const codenameResult = await run(
+      `cat /etc/os-release 2>/dev/null | grep "^VERSION_CODENAME=" | cut -d= -f2 || echo ${fallbackCodename}`,
+      3e4
+    );
+    const detectedCodename = codenameResult.stdout.trim() || fallbackCodename;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(detectedCodename)) {
+      throw new Error(`Invalid distro codename for gcsfuse repo: "${detectedCodename}"`);
+    }
+    logger.debug(`${LOG_PREFIX} Detected distro: ${distroId}/${detectedCodename}, fallback: ${fallbackCodename}`);
+    const repoSetup = await run(
+      `sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg -o /tmp/gcsfuse-key.gpg && sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/gcsfuse.gpg /tmp/gcsfuse-key.gpg && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-${detectedCodename} main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list`,
+      3e4
+    );
+    if (repoSetup.exitCode !== 0) {
+      throw new Error(`Failed to set up gcsfuse apt repository: ${repoSetup.stderr || repoSetup.stdout}`);
+    }
+    await run("sudo apt-get update -qq 2>&1 || true", 6e4);
+    let installResult = await run("sudo apt-get install -y gcsfuse 2>&1", 12e4);
+    if (installResult.exitCode !== 0 && detectedCodename !== fallbackCodename) {
+      logger.warn(
+        `${LOG_PREFIX} gcsfuse install failed for "${detectedCodename}", retrying with "${fallbackCodename}" fallback`
+      );
+      await run(
+        `sudo rm -f /etc/apt/sources.list.d/gcsfuse.list && echo "deb [signed-by=/etc/apt/keyrings/gcsfuse.gpg] https://packages.cloud.google.com/apt gcsfuse-${fallbackCodename} main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list`,
+        1e4
+      );
+      await run("sudo apt-get update -qq 2>&1 || true", 6e4);
+      installResult = await run("sudo apt-get install -y gcsfuse 2>&1", 12e4);
+    }
+    const verifyResult = await run('which gcsfuse 2>/dev/null || echo "not found"', 3e4);
+    if (verifyResult.stdout.includes("not found")) {
+      throw new Error(`Failed to install gcsfuse: ${installResult.stderr || installResult.stdout}`);
+    }
+    if (installResult.exitCode !== 0) {
+      logger.warn(
+        `${LOG_PREFIX} gcsfuse install reported dpkg errors (likely fuse post-install in container) but binary is present \u2014 proceeding`
+      );
+    }
+  }
+  const idResult = await run("id -u && id -g", 3e4);
+  const [uid, gid] = idResult.stdout.trim().split("\n");
+  const validUidGid = uid && gid && /^\d+$/.test(uid) && /^\d+$/.test(gid);
+  if (!validUidGid) {
+    logger.warn(
+      `${LOG_PREFIX} Unexpected uid/gid format: "${idResult.stdout.trim()}" \u2014 mounted files will be owned by root`
+    );
+  }
+  const uidGidFlags = validUidGid ? `--uid=${uid} --gid=${gid}` : "";
+  await run(
+    `sudo chmod a+rw /dev/fuse 2>/dev/null || true; sudo bash -c 'grep -q "^user_allow_other" /etc/fuse.conf 2>/dev/null || echo "user_allow_other" >> /etc/fuse.conf' 2>/dev/null || true`
+  );
+  const hasCredentials = !!config.serviceAccountKey;
+  let mountCmd;
+  if (hasCredentials) {
+    const mountHash = crypto.createHash("md5").update(mountPath).digest("hex").slice(0, 8);
+    const keyPath = `/tmp/gcs-key-${mountHash}.json`;
+    await run(`sudo rm -f ${shellQuote(keyPath)}`, 3e4);
+    await writeFile(keyPath, config.serviceAccountKey);
+    await run(`chmod 600 ${shellQuote(keyPath)}`, 3e4);
+    mountCmd = `gcsfuse --key-file=${shellQuote(keyPath)} -o allow_other ${uidGidFlags} ${shellQuote(config.bucket)} ${quotedMountPath}`;
+  } else {
+    logger.debug(`${LOG_PREFIX} No credentials provided, mounting GCS as public bucket (read-only)`);
+    mountCmd = `gcsfuse --anonymous-access -o allow_other ${uidGidFlags} ${shellQuote(config.bucket)} ${quotedMountPath}`;
+  }
+  logger.debug(`${LOG_PREFIX} Mounting GCS:`, mountCmd);
+  const result = await run(mountCmd, 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}`);
+  }
+}
 var DaytonaProcessHandle = class extends workspace.ProcessHandle {
   pid;
   _sessionId;
@@ -195,22 +426,51 @@ function buildSpawnCommand(command, cwd, envs) {
 }
 
 // src/sandbox/index.ts
-var LOG_PREFIX = "[@mastra/daytona]";
+var SAFE_MOUNT_PATH = /^\/[a-zA-Z0-9_.\-/]+$/;
+var MOUNT_COMMAND_TIMEOUT_MS = 3e4;
+function errorToString(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  if (error && typeof error === "object" && "message" in error) {
+    const maybeError = error;
+    if (typeof maybeError.message === "string") {
+      return maybeError.message;
+    }
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+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.`
+    );
+  }
+  const segments = mountPath.split("/");
+  if (mountPath.includes("//") || segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error(`Invalid mount path: ${mountPath}. Path traversal segments are not allowed.`);
+  }
+}
+var SAFE_MARKER_NAME = /^mount-[a-z0-9]+$/;
 var SANDBOX_DEAD_PATTERNS = [
   /sandbox is not running/i,
   /sandbox already destroyed/i,
   /sandbox.*not found/i
 ];
-var DaytonaSandbox = class extends workspace.MastraSandbox {
+var DaytonaSandbox = class _DaytonaSandbox extends workspace.MastraSandbox {
   id;
   name = "DaytonaSandbox";
   provider = "daytona";
+  // Non-optional (initialized by base class when mount() exists)
   status = "pending";
   _daytona = null;
   _sandbox = null;
   _createdAt = null;
-  _isRetrying = false;
   _workingDir = null;
+  _isRetrying = false;
   timeout;
   language;
   resources;
@@ -305,13 +565,16 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
       this._sandbox = existing;
       this._createdAt = existing.createdAt ? new Date(existing.createdAt) : /* @__PURE__ */ new Date();
       this.logger.debug(`${LOG_PREFIX} Reconnected to existing sandbox ${existing.id} 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`);
       await this.detectWorkingDir();
       return;
     }
     this.logger.debug(`${LOG_PREFIX} Creating sandbox for: ${this.id}`);
     const baseParams = compact({
       language: this.language,
-      envVars: this.env,
       labels: { ...this.labels, "mastra-sandbox-id": this.id },
       ephemeral: this.ephemeral,
       autoStopInterval: this.autoStopInterval,
@@ -341,9 +604,15 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
   }
   /**
    * Stop the Daytona sandbox.
-   * Stops the sandbox instance and releases the reference.
+   * Unmounts all filesystems, then stops the sandbox.
    */
   async stop() {
+    for (const mountPath of [...this.mounts.entries.keys()]) {
+      try {
+        await this.unmount(mountPath);
+      } catch {
+      }
+    }
     if (this._sandbox && this._daytona) {
       try {
         await this._daytona.stop(this._sandbox);
@@ -417,7 +686,9 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
    */
   getInstructions() {
     const parts = [];
-    parts.push(`Cloud sandbox with isolated execution (${this.language} runtime).`);
+    const mountCount = this.mounts.entries.size;
+    const mountInfo = mountCount > 0 ? ` ${mountCount} filesystem(s) mounted via FUSE.` : "";
+    parts.push(`Cloud sandbox with isolated execution (${this.language} runtime).${mountInfo}`);
     if (this._workingDir) {
       parts.push(`Default working directory: ${this._workingDir}.`);
     }
@@ -432,17 +703,339 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
     return parts.join(" ");
   }
   // ---------------------------------------------------------------------------
+  // Command Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a command in the sandbox and return the result.
+   */
+  async executeCommand(command, args = [], options = {}) {
+    await this.ensureRunning();
+    const fullCommand = args.length > 0 ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+    const handle = await this.processes.spawn(fullCommand, options);
+    const result = await handle.wait();
+    return { ...result, command, args };
+  }
+  // ---------------------------------------------------------------------------
+  // 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);
+    }
+    const sandbox = this._sandbox;
+    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 at "${mountPath}", unmounting to re-mount with new config...`);
+      await this.unmount(mountPath);
+    } else if (existingMount === "unmanaged") {
+      const error = `Mount path "${mountPath}" is already mounted by an unmanaged source`;
+      this.logger.error(`${LOG_PREFIX} ${error}`);
+      this.mounts.set(mountPath, { filesystem, state: "error", config, error });
+      return { success: false, mountPath, error };
+    }
+    this.mounts.set(mountPath, { filesystem, state: "mounting", config });
+    this.logger.debug(`${LOG_PREFIX} Config type: ${config.type}`);
+    try {
+      const quotedPath = shellQuote(mountPath);
+      const checkResult = await runCommand(
+        sandbox,
+        `[ -d ${quotedPath} ] && ! mountpoint -q ${quotedPath} 2>/dev/null && [ "$(ls -A ${quotedPath} 2>/dev/null)" ] && echo "non-empty" || echo "ok"`,
+        { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+      );
+      if (checkResult.output.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 {
+    }
+    this.logger.debug(`${LOG_PREFIX} Creating mount directory for "${mountPath}"...`);
+    try {
+      const quotedPath = shellQuote(mountPath);
+      const mkdirResult = await runCommand(
+        sandbox,
+        `mountpoint -q ${quotedPath} 2>/dev/null && sudo mount -t tmpfs tmpfs ${quotedPath} 2>/dev/null; sudo mkdir -p ${quotedPath} 2>/dev/null; sudo chown $(id -u):$(id -g) ${quotedPath}`,
+        { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+      );
+      if (mkdirResult.exitCode !== 0) {
+        const error = mkdirResult.output || "Failed to create mount directory";
+        this.logger.debug(`${LOG_PREFIX} mkdir error for "${mountPath}":`, error);
+        this.mounts.set(mountPath, { filesystem, state: "error", config, error });
+        return { success: false, mountPath, error };
+      }
+    } catch (err) {
+      const error = `Failed to create mount directory: ${err}`;
+      this.mounts.set(mountPath, { filesystem, state: "error", config, error });
+      return { success: false, mountPath, error };
+    }
+    const mountCtx = {
+      run: async (cmd, timeoutMs) => {
+        const result = await runCommand(sandbox, cmd, timeoutMs !== void 0 ? { timeout: timeoutMs } : void 0);
+        return {
+          exitCode: result.exitCode,
+          stdout: result.output,
+          stderr: result.exitCode !== 0 ? result.output : ""
+        };
+      },
+      writeFile: async (path, content) => {
+        await sandbox.fs.uploadFile(Buffer.from(content), path);
+      },
+      logger: this.logger
+    };
+    try {
+      switch (config.type) {
+        case "s3":
+          this.logger.debug(`${LOG_PREFIX} Mounting S3 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 at "${mountPath}"...`);
+          await mountGCS(mountPath, config, mountCtx);
+          this.logger.debug(`${LOG_PREFIX} Mounted GCS bucket at ${mountPath}`);
+          break;
+        default: {
+          const error = `Unsupported mount type: ${config.type}`;
+          this.mounts.set(mountPath, { filesystem, state: "unsupported", config, error });
+          return { success: false, mountPath, error };
+        }
+      }
+    } 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: errorToString(error) });
+      await runCommand(sandbox, `sudo rmdir ${shellQuote(mountPath)} 2>/dev/null || true`, {
+        timeout: MOUNT_COMMAND_TIMEOUT_MS
+      });
+      this.logger.debug(`${LOG_PREFIX} Cleaned up directory after failed mount: ${mountPath}`);
+      return { success: false, mountPath, error: errorToString(error) };
+    }
+    this.mounts.set(mountPath, { state: "mounted", config });
+    await this.writeMarkerFile(mountPath);
+    this.logger.debug(`${LOG_PREFIX} Mounted "${mountPath}"`);
+    return { success: true, mountPath };
+  }
+  /**
+   * Unmount a filesystem from a path in the sandbox.
+   */
+  async unmount(mountPath) {
+    validateMountPath(mountPath);
+    if (!this._sandbox) {
+      throw new workspace.SandboxNotReadyError(this.id);
+    }
+    const sandbox = this._sandbox;
+    this.logger.debug(`${LOG_PREFIX} Unmounting "${mountPath}"...`);
+    const quotedPath = shellQuote(mountPath);
+    await runCommand(
+      sandbox,
+      `sudo fusermount -u ${quotedPath} 2>/dev/null; sudo umount -l ${quotedPath} 2>/dev/null; mountpoint -q ${quotedPath} 2>/dev/null && { _p="/tmp/.mastra-defunct-$$"; sudo mkdir -p "$_p" && sudo mount --move ${quotedPath} "$_p" 2>/dev/null; sudo umount -l "$_p" 2>/dev/null; sudo rmdir "$_p" 2>/dev/null; }`,
+      { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+    );
+    this.mounts.delete(mountPath);
+    const markerPath = `/tmp/.mastra-mounts/${this.mounts.markerFilename(mountPath)}`;
+    const rmdirResult = await runCommand(
+      sandbox,
+      `rm -f ${shellQuote(markerPath)} 2>/dev/null; sudo rmdir ${quotedPath} 2>&1`,
+      {
+        timeout: MOUNT_COMMAND_TIMEOUT_MS
+      }
+    );
+    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.output.trim() || "not empty"})`
+      );
+    }
+  }
+  /**
+   * 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) return;
+    const sandbox = this._sandbox;
+    this.logger.debug(`${LOG_PREFIX} Reconciling mounts. Expected paths:`, expectedMountPaths);
+    let currentMounts = [];
+    try {
+      const mountsResult = await runCommand(
+        sandbox,
+        `grep -E 'fuse\\.(s3fs|gcsfuse)' /proc/mounts | awk '{print $2}'`,
+        { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+      );
+      currentMounts = mountsResult.output.trim().split("\n").filter((p) => p.length > 0);
+    } catch (err) {
+      this.logger.debug(`${LOG_PREFIX} Could not read /proc/mounts: ${err}`);
+      return;
+    }
+    this.logger.debug(`${LOG_PREFIX} Current FUSE mounts in sandbox:`, currentMounts);
+    let markerFiles = [];
+    try {
+      const markersResult = await runCommand(sandbox, 'ls /tmp/.mastra-mounts/ 2>/dev/null || echo ""', {
+        timeout: MOUNT_COMMAND_TIMEOUT_MS
+      });
+      markerFiles = markersResult.output.trim().split("\n").filter((f) => f.length > 0 && SAFE_MARKER_NAME.test(f));
+    } catch (err) {
+      this.logger.debug(`${LOG_PREFIX} Could not read marker files: ${err}`);
+    }
+    const managedMountPaths = /* @__PURE__ */ new Map();
+    for (const markerFile of markerFiles) {
+      const markerResult = await runCommand(sandbox, `cat "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null || echo ""`, {
+        timeout: MOUNT_COMMAND_TIMEOUT_MS
+      });
+      const parsed = this.mounts.parseMarkerContent(markerResult.output.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...`);
+        try {
+          await this.unmount(stalePath);
+        } catch (err) {
+          this.logger.debug(`${LOG_PREFIX} Failed to unmount stale mount at "${stalePath}": ${err}`);
+        }
+      } 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 runCommand(
+                sandbox,
+                `rm -f "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null; sudo rmdir ${shellQuote(mountPath)} 2>/dev/null`,
+                { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+              );
+            }
+          } else {
+            this.logger.debug(`${LOG_PREFIX} Removing malformed marker file: ${markerFile}`);
+            await runCommand(sandbox, `rm -f "/tmp/.mastra-mounts/${markerFile}" 2>/dev/null || true`, {
+              timeout: MOUNT_COMMAND_TIMEOUT_MS
+            });
+          }
+        }
+      }
+    } catch {
+      this.logger.debug(`${LOG_PREFIX} Error during orphan cleanup (non-fatal)`);
+    }
+  }
+  /**
+   * 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 runCommand(this._sandbox, "mkdir -p /tmp/.mastra-mounts", { timeout: MOUNT_COMMAND_TIMEOUT_MS });
+      await this._sandbox.fs.uploadFile(Buffer.from(markerContent, "utf-8"), markerPath);
+    } catch {
+      this.logger.debug(`${LOG_PREFIX} Warning: Could not write marker file at ${markerPath}`);
+    }
+  }
+  /**
+   * Check if a path is already mounted and whether 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' | 'unmanaged'
+   */
+  async checkExistingMount(mountPath, newConfig) {
+    if (!this._sandbox) throw new workspace.SandboxNotReadyError(this.id);
+    const sandbox = this._sandbox;
+    try {
+      const mountCheck = await runCommand(
+        sandbox,
+        `mountpoint -q ${shellQuote(mountPath)} && echo "mounted" || echo "not mounted"`,
+        { timeout: MOUNT_COMMAND_TIMEOUT_MS }
+      );
+      if (mountCheck.output.trim() !== "mounted") {
+        return "not_mounted";
+      }
+    } catch {
+      return "not_mounted";
+    }
+    const filename = this.mounts.markerFilename(mountPath);
+    const markerPath = `/tmp/.mastra-mounts/${filename}`;
+    let parsed;
+    try {
+      const markerResult = await runCommand(sandbox, `cat ${shellQuote(markerPath)} 2>/dev/null || echo ""`, {
+        timeout: MOUNT_COMMAND_TIMEOUT_MS
+      });
+      parsed = this.mounts.parseMarkerContent(markerResult.output.trim());
+    } catch {
+      return "unmanaged";
+    }
+    if (!parsed) return "unmanaged";
+    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";
+    }
+    return "mismatched";
+  }
+  // ---------------------------------------------------------------------------
   // Internal Helpers
   // ---------------------------------------------------------------------------
   /**
-   * Detect the actual working directory inside the sandbox via `pwd`.
-   * Stores the result for use in `getInstructions()`.
+   * Try to find and reconnect to an existing Daytona sandbox.
+   *
+   * Uses two strategies:
+   * 1. `get()` by sandbox name — calls the getSandbox API directly, which
+   *    returns sandboxes in ANY state (including stopped). This is the
+   *    primary path and fixes reconnection after stop/start cycles.
+   * 2. `findOne()` by label — falls back to label-based search. Note: the
+   *    SDK's list() API only returns started sandboxes by default (no states
+   *    param in v0.143.0), so this only finds running sandboxes.
+   *
+   * Returns the sandbox if found and usable, or null if a fresh one should
+   * be created.
    */
   async detectWorkingDir() {
     if (!this._sandbox) return;
     try {
-      const result = await this._sandbox.process.executeCommand("pwd");
-      const dir = result.result?.trim();
+      const result = await runCommand(this._sandbox, "pwd", { timeout: MOUNT_COMMAND_TIMEOUT_MS });
+      const dir = result.output?.trim();
       if (dir) {
         this._workingDir = dir;
         this.logger.debug(`${LOG_PREFIX} Detected working directory: ${dir}`);
@@ -451,11 +1044,6 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
       this.logger.debug(`${LOG_PREFIX} Could not detect working directory, will omit from instructions`);
     }
   }
-  /**
-   * Try to find and reconnect to an existing Daytona sandbox with the same
-   * logical ID (via the mastra-sandbox-id label). Returns the sandbox if
-   * found and usable, or null if a fresh sandbox should be created.
-   */
   async findExistingSandbox() {
     const DEAD_STATES = [
       sdk.SandboxState.DESTROYED,
@@ -463,27 +1051,102 @@ var DaytonaSandbox = class extends workspace.MastraSandbox {
       sdk.SandboxState.ERROR,
       sdk.SandboxState.BUILD_FAILED
     ];
-    try {
-      const sandbox = await this._daytona.findOne({ labels: { "mastra-sandbox-id": this.id } });
-      const state = sandbox.state;
-      if (state && DEAD_STATES.includes(state)) {
-        this.logger.debug(
-          `${LOG_PREFIX} Existing sandbox ${sandbox.id} is dead (${state}), deleting and creating fresh`
-        );
-        try {
-          await this._daytona.delete(sandbox);
-        } catch {
+    let sandbox = null;
+    if (this.sandboxName) {
+      try {
+        sandbox = await this._daytona.get(this.sandboxName);
+      } catch (error) {
+        if (error instanceof sdk.DaytonaNotFoundError) ; else if (error instanceof sdk.DaytonaError && (error.statusCode === 401 || error.statusCode === 403)) {
+          throw error;
+        } else {
+          this.logger.debug(`${LOG_PREFIX} Transient error looking up sandbox by name: ${error}`);
+        }
+      }
+    }
+    if (!sandbox) {
+      try {
+        sandbox = await this._daytona.findOne({ labels: { "mastra-sandbox-id": this.id } });
+      } catch (error) {
+        if (error instanceof sdk.DaytonaNotFoundError || error instanceof Error && error.message.includes("No sandbox found")) {
+          return null;
+        }
+        if (error instanceof sdk.DaytonaError && (error.statusCode === 401 || error.statusCode === 403)) {
+          throw error;
         }
+        this.logger.debug(`${LOG_PREFIX} Transient error looking up sandbox by label: ${error}`);
         return null;
       }
-      if (state !== sdk.SandboxState.STARTED) {
-        this.logger.debug(`${LOG_PREFIX} Restarting sandbox ${sandbox.id} (state: ${state})`);
-        await this._daytona.start(sandbox);
+    }
+    const state = sandbox.state;
+    if (state && DEAD_STATES.includes(state)) {
+      this.logger.debug(`${LOG_PREFIX} Existing sandbox ${sandbox.id} is dead (${state}), deleting and creating fresh`);
+      try {
+        await this._daytona.delete(sandbox);
+      } catch {
       }
-      return sandbox;
-    } catch {
       return null;
     }
+    if (state !== sdk.SandboxState.STARTED) {
+      this.logger.debug(`${LOG_PREFIX} Restarting sandbox ${sandbox.id} (state: ${state})`);
+      await this.waitForStableStateAndStart(sandbox);
+    }
+    return sandbox;
+  }
+  /**
+   * Transitional states where the Daytona API will reject start() with
+   * "State change in progress". We poll until the sandbox reaches a stable
+   * state before attempting start().
+   */
+  static TRANSITIONAL_STATES = [
+    sdk.SandboxState.STARTING,
+    sdk.SandboxState.STOPPING,
+    sdk.SandboxState.CREATING,
+    sdk.SandboxState.RESTORING,
+    sdk.SandboxState.ARCHIVING,
+    sdk.SandboxState.RESIZING,
+    sdk.SandboxState.PULLING_SNAPSHOT,
+    sdk.SandboxState.BUILDING_SNAPSHOT
+  ];
+  /**
+   * Wait for the sandbox to leave a transitional state, then start it if needed.
+   * Polls every 2s for up to 120s. If the sandbox reaches STARTED on its own
+   * (e.g. it was STARTING), we skip the start() call. If start() still fails
+   * with "State change in progress", we retry with backoff.
+   */
+  async waitForStableStateAndStart(sandbox) {
+    const MAX_WAIT_MS = 12e4;
+    const POLL_INTERVAL_MS = 2e3;
+    const deadline = Date.now() + MAX_WAIT_MS;
+    let current = sandbox;
+    while (current.state && _DaytonaSandbox.TRANSITIONAL_STATES.includes(current.state) && Date.now() < deadline) {
+      this.logger.debug(`${LOG_PREFIX} Sandbox ${current.id} is in transitional state (${current.state}), waiting...`);
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+      current = await this._daytona.get(current.id);
+    }
+    if (current.state === sdk.SandboxState.STARTED) {
+      Object.assign(sandbox, current);
+      return;
+    }
+    while (Date.now() < deadline) {
+      try {
+        await this._daytona.start(current);
+        return;
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes("State change in progress") && Date.now() < deadline) {
+          this.logger.debug(`${LOG_PREFIX} start() returned "State change in progress", retrying...`);
+          await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+          current = await this._daytona.get(current.id);
+          if (current.state === sdk.SandboxState.STARTED) {
+            Object.assign(sandbox, current);
+            return;
+          }
+          continue;
+        }
+        throw error;
+      }
+    }
+    await this._daytona.start(current);
   }
   /**
    * Check if an error indicates the sandbox is dead/gone.