@mastra/core 1.6.0 → 1.7.0

package/dist/{chunk-AYHSPIT6.cjs → chunk-7UAJ6LMR.cjs}

@@ -10,8 +10,9 @@ var nodePath = require('path');
 var picomatch = require('picomatch');
 var crypto = require('crypto');
 var matter = require('gray-matter');
-var childProcess = require('child_process');
 var os = require('os');
+var childProcess = require('child_process');
+var stream = require('stream');
 var module$1 = require('module');
 var zod = require('zod');
 
@@ -42,8 +43,8 @@ var nodePath__namespace = /*#__PURE__*/_interopNamespace(nodePath);
 var picomatch__default = /*#__PURE__*/_interopDefault(picomatch);
 var crypto__namespace = /*#__PURE__*/_interopNamespace(crypto);
 var matter__default = /*#__PURE__*/_interopDefault(matter);
-var childProcess__namespace = /*#__PURE__*/_interopNamespace(childProcess);
 var os__namespace = /*#__PURE__*/_interopNamespace(os);
+var childProcess__namespace = /*#__PURE__*/_interopNamespace(childProcess);
 
 // src/workspace/errors.ts
 var WorkspaceError = class extends Error {
@@ -479,13 +480,13 @@ var CompositeFilesystem = class {
    * Get instructions describing the mounted filesystems.
    * Used by agents to understand available storage locations.
    */
-  getInstructions() {
+  getInstructions(_opts) {
     const mountDescriptions = Array.from(this._mounts.entries()).map(([mountPath, fs5]) => {
       const name = fs5.displayName || fs5.provider;
       const access2 = fs5.readOnly ? "(read-only)" : "(read-write)";
       return `- ${mountPath}: ${name} ${access2}`;
     }).join("\n");
-    return `Mounted filesystems:
+    return `Filesystem mount points:
 ${mountDescriptions}`;
   }
 };
@@ -657,6 +658,14 @@ var MastraFilesystem = class extends chunkRO47SMI7_cjs.MastraBase {
   async destroy() {
   }
 };
+
+// src/workspace/utils.ts
+function resolveInstructions(override, getDefault, requestContext) {
+  if (typeof override === "string") return override;
+  const defaultInstructions = getDefault();
+  if (override === void 0) return defaultInstructions;
+  return override({ defaultInstructions, requestContext });
+}
 function isEnoentError(error) {
   return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
 }
@@ -797,6 +806,7 @@ var LocalFilesystem = class extends MastraFilesystem {
   _basePath;
   _contained;
   _allowedPaths;
+  _instructionsOverride;
   /**
    * The absolute base path on disk where files are stored.
    * Useful for understanding how workspace paths map to disk paths.
@@ -835,6 +845,7 @@ var LocalFilesystem = class extends MastraFilesystem {
     this._contained = options.contained ?? true;
     this.readOnly = options.readOnly;
     this._allowedPaths = (options.allowedPaths ?? []).map((p) => nodePath__namespace.resolve(p));
+    this._instructionsOverride = options.instructions;
   }
   generateId() {
     return `local-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -1297,7 +1308,10 @@ var LocalFilesystem = class extends MastraFilesystem {
       }
     };
   }
-  getInstructions() {
+  getInstructions(opts) {
+    return resolveInstructions(this._instructionsOverride, () => this._getDefaultInstructions(), opts?.requestContext);
+  }
+  _getDefaultInstructions() {
     const allowedNote = this._allowedPaths.length > 0 ? ` Additionally, the following paths outside basePath are accessible: ${this._allowedPaths.join(", ")}.` : "";
     if (this._contained) {
       return `Local filesystem at "${this.basePath}". Files at workspace path "/foo" are stored at "${this.basePath}/foo" on disk.${allowedNote}`;
@@ -1345,6 +1359,57 @@ var InMemoryFileReadTracker = class {
     return normalized.replace(/\/$/, "") || "/";
   }
 };
+var InMemoryFileWriteLock = class {
+  queues = /* @__PURE__ */ new Map();
+  timeoutMs;
+  constructor(opts) {
+    this.timeoutMs = opts?.timeoutMs ?? 3e4;
+  }
+  get size() {
+    return this.queues.size;
+  }
+  withLock(filePath, fn) {
+    const key = this.normalizePath(filePath);
+    const currentQueue = this.queues.get(key) ?? Promise.resolve();
+    let resolve3;
+    let reject;
+    const resultPromise = new Promise((res, rej) => {
+      resolve3 = res;
+      reject = rej;
+    });
+    const queuePromise = currentQueue.catch(() => {
+    }).then(async () => {
+      let timeoutId;
+      try {
+        const result = await Promise.race([
+          fn(),
+          new Promise((_, rej) => {
+            timeoutId = setTimeout(
+              () => rej(new Error(`write-lock timeout on "${key}" after ${this.timeoutMs}ms`)),
+              this.timeoutMs
+            );
+          })
+        ]);
+        clearTimeout(timeoutId);
+        resolve3(result);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        reject(error);
+      }
+    });
+    this.queues.set(key, queuePromise);
+    void queuePromise.finally(() => {
+      if (this.queues.get(key) === queuePromise) {
+        this.queues.delete(key);
+      }
+    });
+    return resultPromise;
+  }
+  normalizePath(pathStr) {
+    const normalized = nodePath__namespace.posix.normalize(pathStr.replace(/\\/g, "/").replace(/^\/\/+/, "/"));
+    return normalized.replace(/\/+$/, "") || "/";
+  }
+};
 var GLOB_CHARS = /[*?{}[\]]/;
 function isGlobPattern(input) {
   return GLOB_CHARS.test(input);
@@ -1724,8 +1789,16 @@ var MountManager = class {
   }
 };
 
+// src/workspace/sandbox/utils.ts
+function shellQuote(arg) {
+  if (/^[a-zA-Z0-9._\-\/=:@]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
 // src/workspace/sandbox/mastra-sandbox.ts
 var MastraSandbox = class extends chunkRO47SMI7_cjs.MastraBase {
+  /** Process manager */
+  processes;
   /** Mount manager - automatically created if subclass implements mount() */
   mounts;
   // ---------------------------------------------------------------------------
@@ -1752,6 +1825,21 @@ var MastraSandbox = class extends chunkRO47SMI7_cjs.MastraBase {
         logger: this.logger
       });
     }
+    if (options.processes) {
+      const pm = options.processes;
+      pm.sandbox = this;
+      this.processes = pm;
+      if (!this.executeCommand) {
+        this.executeCommand = async (command, args, opts) => {
+          const fullCommand = args?.length ? `${command} ${args.map((a) => shellQuote(a)).join(" ")}` : command;
+          this.logger.debug(`[${this.name}] Executing: ${fullCommand}`, { cwd: opts?.cwd });
+          const handle = await pm.spawn(fullCommand, opts ?? {});
+          const result = await handle.wait();
+          this.logger.debug(`[${this.name}] Exit code: ${result.exitCode} (${result.executionTimeMs}ms)`);
+          return { ...result, command: fullCommand };
+        };
+      }
+    }
   }
   // ---------------------------------------------------------------------------
   // Lifecycle Wrappers (race-condition-safe)
@@ -1838,6 +1926,12 @@ var MastraSandbox = class extends chunkRO47SMI7_cjs.MastraBase {
    * ```
    */
   async ensureRunning() {
+    if (this.status === "destroyed") {
+      throw new SandboxNotReadyError(this.id);
+    }
+    if (this.status === "destroying" || this.status === "stopping") {
+      return;
+    }
     if (this.status !== "running") {
       await this._start();
     }
@@ -1903,6 +1997,10 @@ var MastraSandbox = class extends chunkRO47SMI7_cjs.MastraBase {
     if (this.status === "destroyed") {
       return;
     }
+    if (this.status === "pending") {
+      this.status = "destroyed";
+      return;
+    }
     if (this._startPromise) await this._startPromise.catch(() => {
     });
     if (this._stopPromise) await this._stopPromise.catch(() => {
@@ -3988,6 +4086,25 @@ var Workspace = class {
   getToolsConfig() {
     return this._config.tools;
   }
+  /**
+   * Update the per-tool configuration for this workspace.
+   * Takes effect on the next `createWorkspaceTools()` call.
+   *
+   * @example
+   * ```typescript
+   * // Disable write tools for read-only mode
+   * workspace.setToolsConfig({
+   *   mastra_workspace_write_file: { enabled: false },
+   *   mastra_workspace_edit_file: { enabled: false },
+   * });
+   *
+   * // Re-enable all tools
+   * workspace.setToolsConfig(undefined);
+   * ```
+   */
+  setToolsConfig(config) {
+    this._config.tools = config;
+  }
   /**
    * Access skills stored in this workspace.
    * Skills are SKILL.md files discovered from the configured skillPaths.
@@ -4226,10 +4343,58 @@ var Workspace = class {
     }
     return info;
   }
+  /**
+   * Get human-readable instructions describing the workspace environment.
+   *
+   * When both a sandbox with mounts and a filesystem exist, each mount path
+   * is classified as sandbox-accessible (state === 'mounted') or
+   * workspace-only (pending / mounting / error / unsupported). When there's
+   * no sandbox or no mounts, falls back to provider-level instructions.
+   *
+   * @param opts - Optional options including request context for per-request customisation
+   * @returns Combined instructions string (may be empty)
+   */
+  getInstructions(opts) {
+    const parts = [];
+    const sandboxInstructions = this._sandbox?.getInstructions?.(opts);
+    if (sandboxInstructions) parts.push(sandboxInstructions);
+    const mountEntries = this._sandbox?.mounts?.entries;
+    if (mountEntries && mountEntries.size > 0) {
+      const sandboxAccessible = [];
+      const workspaceOnly = [];
+      for (const [mountPath, entry] of mountEntries) {
+        const fsName = entry.filesystem.displayName || entry.filesystem.provider;
+        const access2 = entry.filesystem.readOnly ? "read-only" : "read-write";
+        if (entry.state === "mounted") {
+          sandboxAccessible.push(`  - ${mountPath}: ${fsName} (${access2})`);
+        } else {
+          workspaceOnly.push(`  - ${mountPath}: ${fsName} (${access2})`);
+        }
+      }
+      if (sandboxAccessible.length) {
+        parts.push(`Sandbox-mounted filesystems (accessible in shell commands):
+${sandboxAccessible.join("\n")}`);
+      }
+      if (workspaceOnly.length) {
+        parts.push(
+          `Workspace-only filesystems (use file tools, NOT available in shell commands):
+${workspaceOnly.join("\n")}`
+        );
+      }
+    } else {
+      const fsInstructions = this._fs?.getInstructions?.(opts);
+      if (fsInstructions) parts.push(fsInstructions);
+    }
+    return parts.join("\n\n");
+  }
   /**
    * Get information about how filesystem and sandbox paths relate.
    * Useful for understanding how to access workspace files from sandbox code.
    *
+   * @deprecated Use {@link getInstructions} instead. `getInstructions()` is
+   * mount-state-aware and feeds into the system message via
+   * `WorkspaceInstructionsProcessor`.
+   *
    * @returns PathContext with paths and instructions from providers
    */
   getPathContext() {
@@ -4265,6 +4430,274 @@ var Workspace = class {
     }
   }
 };
+var ProcessHandle = class {
+  /** The command that was spawned (set by the process manager) */
+  command;
+  /**
+   * Wait for the process to finish and return the result.
+   *
+   * Optionally pass `onStdout`/`onStderr` callbacks to stream output chunks
+   * while waiting. The callbacks are automatically removed when `wait()`
+   * resolves, so there's no cleanup needed by the caller.
+   *
+   * Subclasses implement `wait()` with platform-specific logic — the base
+   * constructor wraps it to handle the optional streaming callbacks.
+   */
+  async wait(_options) {
+    throw new Error(`${this.constructor.name} must implement wait()`);
+  }
+  _stdout = "";
+  _stderr = "";
+  _stdoutListeners = /* @__PURE__ */ new Set();
+  _stderrListeners = /* @__PURE__ */ new Set();
+  _reader;
+  _writer;
+  constructor(options) {
+    if (options?.onStdout) this._stdoutListeners.add(options.onStdout);
+    if (options?.onStderr) this._stderrListeners.add(options.onStderr);
+    const implWait = this.wait.bind(this);
+    this.wait = async (waitOptions) => {
+      if (waitOptions?.onStdout) this._stdoutListeners.add(waitOptions.onStdout);
+      if (waitOptions?.onStderr) this._stderrListeners.add(waitOptions.onStderr);
+      try {
+        return await implWait();
+      } finally {
+        if (waitOptions?.onStdout) this._stdoutListeners.delete(waitOptions.onStdout);
+        if (waitOptions?.onStderr) this._stderrListeners.delete(waitOptions.onStderr);
+      }
+    };
+  }
+  /** Accumulated stdout so far */
+  get stdout() {
+    return this._stdout;
+  }
+  /** Accumulated stderr so far */
+  get stderr() {
+    return this._stderr;
+  }
+  /**
+   * Emit stdout data — accumulates, dispatches to user callback, and pushes to reader stream.
+   * @internal Called by subclasses and process managers to dispatch transport data.
+   */
+  emitStdout(data) {
+    this._stdout += data;
+    for (const listener of this._stdoutListeners) listener(data);
+    this._reader?.push(data);
+  }
+  /**
+   * Emit stderr data — accumulates and dispatches to user callback.
+   * @internal Called by subclasses and process managers to dispatch transport data.
+   */
+  emitStderr(data) {
+    this._stderr += data;
+    for (const listener of this._stderrListeners) listener(data);
+  }
+  /** Readable stream of stdout (for use with StreamMessageReader, pipes, etc.) */
+  get reader() {
+    if (!this._reader) {
+      this._reader = new stream.Readable({ read() {
+      } });
+      void this.wait().then(
+        () => this._reader.push(null),
+        () => this._reader.push(null)
+      );
+    }
+    return this._reader;
+  }
+  /** Writable stream to stdin (for use with StreamMessageWriter, pipes, etc.) */
+  get writer() {
+    if (!this._writer) {
+      this._writer = new stream.Writable({
+        write: (chunk, _encoding, cb) => {
+          this.sendStdin(chunk.toString()).then(() => cb(), cb);
+        }
+      });
+    }
+    return this._writer;
+  }
+};
+
+// src/workspace/sandbox/process-manager/process-manager.ts
+var SandboxProcessManager = class {
+  /**
+   * The sandbox this process manager belongs to.
+   * Set automatically by MastraSandbox when processes are passed into the constructor.
+   * @internal
+   */
+  sandbox;
+  env;
+  /** Tracked process handles keyed by PID. Populated by spawn(), used by get()/kill(). */
+  _tracked = /* @__PURE__ */ new Map();
+  /** PIDs that have been read after exit and should not be re-discovered by subclass fallbacks. */
+  _dismissed = /* @__PURE__ */ new Set();
+  constructor({ env = {} } = {}) {
+    this.env = env;
+    const impl = {
+      spawn: this.spawn.bind(this),
+      list: this.list.bind(this),
+      get: this.get.bind(this)
+    };
+    this.spawn = async (...args) => {
+      await this.sandbox.ensureRunning();
+      const handle = await impl.spawn(...args);
+      handle.command = args[0];
+      return handle;
+    };
+    this.list = async () => {
+      await this.sandbox.ensureRunning();
+      return impl.list();
+    };
+    this.get = async (...args) => {
+      await this.sandbox.ensureRunning();
+      if (this._dismissed.has(args[0])) return void 0;
+      const handle = await impl.get(...args);
+      if (handle?.exitCode !== void 0) {
+        this._tracked.delete(handle.pid);
+        this._dismissed.add(handle.pid);
+      }
+      return handle;
+    };
+  }
+  /** Spawn a process. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async spawn(command, options = {}) {
+    throw new Error(`${this.constructor.name} must implement spawn()`);
+  }
+  /** List all tracked processes. */
+  async list() {
+    throw new Error(`${this.constructor.name} must implement list()`);
+  }
+  /** Get a handle to a process by PID. Subclasses can override for fallback behavior. */
+  async get(pid) {
+    return this._tracked.get(pid);
+  }
+  /** Kill a process by PID. Returns true if killed, false if not found. */
+  async kill(pid) {
+    const handle = await this.get(pid);
+    if (!handle) return false;
+    const killed = await handle.kill();
+    if (killed) {
+      await handle.wait().catch(() => {
+      });
+    }
+    this._tracked.delete(pid);
+    this._dismissed.add(pid);
+    return killed;
+  }
+};
+
+// src/workspace/sandbox/local-process-manager.ts
+var LocalProcessHandle = class extends ProcessHandle {
+  pid;
+  exitCode;
+  proc;
+  waitPromise;
+  startTime;
+  constructor(proc, startTime, options) {
+    super(options);
+    if (!proc.pid) {
+      throw new Error("Process has no PID - it may have failed to spawn");
+    }
+    this.pid = proc.pid;
+    this.proc = proc;
+    this.startTime = startTime;
+    let timedOut = false;
+    const timeoutId = options?.timeout ? setTimeout(() => {
+      timedOut = true;
+      try {
+        process.kill(-this.pid, "SIGTERM");
+      } catch {
+        proc.kill("SIGTERM");
+      }
+    }, options.timeout) : void 0;
+    this.waitPromise = new Promise((resolve3) => {
+      proc.on("close", (code, signal) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (timedOut) {
+          const timeoutMsg = `
+Process timed out after ${options.timeout}ms`;
+          this.emitStderr(timeoutMsg);
+          this.exitCode = 124;
+        } else {
+          this.exitCode = signal && code === null ? 128 : code ?? 0;
+        }
+        resolve3({
+          success: this.exitCode === 0,
+          exitCode: this.exitCode,
+          stdout: this.stdout,
+          stderr: this.stderr,
+          executionTimeMs: Date.now() - this.startTime,
+          killed: signal !== null,
+          timedOut
+        });
+      });
+      proc.on("error", (err) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        this.emitStderr(err.message);
+        this.exitCode = 1;
+        resolve3({
+          success: false,
+          exitCode: 1,
+          stdout: this.stdout,
+          stderr: this.stderr,
+          executionTimeMs: Date.now() - this.startTime
+        });
+      });
+    });
+    proc.stdout?.on("data", (data) => {
+      this.emitStdout(data.toString());
+    });
+    proc.stderr?.on("data", (data) => {
+      this.emitStderr(data.toString());
+    });
+  }
+  async wait() {
+    return this.waitPromise;
+  }
+  async kill() {
+    if (this.exitCode !== void 0) return false;
+    try {
+      process.kill(-this.pid, "SIGKILL");
+      return true;
+    } catch {
+      return this.proc.kill("SIGKILL");
+    }
+  }
+  async sendStdin(data) {
+    if (this.exitCode !== void 0) {
+      throw new Error(`Process ${this.pid} has already exited with code ${this.exitCode}`);
+    }
+    if (!this.proc.stdin) {
+      throw new Error(`Process ${this.pid} does not have stdin available`);
+    }
+    return new Promise((resolve3, reject) => {
+      this.proc.stdin.write(data, (err) => err ? reject(err) : resolve3());
+    });
+  }
+};
+var LocalProcessManager = class extends SandboxProcessManager {
+  async spawn(command, options = {}) {
+    const cwd = options.cwd ?? this.sandbox.workingDirectory;
+    const env = this.sandbox.buildEnv(options.env);
+    const wrapped = this.sandbox.wrapCommandForIsolation(command);
+    const proc = childProcess__namespace.spawn(wrapped.command, wrapped.args, {
+      cwd,
+      env,
+      shell: this.sandbox.isolation === "none",
+      detached: true
+    });
+    const handle = new LocalProcessHandle(proc, Date.now(), options);
+    this._tracked.set(handle.pid, handle);
+    return handle;
+  }
+  async list() {
+    return Array.from(this._tracked.values()).map((handle) => ({
+      pid: handle.pid,
+      running: handle.exitCode === void 0,
+      exitCode: handle.exitCode
+    }));
+  }
+};
 function commandExists(command) {
   try {
     childProcess.execFileSync("which", [command], { stdio: "ignore" });
@@ -4405,10 +4838,10 @@ function generateSeatbeltProfile(workspacePath, config) {
   }
   return lines.join("\n");
 }
-function buildSeatbeltCommand(command, args, profile) {
+function buildSeatbeltCommand(command, profile) {
   return {
     command: "sandbox-exec",
-    args: ["-p", profile, command, ...args]
+    args: ["-p", profile, "sh", "-c", command]
   };
 }
 
@@ -4430,11 +4863,11 @@ var DEFAULT_READONLY_BINDS = [
   "/etc/ld.so.cache",
   "/etc/localtime"
 ];
-function buildBwrapCommand(command, args, workspacePath, config) {
+function buildBwrapCommand(command, workspacePath, config) {
   if (config.bwrapArgs && config.bwrapArgs.length > 0) {
     return {
       command: "bwrap",
-      args: [...config.bwrapArgs, "--", command, ...args]
+      args: [...config.bwrapArgs, "--", "sh", "-c", command]
     };
   }
   const bwrapArgs = [];
@@ -4453,8 +4886,8 @@ function buildBwrapCommand(command, args, workspacePath, config) {
     bwrapArgs.push("--ro-bind", path4, path4);
   }
   if (config.allowSystemBinaries !== false) {
-    const nodePath3 = process.execPath;
-    const nodeDir = nodePath3.substring(0, nodePath3.lastIndexOf("/"));
+    const nodePath4 = process.execPath;
+    const nodeDir = nodePath4.substring(0, nodePath4.lastIndexOf("/"));
     if (!DEFAULT_READONLY_BINDS.some((p) => nodeDir.startsWith(p))) {
       bwrapArgs.push("--ro-bind", nodeDir, nodeDir);
     }
@@ -4467,7 +4900,7 @@ function buildBwrapCommand(command, args, workspacePath, config) {
   }
   bwrapArgs.push("--chdir", workspacePath);
   bwrapArgs.push("--die-with-parent");
-  bwrapArgs.push("--", command, ...args);
+  bwrapArgs.push("--", "sh", "-c", command);
   return {
     command: "bwrap",
     args: bwrapArgs
@@ -4475,141 +4908,59 @@ function buildBwrapCommand(command, args, workspacePath, config) {
 }
 
 // src/workspace/sandbox/native-sandbox/wrapper.ts
-function wrapCommand(command, args, options) {
+function wrapCommand(command, options) {
   switch (options.backend) {
     case "seatbelt": {
       const profile = options.seatbeltProfile ?? generateSeatbeltProfile(options.workspacePath, options.config);
-      return buildSeatbeltCommand(command, args, profile);
+      return buildSeatbeltCommand(command, profile);
     }
     case "bwrap": {
-      return buildBwrapCommand(command, args, options.workspacePath, options.config);
+      return buildBwrapCommand(command, options.workspacePath, options.config);
     }
     case "none":
     default:
-      return { command, args };
+      return { command, args: [] };
   }
 }
 
 // src/workspace/sandbox/local-sandbox.ts
-function execWithStreaming(command, args, options) {
-  const { timeout, onStdout, onStderr, cwd, env, ...spawnOptions } = options;
-  return new Promise((resolve3, reject) => {
-    const proc = childProcess__namespace.spawn(command, args, { cwd, env, ...spawnOptions });
-    let stdout = "";
-    let stderr = "";
-    let killed = false;
-    const timeoutId = timeout ? setTimeout(() => {
-      killed = true;
-      proc.kill("SIGTERM");
-    }, timeout) : void 0;
-    proc.stdout.on("data", (data) => {
-      const str = data.toString();
-      stdout += str;
-      onStdout?.(str);
-    });
-    proc.stderr.on("data", (data) => {
-      const str = data.toString();
-      stderr += str;
-      onStderr?.(str);
-    });
-    proc.on("error", (err) => {
-      if (timeoutId) clearTimeout(timeoutId);
-      const errorMsg = err.message;
-      stderr += errorMsg;
-      onStderr?.(errorMsg);
-      reject(err);
-    });
-    proc.on("close", (code, signal) => {
-      if (timeoutId) clearTimeout(timeoutId);
-      if (killed) {
-        const timeoutMsg = `
-Process timed out after ${timeout}ms`;
-        onStderr?.(timeoutMsg);
-        resolve3({ stdout, stderr: stderr + timeoutMsg, exitCode: 124 });
-      } else if (signal) {
-        const signalMsg = `
-Process terminated by ${signal}`;
-        onStderr?.(signalMsg);
-        resolve3({ stdout, stderr: stderr + signalMsg, exitCode: 128 });
-      } else {
-        resolve3({ stdout, stderr, exitCode: code ?? 0 });
-      }
-    });
-  });
-}
 var LocalSandbox = class extends MastraSandbox {
   id;
   name = "LocalSandbox";
   provider = "local";
   status = "pending";
-  _workingDirectory;
+  workingDirectory;
+  isolation;
   env;
-  timeout;
-  _isolation;
   _nativeSandboxConfig;
   _seatbeltProfile;
   _seatbeltProfilePath;
   _sandboxFolderPath;
   _userProvidedProfilePath = false;
   _createdAt;
-  /**
-   * The working directory where commands are executed.
-   */
-  get workingDirectory() {
-    return this._workingDirectory;
-  }
-  /**
-   * The isolation backend being used.
-   */
-  get isolation() {
-    return this._isolation;
-  }
-  /**
-   * Detect the best available isolation backend for this platform.
-   * Returns detection result with backend recommendation and availability.
-   *
-   * @example
-   * ```typescript
-   * const result = LocalSandbox.detectIsolation();
-   * const sandbox = new LocalSandbox({
-   *   isolation: result.available ? result.backend : 'none',
-   * });
-   * ```
-   */
-  static detectIsolation() {
-    return detectIsolation();
-  }
+  _instructionsOverride;
   constructor(options = {}) {
-    super({ ...options, name: "LocalSandbox" });
-    this.id = options.id ?? this.generateId();
-    this._createdAt = /* @__PURE__ */ new Date();
-    this._workingDirectory = options.workingDirectory ?? nodePath__namespace.join(process.cwd(), ".sandbox");
-    this.env = options.env ?? {};
-    this.timeout = options.timeout;
-    this._nativeSandboxConfig = options.nativeSandbox ?? {};
     const requestedIsolation = options.isolation ?? "none";
     if (requestedIsolation !== "none" && !isIsolationAvailable(requestedIsolation)) {
       const detection = detectIsolation();
       throw new IsolationUnavailableError(requestedIsolation, detection.message);
     }
-    this._isolation = requestedIsolation;
-  }
-  generateId() {
-    return `local-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  }
-  /**
-   * Build the environment object for execution.
-   * Always includes PATH by default (needed for finding executables).
-   * Merges the sandbox's configured env with any additional env from the command.
-   */
-  buildEnv(additionalEnv) {
-    return {
-      PATH: process.env.PATH,
-      // Always include PATH for finding executables
-      ...this.env,
-      ...additionalEnv
-    };
+    super({
+      ...options,
+      name: "LocalSandbox",
+      processes: new LocalProcessManager({ env: options.env ?? {} })
+    });
+    this.id = options.id ?? this.generateId();
+    this._createdAt = /* @__PURE__ */ new Date();
+    this.workingDirectory = options.workingDirectory ?? nodePath__namespace.join(process.cwd(), ".sandbox");
+    this.env = options.env ?? {};
+    this._nativeSandboxConfig = options.nativeSandbox ?? {};
+    this.isolation = requestedIsolation;
+    this._instructionsOverride = options.instructions;
   }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
   /**
    * Start the local sandbox.
    * Creates working directory and sets up seatbelt profile if using macOS isolation.
@@ -4617,11 +4968,11 @@ var LocalSandbox = class extends MastraSandbox {
    */
   async start() {
     this.logger.debug("[LocalSandbox] Starting sandbox", {
-      workingDirectory: this._workingDirectory,
-      isolation: this._isolation
+      workingDirectory: this.workingDirectory,
+      isolation: this.isolation
     });
     await fs2__namespace.mkdir(this.workingDirectory, { recursive: true });
-    if (this._isolation === "seatbelt") {
+    if (this.isolation === "seatbelt") {
       const userProvidedPath = this._nativeSandboxConfig.seatbeltProfilePath;
       if (userProvidedPath) {
         this._seatbeltProfilePath = userProvidedPath;
@@ -4645,14 +4996,14 @@ var LocalSandbox = class extends MastraSandbox {
         await fs2__namespace.writeFile(this._seatbeltProfilePath, this._seatbeltProfile, "utf-8");
       }
     }
-    this.logger.debug("[LocalSandbox] Sandbox started", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Sandbox started", { workingDirectory: this.workingDirectory });
   }
   /**
    * Stop the local sandbox.
    * Status management is handled by the base class.
    */
   async stop() {
-    this.logger.debug("[LocalSandbox] Stopping sandbox", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Stopping sandbox", { workingDirectory: this.workingDirectory });
   }
   /**
    * Destroy the local sandbox and clean up resources.
@@ -4660,7 +5011,9 @@ var LocalSandbox = class extends MastraSandbox {
    * Status management is handled by the base class.
    */
   async destroy() {
-    this.logger.debug("[LocalSandbox] Destroying sandbox", { workingDirectory: this._workingDirectory });
+    this.logger.debug("[LocalSandbox] Destroying sandbox", { workingDirectory: this.workingDirectory });
+    const procs = await this.processes.list();
+    await Promise.all(procs.map((p) => this.processes.kill(p.pid)));
     if (this._seatbeltProfilePath && !this._userProvidedProfilePath) {
       try {
         await fs2__namespace.unlink(this._seatbeltProfilePath);
@@ -4678,6 +5031,7 @@ var LocalSandbox = class extends MastraSandbox {
       this._sandboxFolderPath = void 0;
     }
   }
+  /** @deprecated Use `status === 'running'` instead. */
   async isReady() {
     return this.status === "running";
   }
@@ -4696,8 +5050,8 @@ var LocalSandbox = class extends MastraSandbox {
         workingDirectory: this.workingDirectory,
         platform: os__namespace.platform(),
         nodeVersion: process.version,
-        isolation: this._isolation,
-        isolationConfig: this._isolation !== "none" ? {
+        isolation: this.isolation,
+        isolationConfig: this.isolation !== "none" ? {
           allowNetwork: this._nativeSandboxConfig.allowNetwork ?? false,
           readOnlyPaths: this._nativeSandboxConfig.readOnlyPaths,
           readWritePaths: this._nativeSandboxConfig.readWritePaths
@@ -4705,63 +5059,61 @@ var LocalSandbox = class extends MastraSandbox {
       }
     };
   }
-  getInstructions() {
-    if (this.workingDirectory) {
-      return `Local command execution. Working directory: "${this.workingDirectory}".`;
-    }
-    return "Local command execution on the host machine.";
+  getInstructions(opts) {
+    return resolveInstructions(this._instructionsOverride, () => this._getDefaultInstructions(), opts?.requestContext);
+  }
+  _getDefaultInstructions() {
+    return `Local command execution. Working directory: "${this.workingDirectory}".`;
+  }
+  // ---------------------------------------------------------------------------
+  // Internal Utils
+  // ---------------------------------------------------------------------------
+  generateId() {
+    return `local-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+  /**
+   * Build the environment object for execution.
+   * Always includes PATH by default (needed for finding executables).
+   * Merges the sandbox's configured env with any additional env from the command.
+   * @internal Used by LocalProcessManager.
+   */
+  buildEnv(additionalEnv) {
+    return {
+      PATH: process.env.PATH,
+      // Always include PATH for finding executables
+      ...this.env,
+      ...additionalEnv
+    };
   }
   /**
    * Wrap a command with the configured isolation backend.
+   * @internal Used by LocalProcessManager for background process isolation.
    */
-  wrapCommandForIsolation(command, args) {
-    if (this._isolation === "none") {
-      return { command, args };
+  wrapCommandForIsolation(command) {
+    if (this.isolation === "none") {
+      return { command, args: [] };
     }
-    return wrapCommand(command, args, {
-      backend: this._isolation,
+    return wrapCommand(command, {
+      backend: this.isolation,
       workspacePath: this.workingDirectory,
       seatbeltProfile: this._seatbeltProfile,
       config: this._nativeSandboxConfig
     });
   }
-  async executeCommand(command, args = [], options = {}) {
-    this.logger.debug("[LocalSandbox] Executing command", { command, args, cwd: options.cwd ?? this.workingDirectory });
-    await this.ensureRunning();
-    const startTime = Date.now();
-    const wrapped = this.wrapCommandForIsolation(command, args);
-    try {
-      const result = await execWithStreaming(wrapped.command, wrapped.args, {
-        cwd: options.cwd ?? this.workingDirectory,
-        timeout: options.timeout ?? this.timeout ?? 3e4,
-        env: this.buildEnv(options.env),
-        onStdout: options.onStdout,
-        onStderr: options.onStderr
-      });
-      const commandResult = {
-        success: result.exitCode === 0,
-        stdout: result.stdout,
-        stderr: result.stderr,
-        exitCode: result.exitCode,
-        executionTimeMs: Date.now() - startTime
-      };
-      this.logger.debug("[LocalSandbox] Command completed", {
-        command,
-        exitCode: commandResult.exitCode,
-        executionTimeMs: commandResult.executionTimeMs
-      });
-      return commandResult;
-    } catch (error) {
-      const executionTimeMs = Date.now() - startTime;
-      this.logger.error("[LocalSandbox] Command failed", { command, error, executionTimeMs });
-      return {
-        success: false,
-        stdout: "",
-        stderr: error instanceof Error ? error.message : String(error),
-        exitCode: 1,
-        executionTimeMs
-      };
-    }
+  /**
+   * Detect the best available isolation backend for this platform.
+   * Returns detection result with backend recommendation and availability.
+   *
+   * @example
+   * ```typescript
+   * const result = LocalSandbox.detectIsolation();
+   * const sandbox = new LocalSandbox({
+   *   isolation: result.available ? result.backend : 'none',
+   * });
+   * ```
+   */
+  static detectIsolation() {
+    return detectIsolation();
   }
 };
 
@@ -4780,7 +5132,9 @@ var WORKSPACE_TOOLS = {
     AST_EDIT: `${WORKSPACE_TOOLS_PREFIX}_ast_edit`
   },
   SANDBOX: {
-    EXECUTE_COMMAND: `${WORKSPACE_TOOLS_PREFIX}_execute_command`
+    EXECUTE_COMMAND: `${WORKSPACE_TOOLS_PREFIX}_execute_command`,
+    GET_PROCESS_OUTPUT: `${WORKSPACE_TOOLS_PREFIX}_get_process_output`,
+    KILL_PROCESS: `${WORKSPACE_TOOLS_PREFIX}_kill_process`
   },
   SEARCH: {
     SEARCH: `${WORKSPACE_TOOLS_PREFIX}_search`,
@@ -4849,7 +5203,7 @@ function isAstGrepAvailable() {
     return astGrepModule !== null;
   }
   try {
-    const req = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-AYHSPIT6.cjs', document.baseURI).href)));
+    const req = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-7UAJ6LMR.cjs', document.baseURI).href)));
     req.resolve("@ast-grep/napi");
     return true;
   } catch {
@@ -5193,81 +5547,144 @@ Usage:
     }
   }
 });
-var executeCommandTool = chunkEAZ6YDCQ_cjs.createTool({
-  id: WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND,
-  description: `Execute a shell command in the workspace sandbox.
 
-Usage:
-- Verify parent directories exist before running commands that create files or directories.
-- Always quote file paths that contain spaces (e.g., cd "/path/with spaces").
-- Use the timeout parameter to limit execution time. Behavior when omitted depends on the sandbox provider.
-- Optionally use cwd to override the working directory. Commands run from the sandbox default if omitted.`,
-  inputSchema: zod.z.object({
-    command: zod.z.string().describe('The command to execute (e.g., "ls", "npm", "python")'),
-    args: zod.z.array(zod.z.string()).nullish().default([]).describe("Arguments to pass to the command"),
-    timeout: zod.z.number().nullish().describe("Maximum execution time in milliseconds. Example: 60000 for 1 minute."),
-    cwd: zod.z.string().nullish().describe("Working directory for the command")
-  }),
-  execute: async ({ command, args, timeout, cwd }, context) => {
-    const { sandbox } = requireSandbox(context);
-    if (!sandbox.executeCommand) {
-      throw new SandboxFeatureNotSupportedError("executeCommand");
+// src/workspace/tools/output-helpers.ts
+var DEFAULT_TAIL_LINES = 200;
+var MAX_OUTPUT_CHARS = 3e4;
+function applyTail(output, tail) {
+  if (!output) return output;
+  const n = Math.abs(tail ?? DEFAULT_TAIL_LINES);
+  if (n === 0) return output;
+  const trailingNewline = output.endsWith("\n");
+  const lines = (trailingNewline ? output.slice(0, -1) : output).split("\n");
+  if (lines.length <= n) return output;
+  const sliced = lines.slice(-n).join("\n");
+  const body = trailingNewline ? sliced + "\n" : sliced;
+  return `[showing last ${n} of ${lines.length} lines]
+${body}`;
+}
+function applyCharLimit(output, limit = MAX_OUTPUT_CHARS) {
+  if (!output || output.length <= limit) return output;
+  const truncated = output.slice(-limit);
+  return `[output truncated: showing last ${limit} of ${output.length} characters]
+${truncated}`;
+}
+function truncateOutput(output, tail, charLimit) {
+  return applyCharLimit(applyTail(output, tail), charLimit);
+}
+
+// src/workspace/tools/execute-command.ts
+var executeCommandInputSchema = zod.z.object({
+  command: zod.z.string().describe('The shell command to execute (e.g., "npm install", "ls -la src/", "cat file.txt | grep error")'),
+  timeout: zod.z.number().nullish().describe("Maximum execution time in milliseconds. Example: 60000 for 1 minute."),
+  cwd: zod.z.string().nullish().describe("Working directory for the command"),
+  tail: zod.z.number().nullish().describe(
+    `For foreground commands: limit output to the last N lines, similar to tail -n. Defaults to ${DEFAULT_TAIL_LINES}. Use 0 for no limit.`
+  )
+});
+var executeCommandWithBackgroundSchema = executeCommandInputSchema.extend({
+  background: zod.z.boolean().optional().describe(
+    "Run the command in the background. Returns a PID immediately instead of waiting for completion. Use get_process_output to check on it later."
+  )
+});
+async function executeCommand(input, context) {
+  const { command, timeout, cwd, tail } = input;
+  const background = input.background;
+  const { sandbox } = requireSandbox(context);
+  await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND);
+  const toolCallId = context?.agent?.toolCallId;
+  if (background) {
+    if (!sandbox.processes) {
+      throw new SandboxFeatureNotSupportedError("processes");
     }
-    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND);
-    const toolCallId = context?.agent?.toolCallId;
-    const startedAt = Date.now();
-    let stdout = "";
-    let stderr = "";
-    try {
-      const result = await sandbox.executeCommand(command, args ?? [], {
-        timeout: timeout ?? void 0,
-        cwd: cwd ?? void 0,
-        onStdout: async (data) => {
-          stdout += data;
-          await context?.writer?.custom({
-            type: "data-sandbox-stdout",
-            data: { output: data, timestamp: Date.now(), toolCallId }
-          });
-        },
-        onStderr: async (data) => {
-          stderr += data;
-          await context?.writer?.custom({
-            type: "data-sandbox-stderr",
-            data: { output: data, timestamp: Date.now(), toolCallId }
-          });
-        }
-      });
-      await context?.writer?.custom({
-        type: "data-sandbox-exit",
-        data: {
-          exitCode: result.exitCode,
-          success: result.success,
-          executionTimeMs: result.executionTimeMs,
-          toolCallId
-        }
-      });
-      if (!result.success) {
-        const parts = [result.stdout, result.stderr].filter(Boolean);
-        parts.push(`Exit code: ${result.exitCode}`);
-        return parts.join("\n");
+    const handle = await sandbox.processes.spawn(command, {
+      cwd: cwd ?? void 0,
+      timeout: timeout ?? void 0
+    });
+    return `Started background process (PID: ${handle.pid})`;
+  }
+  if (!sandbox.executeCommand) {
+    throw new SandboxFeatureNotSupportedError("executeCommand");
+  }
+  const startedAt = Date.now();
+  let stdout = "";
+  let stderr = "";
+  try {
+    const result = await sandbox.executeCommand(command, [], {
+      timeout: timeout ?? void 0,
+      cwd: cwd ?? void 0,
+      onStdout: async (data) => {
+        stdout += data;
+        await context?.writer?.custom({
+          type: "data-sandbox-stdout",
+          data: { output: data, timestamp: Date.now(), toolCallId }
+        });
+      },
+      onStderr: async (data) => {
+        stderr += data;
+        await context?.writer?.custom({
+          type: "data-sandbox-stderr",
+          data: { output: data, timestamp: Date.now(), toolCallId }
+        });
       }
-      return result.stdout || "(no output)";
-    } catch (error) {
-      await context?.writer?.custom({
-        type: "data-sandbox-exit",
-        data: {
-          exitCode: -1,
-          success: false,
-          executionTimeMs: Date.now() - startedAt,
-          toolCallId
-        }
-      });
-      const parts = [stdout, stderr].filter(Boolean);
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      parts.push(`Error: ${errorMessage}`);
+    });
+    await context?.writer?.custom({
+      type: "data-sandbox-exit",
+      data: {
+        exitCode: result.exitCode,
+        success: result.success,
+        executionTimeMs: result.executionTimeMs,
+        toolCallId
+      }
+    });
+    if (!result.success) {
+      const parts = [truncateOutput(result.stdout, tail), truncateOutput(result.stderr, tail)].filter(Boolean);
+      parts.push(`Exit code: ${result.exitCode}`);
       return parts.join("\n");
     }
+    return truncateOutput(result.stdout, tail) || "(no output)";
+  } catch (error) {
+    await context?.writer?.custom({
+      type: "data-sandbox-exit",
+      data: {
+        exitCode: -1,
+        success: false,
+        executionTimeMs: Date.now() - startedAt,
+        toolCallId
+      }
+    });
+    const parts = [truncateOutput(stdout, tail), truncateOutput(stderr, tail)].filter(Boolean);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    parts.push(`Error: ${errorMessage}`);
+    return parts.join("\n");
   }
+}
+var baseDescription = `Execute a shell command in the workspace sandbox.
+
+Examples:
+  "npm install && npm run build"
+  "ls -la src/"
+  "cat config.json | jq '.database'"
+  "cd /app && python main.py"
+
+Usage:
+- Commands run in a shell, so pipes, redirects, and chaining (&&, ||, ;) all work.
+- Always quote file paths that contain spaces (e.g., cd "/path/with spaces").
+- Use the timeout parameter to limit execution time. Behavior when omitted depends on the sandbox provider.
+- Optionally use cwd to override the working directory. Commands run from the sandbox default if omitted.`;
+var executeCommandTool = chunkEAZ6YDCQ_cjs.createTool({
+  id: WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND,
+  description: baseDescription,
+  inputSchema: executeCommandInputSchema,
+  execute: executeCommand
+});
+var executeCommandWithBackgroundTool = chunkEAZ6YDCQ_cjs.createTool({
+  id: WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND,
+  description: `${baseDescription}
+
+Set background: true to run long-running commands (dev servers, watchers) without blocking. You'll get a PID to track the process.`,
+  inputSchema: executeCommandWithBackgroundSchema,
+  execute: executeCommand
 });
 var fileStatTool = chunkEAZ6YDCQ_cjs.createTool({
   id: WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT,
@@ -5293,6 +5710,82 @@ var fileStatTool = chunkEAZ6YDCQ_cjs.createTool({
     }
   }
 });
+var getProcessOutputTool = chunkEAZ6YDCQ_cjs.createTool({
+  id: WORKSPACE_TOOLS.SANDBOX.GET_PROCESS_OUTPUT,
+  description: `Get the current output (stdout, stderr) and status of a background process by its PID.
+
+Use this after starting a background command with execute_command (background: true) to check if the process is still running and read its output.`,
+  inputSchema: zod.z.object({
+    pid: zod.z.number().describe("The process ID returned when the background command was started"),
+    tail: zod.z.number().optional().describe(
+      `Number of lines to return, similar to tail -n. Positive or negative returns last N lines from end. Defaults to ${DEFAULT_TAIL_LINES}. Use 0 for no limit.`
+    ),
+    wait: zod.z.boolean().optional().describe(
+      "If true, block until the process exits and return the final output. Useful for short-lived background commands where you want to wait for the result."
+    )
+  }),
+  execute: async ({ pid, tail, wait: shouldWait }, context) => {
+    const { sandbox } = requireSandbox(context);
+    if (!sandbox.processes) {
+      throw new SandboxFeatureNotSupportedError("processes");
+    }
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.GET_PROCESS_OUTPUT);
+    const toolCallId = context?.agent?.toolCallId;
+    const handle = await sandbox.processes.get(pid);
+    if (!handle) {
+      return `No background process found with PID ${pid}.`;
+    }
+    if (handle.command) {
+      await context?.writer?.custom({
+        type: "data-sandbox-command",
+        data: { command: handle.command, pid, toolCallId }
+      });
+    }
+    if (shouldWait && handle.exitCode === void 0) {
+      const result = await handle.wait({
+        onStdout: context?.writer ? async (data) => {
+          await context.writer.custom({
+            type: "data-sandbox-stdout",
+            data: { output: data, timestamp: Date.now(), toolCallId }
+          });
+        } : void 0,
+        onStderr: context?.writer ? async (data) => {
+          await context.writer.custom({
+            type: "data-sandbox-stderr",
+            data: { output: data, timestamp: Date.now(), toolCallId }
+          });
+        } : void 0
+      });
+      await context?.writer?.custom({
+        type: "data-sandbox-exit",
+        data: {
+          exitCode: result.exitCode,
+          success: result.success,
+          executionTimeMs: result.executionTimeMs,
+          toolCallId
+        }
+      });
+    }
+    const running = handle.exitCode === void 0;
+    const stdout = truncateOutput(handle.stdout, tail);
+    const stderr = truncateOutput(handle.stderr, tail);
+    if (!stdout && !stderr) {
+      return "(no output yet)";
+    }
+    const parts = [];
+    if (stdout && stderr) {
+      parts.push("stdout:", stdout, "", "stderr:", stderr);
+    } else if (stdout) {
+      parts.push(stdout);
+    } else {
+      parts.push("stderr:", stderr);
+    }
+    if (!running) {
+      parts.push("", `Exit code: ${handle.exitCode}`);
+    }
+    return parts.join("\n");
+  }
+});
 var grepTool = chunkEAZ6YDCQ_cjs.createTool({
   id: WORKSPACE_TOOLS.FILESYSTEM.GREP,
   description: `Search file contents using a regex pattern. Walks the filesystem and returns matching lines with file paths and line numbers.
@@ -5449,6 +5942,55 @@ var indexContentTool = chunkEAZ6YDCQ_cjs.createTool({
     return `Indexed ${path4}`;
   }
 });
+var KILL_TAIL_LINES = 50;
+var killProcessTool = chunkEAZ6YDCQ_cjs.createTool({
+  id: WORKSPACE_TOOLS.SANDBOX.KILL_PROCESS,
+  description: `Kill a background process by its PID.
+
+Use this to stop a long-running background process that was started with execute_command (background: true). Returns the last ${KILL_TAIL_LINES} lines of output.`,
+  inputSchema: zod.z.object({
+    pid: zod.z.number().describe("The process ID of the background process to kill")
+  }),
+  execute: async ({ pid }, context) => {
+    const { sandbox } = requireSandbox(context);
+    if (!sandbox.processes) {
+      throw new SandboxFeatureNotSupportedError("processes");
+    }
+    await emitWorkspaceMetadata(context, WORKSPACE_TOOLS.SANDBOX.KILL_PROCESS);
+    const toolCallId = context?.agent?.toolCallId;
+    const handle = await sandbox.processes.get(pid);
+    if (handle?.command) {
+      await context?.writer?.custom({
+        type: "data-sandbox-command",
+        data: { command: handle.command, pid, toolCallId }
+      });
+    }
+    const killed = await sandbox.processes.kill(pid);
+    if (!killed) {
+      await context?.writer?.custom({
+        type: "data-sandbox-exit",
+        data: { exitCode: handle?.exitCode ?? -1, success: false, killed: false, toolCallId }
+      });
+      return `Process ${pid} was not found or had already exited.`;
+    }
+    await context?.writer?.custom({
+      type: "data-sandbox-exit",
+      data: { exitCode: handle?.exitCode ?? 137, success: false, killed: true, toolCallId }
+    });
+    const parts = [`Process ${pid} has been killed.`];
+    if (handle) {
+      const stdout = handle.stdout ? truncateOutput(handle.stdout, KILL_TAIL_LINES) : "";
+      const stderr = handle.stderr ? truncateOutput(handle.stderr, KILL_TAIL_LINES) : "";
+      if (stdout) {
+        parts.push("", "--- stdout (last output) ---", stdout);
+      }
+      if (stderr) {
+        parts.push("", "--- stderr (last output) ---", stderr);
+      }
+    }
+    return parts.join("\n");
+  }
+});
 
 // src/workspace/tools/tree-formatter.ts
 var BRANCH = "\u251C\u2500\u2500 ";
@@ -5783,10 +6325,22 @@ function wrapWithReadTracker(tool, workspace, readTracker, config, mode) {
     }
   };
 }
+function wrapWithWriteLock(tool, writeLock) {
+  return {
+    ...tool,
+    execute: async (input, context = {}) => {
+      if (!input.path) {
+        throw new Error("wrapWithWriteLock: input.path is required");
+      }
+      return writeLock.withLock(input.path, () => tool.execute(input, context));
+    }
+  };
+}
 function createWorkspaceTools(workspace) {
   const tools = {};
   const toolsConfig = workspace.getToolsConfig();
   const isReadOnly = workspace.filesystem?.readOnly ?? false;
+  const writeLock = new InMemoryFileWriteLock();
   let readTracker;
   const writeFileConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE);
   const editFileConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE);
@@ -5798,31 +6352,39 @@ function createWorkspaceTools(workspace) {
     const config = resolveToolConfig(toolsConfig, name);
     if (!config.enabled) return;
     if (opts?.requireWrite && isReadOnly) return;
+    let wrapped;
     if (readTracker && opts?.readTrackerMode) {
-      tools[name] = wrapWithReadTracker(tool, workspace, readTracker, config, opts.readTrackerMode);
+      wrapped = wrapWithReadTracker(tool, workspace, readTracker, config, opts.readTrackerMode);
     } else {
-      tools[name] = wrapTool(tool, workspace, config);
+      wrapped = wrapTool(tool, workspace, config);
+    }
+    if (opts?.useWriteLock) {
+      wrapped = wrapWithWriteLock(wrapped, writeLock);
     }
+    tools[name] = wrapped;
   };
   if (workspace.filesystem) {
     addTool(WORKSPACE_TOOLS.FILESYSTEM.READ_FILE, readFileTool, { readTrackerMode: "read" });
     addTool(WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE, writeFileTool, {
       requireWrite: true,
-      readTrackerMode: "write"
+      readTrackerMode: "write",
+      useWriteLock: true
     });
     addTool(WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE, editFileTool, {
       requireWrite: true,
-      readTrackerMode: "write"
+      readTrackerMode: "write",
+      useWriteLock: true
     });
     addTool(WORKSPACE_TOOLS.FILESYSTEM.LIST_FILES, listFilesTool);
-    addTool(WORKSPACE_TOOLS.FILESYSTEM.DELETE, deleteFileTool, { requireWrite: true });
+    addTool(WORKSPACE_TOOLS.FILESYSTEM.DELETE, deleteFileTool, { requireWrite: true, useWriteLock: true });
     addTool(WORKSPACE_TOOLS.FILESYSTEM.FILE_STAT, fileStatTool);
     addTool(WORKSPACE_TOOLS.FILESYSTEM.MKDIR, mkdirTool, { requireWrite: true });
     addTool(WORKSPACE_TOOLS.FILESYSTEM.GREP, grepTool);
     if (isAstGrepAvailable()) {
       addTool(WORKSPACE_TOOLS.FILESYSTEM.AST_EDIT, astEditTool, {
         requireWrite: true,
-        readTrackerMode: "write"
+        readTrackerMode: "write",
+        useWriteLock: true
       });
     }
   }
@@ -5833,15 +6395,12 @@ function createWorkspaceTools(workspace) {
   if (workspace.sandbox) {
     const executeCommandConfig = resolveToolConfig(toolsConfig, WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND);
     if (workspace.sandbox.executeCommand && executeCommandConfig.enabled) {
-      const pathContext = workspace.getPathContext();
-      const pathInfo = pathContext.instructions ? `
-
-${pathContext.instructions}` : "";
-      const description = pathInfo ? `${executeCommandTool.description}${pathInfo}` : executeCommandTool.description;
-      tools[WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND] = {
-        ...wrapTool(executeCommandTool, workspace, executeCommandConfig),
-        description
-      };
+      const baseTool = workspace.sandbox.processes ? executeCommandWithBackgroundTool : executeCommandTool;
+      tools[WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND] = wrapTool(baseTool, workspace, executeCommandConfig);
+    }
+    if (workspace.sandbox.processes) {
+      addTool(WORKSPACE_TOOLS.SANDBOX.GET_PROCESS_OUTPUT, getProcessOutputTool);
+      addTool(WORKSPACE_TOOLS.SANDBOX.KILL_PROCESS, killProcessTool);
     }
   }
   return tools;
@@ -5871,11 +6430,13 @@ exports.MountManager = MountManager;
 exports.MountNotSupportedError = MountNotSupportedError;
 exports.NotDirectoryError = NotDirectoryError;
 exports.PermissionError = PermissionError;
+exports.ProcessHandle = ProcessHandle;
 exports.SandboxError = SandboxError;
 exports.SandboxExecutionError = SandboxExecutionError;
 exports.SandboxFeatureNotSupportedError = SandboxFeatureNotSupportedError;
 exports.SandboxNotAvailableError = SandboxNotAvailableError;
 exports.SandboxNotReadyError = SandboxNotReadyError;
+exports.SandboxProcessManager = SandboxProcessManager;
 exports.SandboxTimeoutError = SandboxTimeoutError;
 exports.SearchNotAvailableError = SearchNotAvailableError;
 exports.VersionedSkillSource = VersionedSkillSource;
@@ -5912,5 +6473,5 @@ exports.requireWorkspace = requireWorkspace;
 exports.resolveToolConfig = resolveToolConfig;
 exports.searchTool = searchTool;
 exports.writeFileTool = writeFileTool;
-//# sourceMappingURL=chunk-AYHSPIT6.cjs.map
-//# sourceMappingURL=chunk-AYHSPIT6.cjs.map
+//# sourceMappingURL=chunk-7UAJ6LMR.cjs.map
+//# sourceMappingURL=chunk-7UAJ6LMR.cjs.map