@deepagents/context 1.0.0 → 2.1.0

package/dist/index.js

@@ -4697,7 +4697,7 @@ async function chat(agent2, options = {}) {
       if (isAborted) {
         normalizedMessage.parts = sanitizeAbortedParts(normalizedMessage.parts);
       }
-      const drained = sandbox.drainFileEvents?.() ?? [];
+      const drained = sandbox.drainFileEvents();
       const fileEvents = isAborted ? [] : drained;
       const finalMetadata = await options.finalAssistantMetadata?.(normalizedMessage);
       const mergedMetadata = {
@@ -5454,15 +5454,15 @@ function dateReminder(options) {
       const now = /* @__PURE__ */ new Date();
       const currentDate = formatDateKey(now, tz);
       const currentDay = formatDayOfWeek(now, tz);
-      let diff = "";
+      let diff2 = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff = formatDiff([
+        diff2 = formatDiff([
           diffLine("date", formatDateKey(prev, tz), currentDate),
           diffLine("day of week", formatDayOfWeek(prev, tz), currentDay)
         ]);
       }
-      return `${diff}Date: ${currentDate}
+      return `${diff2}Date: ${currentDate}
 Day of Week: ${currentDay}`;
     },
     { when: dayChanged(options), asPart: false }
@@ -5474,14 +5474,14 @@ function timeReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentTime = formatTime(now, tz);
-      let diff = "";
+      let diff2 = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff = formatDiff([
+        diff2 = formatDiff([
           diffLine("hour", formatHour(prev, tz), formatHour(now, tz))
         ]);
       }
-      return `${diff}Time: ${currentTime}`;
+      return `${diff2}Time: ${currentTime}`;
     },
     { when: hourChanged(options), asPart: false }
   );
@@ -5492,14 +5492,14 @@ function monthReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentMonth = formatMonthName(now, tz);
-      let diff = "";
+      let diff2 = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff = formatDiff([
+        diff2 = formatDiff([
           diffLine("month", formatMonthName(prev, tz), currentMonth)
         ]);
       }
-      return `${diff}Month: ${currentMonth}`;
+      return `${diff2}Month: ${currentMonth}`;
     },
     { when: monthChanged(options), asPart: false }
   );
@@ -5510,14 +5510,14 @@ function yearReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentYear = formatYear(now, tz);
-      let diff = "";
+      let diff2 = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff = formatDiff([
+        diff2 = formatDiff([
           diffLine("year", formatYear(prev, tz), currentYear)
         ]);
       }
-      return `${diff}Year: ${currentYear}`;
+      return `${diff2}Year: ${currentYear}`;
     },
     { when: yearChanged(options), asPart: false }
   );
@@ -5528,14 +5528,14 @@ function seasonReminder(options) {
       const tz = resolveTz(options, ctx);
       const now = /* @__PURE__ */ new Date();
       const currentSeason = getSeason(getMonthIndex(now, tz));
-      let diff = "";
+      let diff2 = "";
       if (ctx.lastMessageAt !== void 0) {
         const prev = new Date(ctx.lastMessageAt);
-        diff = formatDiff([
+        diff2 = formatDiff([
           diffLine("season", getSeason(getMonthIndex(prev, tz)), currentSeason)
         ]);
       }
-      return `${diff}Season: ${currentSeason}`;
+      return `${diff2}Season: ${currentSeason}`;
     },
     { when: seasonChanged(options), asPart: false }
   );
@@ -5553,11 +5553,11 @@ function localeReminder() {
       const current = getLocaleFromMessage(ctx.currentMessage);
       if (!current) return "";
       const last = getLocaleFromMessage(ctx.lastMessage);
-      const diff = last ? formatDiff([
+      const diff2 = last ? formatDiff([
         diffLine("language", last.language, current.language),
         diffLine("timezone", last.timeZone, current.timeZone)
       ]) : "";
-      return `${diff}Language: ${current.language}
+      return `${diff2}Language: ${current.language}
 Timezone: ${current.timeZone}`;
     },
     { when: whenFn, asPart: false }
@@ -5829,6 +5829,25 @@ function render(tag, ...fragments) {
   return renderer.render([wrapped]);
 }
 
+// packages/context/src/lib/sandbox/abort.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var ambientAbortSignal = new AsyncLocalStorage();
+function runWithAbortSignal(signal, fn) {
+  return ambientAbortSignal.run(signal, fn);
+}
+function withAbortSignal(sandbox) {
+  return {
+    ...sandbox,
+    async executeCommand(command, options) {
+      const signal = options?.signal ?? ambientAbortSignal.getStore();
+      return sandbox.executeCommand(
+        command,
+        signal ? { ...options, signal } : options
+      );
+    }
+  };
+}
+
 // packages/context/src/lib/sandbox/agent-os-sandbox.ts
 import "bash-tool";
 var textDecoder = new TextDecoder();
@@ -5935,8 +5954,8 @@ var BashException = class extends Error {
 };
 
 // packages/context/src/lib/sandbox/bash-meta.ts
-import { AsyncLocalStorage } from "node:async_hooks";
-var store = new AsyncLocalStorage();
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+var store = new AsyncLocalStorage2();
 function runWithBashMeta(fn) {
   return store.run({ hidden: {} }, fn);
 }
@@ -5966,6 +5985,103 @@ import {
 } from "bash-tool";
 import z3 from "zod";
 
+// packages/context/src/lib/sandbox/file-events.ts
+var SnapshotFailedError = class extends Error {
+  stderr;
+  constructor(message2, stderr) {
+    super(message2);
+    this.name = "SnapshotFailedError";
+    this.stderr = stderr;
+  }
+};
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function snapshot(execute, destination) {
+  const probe = await execute(`[ -d ${shellQuote(destination)} ]`);
+  if (probe.exitCode !== 0) return /* @__PURE__ */ new Map();
+  const list = await execute(
+    `find ${shellQuote(destination)} -type f -print0 | while IFS= read -r -d '' p; do sha256sum "$p"; done`
+  );
+  if (list.exitCode !== 0) {
+    throw new SnapshotFailedError(
+      `snapshot failed for ${destination}`,
+      list.stderr
+    );
+  }
+  const snap = /* @__PURE__ */ new Map();
+  if (!list.stdout) return snap;
+  for (const line of list.stdout.split("\n")) {
+    if (line.length < 66) continue;
+    snap.set(line.slice(66), line.slice(0, 64));
+  }
+  return snap;
+}
+function diff(before, after) {
+  const events = [];
+  const ts = Date.now();
+  for (const [path5, hash] of after) {
+    const prior = before.get(path5);
+    if (prior === void 0) {
+      events.push({ path: path5, op: "write", timestamp: ts });
+    } else if (prior !== hash) {
+      events.push({ path: path5, op: "modify", timestamp: ts });
+    }
+  }
+  for (const path5 of before.keys()) {
+    if (!after.has(path5)) {
+      events.push({ path: path5, op: "delete", timestamp: ts });
+    }
+  }
+  return events;
+}
+function observeSandboxFileEvents(sandbox, options) {
+  const { destination } = options;
+  if (!destination) {
+    throw new Error("observeSandboxFileEvents: destination is required");
+  }
+  const innerExecute = sandbox.executeCommand.bind(sandbox);
+  const innerReadFile = sandbox.readFile.bind(sandbox);
+  const innerWriteFiles = sandbox.writeFiles.bind(sandbox);
+  const buffer = [];
+  const observe = async (fn) => {
+    const before = await snapshot(innerExecute, destination);
+    const takeAfter = async () => {
+      const after = await snapshot(innerExecute, destination);
+      buffer.push(...diff(before, after));
+    };
+    try {
+      const result = await fn();
+      await takeAfter();
+      return result;
+    } catch (err) {
+      await takeAfter().catch(() => {
+      });
+      throw err;
+    }
+  };
+  const decorated = {
+    async executeCommand(command, options2) {
+      return observe(() => innerExecute(command, options2));
+    },
+    async readFile(path5) {
+      const content = await innerReadFile(path5);
+      buffer.push({ path: path5, op: "read", timestamp: Date.now() });
+      return content;
+    },
+    async writeFiles(files) {
+      await observe(() => innerWriteFiles(files));
+    },
+    dispose: sandbox.dispose.bind(sandbox)
+  };
+  return {
+    sandbox: decorated,
+    drain() {
+      return buffer.splice(0, buffer.length);
+    }
+  };
+}
+
 // packages/context/src/lib/sandbox/upload-skills.ts
 import * as path3 from "node:path";
 
@@ -6111,22 +6227,38 @@ async function uploadSkills(sandbox, inputs) {
 
 // packages/context/src/lib/sandbox/bash-tool.ts
 var REASONING_INSTRUCTION = 'Every bash tool call must include a brief non-empty "reasoning" input explaining why the command is needed.';
-async function createBashTool(options = {}) {
-  const { skills: skillInputs = [], extraInstructions, ...rest } = options;
+function withBashExceptionCatch(sandbox) {
+  return {
+    ...sandbox,
+    async executeCommand(command, options) {
+      try {
+        return await sandbox.executeCommand(command, options);
+      } catch (err) {
+        if (err instanceof BashException) return err.format();
+        throw err;
+      }
+    }
+  };
+}
+async function createBashTool(options) {
+  const {
+    skills: skillInputs = [],
+    extraInstructions,
+    sandbox: backend,
+    destination,
+    ...rest
+  } = options;
+  const observer = observeSandboxFileEvents(backend, {
+    destination: destination ?? "/workspace"
+  });
+  const sandbox = withAbortSignal(withBashExceptionCatch(observer.sandbox));
   const combinedInstructions = [extraInstructions, REASONING_INSTRUCTION].filter(Boolean).join("\n\n");
   const toolkit = await externalCreateBashTool({
     ...rest,
+    sandbox,
+    destination,
     extraInstructions: combinedInstructions
   });
-  const innerExecute = toolkit.sandbox.executeCommand.bind(toolkit.sandbox);
-  toolkit.sandbox.executeCommand = async (cmd) => {
-    try {
-      return await innerExecute(cmd);
-    } catch (err) {
-      if (err instanceof BashException) return err.format();
-      throw err;
-    }
-  };
   const upstreamBash = toolkit.bash;
   const originalExecute = upstreamBash.execute;
   const toolBuilder = tool2;
@@ -6141,197 +6273,43 @@ async function createBashTool(options = {}) {
       if (!originalExecute) {
         throw new Error("bash tool execution is not available");
       }
-      return runWithBashMeta(async () => {
-        let result;
-        try {
-          result = await originalExecute({ command }, execOptions);
-        } catch (err) {
-          if (err instanceof BashException) {
-            result = err.format();
-          } else {
-            throw err;
-          }
-        }
-        const state = readBashMeta();
-        if (!state) return result;
-        const hasHidden = Object.keys(state.hidden).length > 0;
-        const hasReminder = state.reminder !== void 0;
-        if (!hasHidden && !hasReminder) return result;
-        return {
-          ...result,
-          ...hasHidden ? { meta: state.hidden } : {},
-          ...hasReminder ? { reminder: state.reminder } : {}
-        };
-      });
+      const { abortSignal } = execOptions;
+      return runWithAbortSignal(
+        abortSignal,
+        () => runWithBashMeta(async () => {
+          const result = await originalExecute({ command }, execOptions);
+          const state = readBashMeta();
+          if (!state) return result;
+          const hasHidden = Object.keys(state.hidden).length > 0;
+          const hasReminder = state.reminder !== void 0;
+          if (!hasHidden && !hasReminder) return result;
+          return {
+            ...result,
+            ...hasHidden ? { meta: state.hidden } : {},
+            ...hasReminder ? { reminder: state.reminder } : {}
+          };
+        })
+      );
     },
     toModelOutput: ({ output }) => {
       if (typeof output !== "object" || output === null) {
         return { type: "json", value: output };
       }
-      const record = output;
-      if (!("meta" in record)) {
-        return { type: "json", value: record };
-      }
-      const { meta: _meta, ...visible } = record;
+      const { meta: _meta, ...visible } = output;
       return { type: "json", value: visible };
     }
   });
-  const skills2 = await uploadSkills(toolkit.sandbox, skillInputs);
+  const skills2 = await uploadSkills(sandbox, skillInputs);
   return {
     ...toolkit,
+    sandbox,
     bash,
     tools: { ...toolkit.tools, bash },
-    skills: skills2
+    skills: skills2,
+    drainFileEvents: () => observer.drain()
   };
 }
 
-// packages/context/src/lib/sandbox/file-events.ts
-var ObservedFs = class {
-  #base;
-  #events = [];
-  readdirWithFileTypes;
-  constructor(base) {
-    this.#base = base;
-    if (base.readdirWithFileTypes) {
-      this.readdirWithFileTypes = (path5) => base.readdirWithFileTypes(path5);
-    }
-  }
-  drain() {
-    const events = this.#events;
-    this.#events = [];
-    return events;
-  }
-  #record(op, path5) {
-    this.#events.push({ path: path5, op, timestamp: Date.now() });
-  }
-  async readFile(path5, options) {
-    const content = await this.#base.readFile(path5, options);
-    this.#record("read", path5);
-    return content;
-  }
-  async readFileBuffer(path5) {
-    const content = await this.#base.readFileBuffer(path5);
-    this.#record("read", path5);
-    return content;
-  }
-  async writeFile(path5, content, options) {
-    const existed = await this.#base.exists(path5);
-    await this.#base.writeFile(path5, content, options);
-    this.#record(existed ? "modify" : "write", path5);
-  }
-  async appendFile(path5, content, options) {
-    const existed = await this.#base.exists(path5);
-    await this.#base.appendFile(path5, content, options);
-    this.#record(existed ? "modify" : "write", path5);
-  }
-  async rm(path5, options) {
-    const toRecord = options?.recursive ? await this.#walk(path5, { includeRoot: true }) : await this.#base.exists(path5) ? [path5] : [];
-    await this.#base.rm(path5, options);
-    for (const p of toRecord) {
-      this.#record("delete", p);
-    }
-  }
-  async cp(src, dest, options) {
-    if (options?.recursive) {
-      const sources = await this.#walk(src, { includeRoot: false });
-      const destChecks = await Promise.all(
-        sources.map(async (srcFile) => {
-          const relative3 = srcFile.slice(src.length);
-          const destFile = this.#joinPath(dest, relative3);
-          return {
-            srcFile,
-            destFile,
-            existed: await this.#base.exists(destFile)
-          };
-        })
-      );
-      await this.#base.cp(src, dest, options);
-      for (const { srcFile, destFile, existed } of destChecks) {
-        this.#record("read", srcFile);
-        this.#record(existed ? "modify" : "write", destFile);
-      }
-      return;
-    }
-    const destExisted = await this.#base.exists(dest);
-    await this.#base.cp(src, dest, options);
-    this.#record("read", src);
-    this.#record(destExisted ? "modify" : "write", dest);
-  }
-  async #walk(root, { includeRoot }) {
-    if (!await this.#base.exists(root)) return [];
-    const stat = await this.#base.stat(root);
-    if (!stat.isDirectory) return [root];
-    const out = [];
-    const visit = async (dir) => {
-      const entries = await this.#base.readdir(dir);
-      for (const name of entries) {
-        const child = this.#joinPath(dir, name);
-        const childStat = await this.#base.stat(child);
-        if (childStat.isDirectory) {
-          await visit(child);
-        } else {
-          out.push(child);
-        }
-      }
-    };
-    await visit(root);
-    if (includeRoot) out.push(root);
-    return out;
-  }
-  #joinPath(a, b) {
-    if (!b) return a;
-    if (b.startsWith("/")) return `${a.replace(/\/$/, "")}${b}`;
-    return a.endsWith("/") ? `${a}${b}` : `${a}/${b}`;
-  }
-  async mv(src, dest) {
-    const destExisted = await this.#base.exists(dest);
-    await this.#base.mv(src, dest);
-    this.#record("delete", src);
-    this.#record(destExisted ? "modify" : "write", dest);
-  }
-  async symlink(target, linkPath) {
-    await this.#base.symlink(target, linkPath);
-    this.#record("write", linkPath);
-  }
-  async link(existingPath, newPath) {
-    await this.#base.link(existingPath, newPath);
-    this.#record("write", newPath);
-  }
-  mkdir(path5, options) {
-    return this.#base.mkdir(path5, options);
-  }
-  exists(path5) {
-    return this.#base.exists(path5);
-  }
-  stat(path5) {
-    return this.#base.stat(path5);
-  }
-  lstat(path5) {
-    return this.#base.lstat(path5);
-  }
-  readdir(path5) {
-    return this.#base.readdir(path5);
-  }
-  readlink(path5) {
-    return this.#base.readlink(path5);
-  }
-  realpath(path5) {
-    return this.#base.realpath(path5);
-  }
-  chmod(path5, mode) {
-    return this.#base.chmod(path5, mode);
-  }
-  utimes(path5, atime, mtime) {
-    return this.#base.utimes(path5, atime, mtime);
-  }
-  resolvePath(base, path5) {
-    return this.#base.resolvePath(base, path5);
-  }
-  getAllPaths() {
-    return this.#base.getAllPaths();
-  }
-};
-
 // packages/context/src/lib/sandbox/binary-bridges.ts
 import { existsSync as existsSync2 } from "fs";
 import { defineCommand } from "just-bash";
@@ -6431,8 +6409,10 @@ function resolveRealCwd(ctx) {
 // packages/context/src/lib/sandbox/docker-sandbox.ts
 import "bash-tool";
 import spawn3 from "nano-spawn";
+import { spawn as childSpawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
+import { Readable } from "node:stream";
 
 // packages/context/src/lib/sandbox/docker-sandbox-errors.ts
 var DockerSandboxError = class extends Error {
@@ -6505,16 +6485,48 @@ var MissingRuntimeError = class extends DockerSandboxError {
     this.required = required;
   }
 };
-var MountPathError = class extends DockerSandboxError {
-  hostPath;
+var VolumePathError = class extends DockerSandboxError {
+  source;
   containerPath;
-  constructor(hostPath, containerPath) {
+  reason;
+  constructor(source, containerPath, reason) {
     super(
-      `Mount path does not exist on host: "${hostPath}" -> "${containerPath}"`
+      `Invalid Docker volume path "${source}" -> "${containerPath}": ${reason}`
     );
-    this.name = "MountPathError";
-    this.hostPath = hostPath;
+    this.name = "VolumePathError";
+    this.source = source;
     this.containerPath = containerPath;
+    this.reason = reason;
+  }
+};
+var VolumeInspectError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to inspect Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeInspectError";
+    this.volume = volume;
+    this.reason = reason;
+  }
+};
+var VolumeCreateError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to create Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeCreateError";
+    this.volume = volume;
+    this.reason = reason;
+  }
+};
+var VolumeRemoveError = class extends DockerSandboxError {
+  volume;
+  reason;
+  constructor(volume, reason) {
+    super(`Failed to remove Docker volume "${volume}": ${reason}`);
+    this.name = "VolumeRemoveError";
+    this.volume = volume;
+    this.reason = reason;
   }
 };
 var DockerfileBuildError = class extends DockerSandboxError {
@@ -6547,7 +6559,7 @@ function isDebianBased(image) {
   const debianPatterns = ["debian", "ubuntu", "node", "python"];
   return debianPatterns.some((pattern) => lower.includes(pattern));
 }
-function shellQuote(s) {
+function shellQuote2(s) {
   return `'${s.replace(/'/g, `'\\''`)}'`;
 }
 function createInstallerContext(containerId, image) {
@@ -6595,7 +6607,7 @@ function createInstallerContext(containerId, image) {
   };
   const installPackages = async (packages) => {
     if (packages.length === 0) return;
-    const quoted = packages.map(shellQuote).join(" ");
+    const quoted = packages.map(shellQuote2).join(" ");
     let cmd;
     if (packageManager === "apt-get") {
       cmd = aptUpdated ? `apt-get install -y ${quoted}` : `apt-get update && apt-get install -y ${quoted}`;
@@ -6617,7 +6629,7 @@ function createInstallerContext(containerId, image) {
   const ensureTool = async (checkName, installName) => {
     const cacheKey = installName ?? checkName;
     if (ensuredTools.has(cacheKey)) return;
-    const check = await exec(`which ${shellQuote(checkName)}`);
+    const check = await exec(`which ${shellQuote2(checkName)}`);
     if (check.exitCode === 0) {
       ensuredTools.add(cacheKey);
       return;
@@ -6643,44 +6655,216 @@ function isDockerfileOptions(opts) {
 function isComposeOptions(opts) {
   return "compose" in opts;
 }
+var CONTAINER_NAME_PATTERN = /^[A-Za-z0-9_.-]+$/;
 var DockerSandboxStrategy = class {
   context;
-  mounts;
+  volumes;
   resources;
   env;
+  name;
+  createdVolumes = /* @__PURE__ */ new Set();
   constructor(args = {}) {
-    const { mounts = [], resources = {}, env = {} } = args;
+    const { volumes = [], resources = {}, env = {}, name } = args;
     for (const key of Object.keys(env)) {
-      if (key.length === 0 || key.includes("=")) {
-        throw new DockerSandboxError(
-          `Invalid environment variable key: "${key}"`
-        );
-      }
+      validateEnvKey(key);
     }
-    this.mounts = mounts;
+    if (name !== void 0 && !CONTAINER_NAME_PATTERN.test(name)) {
+      throw new DockerSandboxError(
+        `Invalid container name: "${name}". Use only letters, numbers, underscore, period, or hyphen. The "sandbox-" prefix is added automatically.`
+      );
+    }
+    this.volumes = volumes;
     this.resources = resources;
     this.env = env;
+    this.name = name;
   }
   async create() {
-    this.validateMounts();
     const image = await this.getImage();
-    const containerId = await this.startContainer(image);
-    this.context = { containerId, image };
+    let acquired;
     try {
-      await this.configure();
+      acquired = await this.acquireContainer(image);
+      this.context = { containerId: acquired.containerId, image };
+      if (!acquired.attached) {
+        await this.configure();
+      }
     } catch (error) {
-      await this.stopContainer(containerId);
+      if (acquired && !acquired.attached) {
+        await this.stopContainer(acquired.containerId);
+      }
+      await this.cleanupCreatedVolumesAfterFailure(error);
       throw error;
     }
     return this.createSandboxMethods();
   }
-  validateMounts() {
-    for (const mount of this.mounts) {
-      if (!existsSync3(mount.hostPath)) {
-        throw new MountPathError(mount.hostPath, mount.containerPath);
+  namedContainerId() {
+    return `sandbox-${this.name}`;
+  }
+  defaultContainerId() {
+    return `sandbox-${crypto.randomUUID().slice(0, 8)}`;
+  }
+  async acquireContainer(image) {
+    if (!this.name) {
+      const containerId2 = this.defaultContainerId();
+      await this.prepareVolumes();
+      await this.startContainer(image, containerId2);
+      return { containerId: containerId2, attached: false };
+    }
+    const containerId = this.namedContainerId();
+    const probe = await this.inspectContainer(containerId);
+    if (probe === "running") {
+      return { containerId, attached: true };
+    }
+    if (probe === "stopped") {
+      await this.startStoppedContainer(containerId, image);
+      return { containerId, attached: true };
+    }
+    await this.prepareVolumes();
+    try {
+      await this.startContainer(image, containerId);
+      return { containerId, attached: false };
+    } catch (error) {
+      if (error instanceof ContainerCreationError && this.isNameConflictError(error.message)) {
+        await this.cleanupCreatedVolumes();
+        const raced = await this.inspectContainer(containerId);
+        if (raced === "running") {
+          return { containerId, attached: true };
+        }
+        if (raced === "stopped") {
+          await this.startStoppedContainer(containerId, image);
+          return { containerId, attached: true };
+        }
+      }
+      throw error;
+    }
+  }
+  async startStoppedContainer(containerId, image) {
+    try {
+      await spawn3("docker", ["start", containerId]);
+    } catch (error) {
+      const message2 = this.getDockerErrorMessage(error);
+      if (this.isDockerUnavailableError(message2)) {
+        throw new DockerNotAvailableError();
+      }
+      throw new ContainerCreationError(message2, image, error);
+    }
+  }
+  async inspectContainer(containerId) {
+    try {
+      const result = await spawn3("docker", [
+        "container",
+        "inspect",
+        "--format",
+        "{{.State.Status}}",
+        containerId
+      ]);
+      const status = result.stdout.trim();
+      return status === "running" ? "running" : "stopped";
+    } catch (error) {
+      const message2 = this.getDockerErrorMessage(error);
+      if (this.isDockerUnavailableError(message2)) {
+        throw new DockerNotAvailableError();
+      }
+      if (this.isMissingContainerError(message2)) {
+        return "absent";
+      }
+      throw new DockerSandboxError(
+        `Failed to inspect container "${containerId}": ${message2}`
+      );
+    }
+  }
+  isMissingContainerError(message2) {
+    return message2.toLowerCase().includes("no such container");
+  }
+  isNameConflictError(message2) {
+    return message2.toLowerCase().includes("is already in use by container");
+  }
+  async prepareVolumes() {
+    this.validateVolumes();
+    for (const volume of this.volumes) {
+      if (volume.type !== "volume") {
+        continue;
+      }
+      const lifecycle = volume.lifecycle ?? "external";
+      if (lifecycle === "external") {
+        await this.inspectVolume(volume.name);
+        continue;
+      }
+      const exists = await this.volumeExists(volume.name);
+      if (exists) {
+        throw new VolumeCreateError(
+          volume.name,
+          "managed volume already exists"
+        );
+      }
+      await this.createVolume(volume);
+      if (volume.removeOnDispose !== false) {
+        this.createdVolumes.add(volume.name);
+      }
+    }
+  }
+  validateVolumes() {
+    const containerPaths = /* @__PURE__ */ new Set();
+    for (const volume of this.volumes) {
+      const source = volume.type === "bind" ? volume.hostPath : volume.name;
+      if (!volume.containerPath.startsWith("/")) {
+        throw new VolumePathError(
+          source,
+          volume.containerPath,
+          "containerPath must be absolute"
+        );
+      }
+      this.validateMountValue("containerPath", volume.containerPath, volume);
+      if (containerPaths.has(volume.containerPath)) {
+        throw new VolumePathError(
+          source,
+          volume.containerPath,
+          "containerPath must be unique"
+        );
+      }
+      containerPaths.add(volume.containerPath);
+      if (volume.type === "bind") {
+        this.validateMountValue("hostPath", volume.hostPath, volume);
+        if (!existsSync3(volume.hostPath)) {
+          throw new VolumePathError(
+            volume.hostPath,
+            volume.containerPath,
+            "hostPath does not exist on host"
+          );
+        }
+        continue;
+      }
+      if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(volume.name)) {
+        throw new VolumePathError(
+          volume.name,
+          volume.containerPath,
+          "volume name must start with an alphanumeric character and contain only letters, numbers, underscore, period, or hyphen"
+        );
+      }
+      if (volume.subPath) {
+        this.validateMountValue("subPath", volume.subPath, volume);
+      }
+      if ((volume.lifecycle ?? "external") === "external") {
+        if (volume.driver || volume.driverOptions) {
+          throw new VolumePathError(
+            volume.name,
+            volume.containerPath,
+            'driver and driverOptions require lifecycle "managed"'
+          );
+        }
       }
     }
   }
+  validateMountValue(field, value, volume) {
+    if (!value.includes(",")) {
+      return;
+    }
+    const source = volume.type === "bind" ? volume.hostPath : volume.name;
+    throw new VolumePathError(
+      source,
+      volume.containerPath,
+      `${field} must not contain commas`
+    );
+  }
   buildDockerArgs(image, containerId) {
     const { memory = "1g", cpus = 2 } = this.resources;
     const args = [
@@ -6697,15 +6881,106 @@ var DockerSandboxStrategy = class {
     for (const [key, value] of Object.entries(this.env)) {
       args.push("-e", `${key}=${value}`);
     }
-    for (const mount of this.mounts) {
-      const mode = mount.readOnly !== false ? "ro" : "rw";
-      args.push("-v", `${mount.hostPath}:${mount.containerPath}:${mode}`);
+    for (const volume of this.volumes) {
+      args.push("--mount", this.buildVolumeMountArg(volume));
     }
     args.push(image, "tail", "-f", "/dev/null");
     return args;
   }
-  async startContainer(image) {
-    const containerId = `sandbox-${crypto.randomUUID().slice(0, 8)}`;
+  buildVolumeMountArg(volume) {
+    const readOnly = volume.readOnly !== false;
+    const parts = volume.type === "bind" ? ["type=bind", `src=${volume.hostPath}`, `dst=${volume.containerPath}`] : [
+      "type=volume",
+      `src=${volume.name}`,
+      `dst=${volume.containerPath}`,
+      ...volume.subPath ? [`volume-subpath=${volume.subPath}`] : [],
+      ...volume.noCopy ? ["volume-nocopy"] : []
+    ];
+    if (readOnly) {
+      parts.push("readonly");
+    }
+    return parts.join(",");
+  }
+  async inspectVolume(name) {
+    try {
+      await spawn3("docker", ["volume", "inspect", name]);
+    } catch (error) {
+      const reason = this.getDockerErrorMessage(error);
+      if (this.isDockerUnavailableError(reason)) {
+        throw new DockerNotAvailableError();
+      }
+      throw new VolumeInspectError(name, reason);
+    }
+  }
+  async volumeExists(name) {
+    try {
+      await this.inspectVolume(name);
+      return true;
+    } catch (error) {
+      if (error instanceof VolumeInspectError) {
+        if (this.isMissingVolumeInspectError(error.reason)) {
+          return false;
+        }
+        throw error;
+      }
+      throw error;
+    }
+  }
+  async createVolume(volume) {
+    const args = ["volume", "create"];
+    if (volume.driver) {
+      args.push("--driver", volume.driver);
+    }
+    for (const [key, value] of Object.entries(volume.driverOptions ?? {})) {
+      args.push("--opt", `${key}=${value}`);
+    }
+    args.push(volume.name);
+    try {
+      await spawn3("docker", args);
+    } catch (error) {
+      const reason = this.getDockerErrorMessage(error);
+      if (this.isDockerUnavailableError(reason)) {
+        throw new DockerNotAvailableError();
+      }
+      throw new VolumeCreateError(volume.name, reason);
+    }
+  }
+  async cleanupCreatedVolumes() {
+    const volumes = [...this.createdVolumes].reverse();
+    for (const volume of volumes) {
+      try {
+        await spawn3("docker", ["volume", "rm", volume]);
+        this.createdVolumes.delete(volume);
+      } catch (error) {
+        const reason = this.getDockerErrorMessage(error);
+        if (this.isDockerUnavailableError(reason)) {
+          throw new DockerNotAvailableError();
+        }
+        throw new VolumeRemoveError(volume, reason);
+      }
+    }
+  }
+  async cleanupCreatedVolumesAfterFailure(originalError) {
+    try {
+      await this.cleanupCreatedVolumes();
+    } catch (cleanupError) {
+      if (originalError instanceof Error) {
+        const original = originalError;
+        original.suppressed = [...original.suppressed ?? [], cleanupError];
+      }
+    }
+  }
+  getDockerErrorMessage(error) {
+    const err = error;
+    return err.stderr || err.stdout || err.message || String(error);
+  }
+  isDockerUnavailableError(message2) {
+    return message2.includes("Cannot connect") || message2.includes("docker daemon");
+  }
+  isMissingVolumeInspectError(message2) {
+    return message2.toLowerCase().includes("no such volume");
+  }
+  async startContainer(image, containerId) {
     const args = this.buildDockerArgs(image, containerId);
     try {
       await spawn3("docker", args);
@@ -6714,9 +6989,12 @@ var DockerSandboxStrategy = class {
       if (err.message?.includes("Cannot connect") || err.message?.includes("docker daemon") || err.stderr?.includes("Cannot connect")) {
         throw new DockerNotAvailableError();
       }
-      throw new ContainerCreationError(err.message || String(err), image, err);
+      throw new ContainerCreationError(
+        this.getDockerErrorMessage(err),
+        image,
+        err
+      );
     }
-    return containerId;
   }
   async stopContainer(containerId) {
     try {
@@ -6724,15 +7002,13 @@ var DockerSandboxStrategy = class {
     } catch {
     }
   }
-  async exec(command) {
+  async exec(command, options) {
     try {
-      const result = await spawn3("docker", [
-        "exec",
-        this.context.containerId,
-        "sh",
-        "-c",
-        command
-      ]);
+      const result = await spawn3(
+        "docker",
+        ["exec", this.context.containerId, "sh", "-c", command],
+        { signal: options?.signal }
+      );
       return {
         stdout: result.stdout,
         stderr: result.stderr,
@@ -6747,12 +7023,22 @@ var DockerSandboxStrategy = class {
       };
     }
   }
+  spawnProcess(command, options) {
+    const child = childSpawn("docker", [
+      "exec",
+      ...buildDockerExecFlags(options),
+      this.context.containerId,
+      "sh",
+      "-c",
+      command
+    ]);
+    return toSandboxProcess(child, options?.signal);
+  }
   createSandboxMethods() {
     const { containerId } = this.context;
     const sandbox = {
-      executeCommand: async (command) => {
-        return this.exec(command);
-      },
+      executeCommand: async (command, options) => this.exec(command, options),
+      spawn: (command, options) => this.spawnProcess(command, options),
       readFile: async (path5) => {
         const result = await sandbox.executeCommand(`base64 "${path5}"`);
         if (result.exitCode !== 0) {
@@ -6779,16 +7065,74 @@ var DockerSandboxStrategy = class {
       },
       dispose: async () => {
         await this.stopContainer(containerId);
+        await this.cleanupCreatedVolumes();
       }
     };
     return sandbox;
   }
 };
+function validateEnvKey(key) {
+  if (key.length === 0 || key.includes("=")) {
+    throw new DockerSandboxError(`Invalid environment variable key: "${key}"`);
+  }
+}
+function buildDockerExecFlags(options) {
+  const flags = [];
+  if (options?.cwd) {
+    flags.push("-w", options.cwd);
+  }
+  if (options?.env) {
+    for (const [key, value] of Object.entries(options.env)) {
+      validateEnvKey(key);
+      flags.push("-e", `${key}=${value}`);
+    }
+  }
+  return flags;
+}
+function toSandboxProcess(child, abortSignal) {
+  if (!child.stdout || !child.stderr) {
+    child.kill("SIGKILL");
+    throw new DockerSandboxError("docker exec child missing stdio streams");
+  }
+  const onAbort = abortSignal ? () => child.kill("SIGKILL") : void 0;
+  if (abortSignal && onAbort) {
+    if (abortSignal.aborted) onAbort();
+    else abortSignal.addEventListener("abort", onAbort, { once: true });
+  }
+  return {
+    stdout: Readable.toWeb(child.stdout),
+    stderr: Readable.toWeb(child.stderr),
+    exit: new Promise((resolve4, reject) => {
+      const settle = () => {
+        child.removeListener("exit", onExitEvent);
+        child.removeListener("error", onError);
+        if (abortSignal && onAbort) {
+          abortSignal.removeEventListener("abort", onAbort);
+        }
+      };
+      const onError = (err) => {
+        settle();
+        reject(err);
+      };
+      const onExitEvent = (code, exitSignal) => {
+        settle();
+        resolve4({ code, signal: exitSignal, success: code === 0 });
+      };
+      child.on("exit", onExitEvent);
+      child.on("error", onError);
+    })
+  };
+}
 var RuntimeStrategy = class extends DockerSandboxStrategy {
   image;
   installers;
   constructor(args = {}) {
-    super({ mounts: args.mounts, resources: args.resources, env: args.env });
+    super({
+      volumes: args.volumes,
+      resources: args.resources,
+      env: args.env,
+      name: args.name
+    });
     this.image = args.image ?? "alpine:latest";
     this.installers = args.installers ?? [];
   }
@@ -6807,7 +7151,12 @@ var DockerfileStrategy = class extends DockerSandboxStrategy {
   dockerfile;
   dockerContext;
   constructor(args) {
-    super({ mounts: args.mounts, resources: args.resources, env: args.env });
+    super({
+      volumes: args.volumes,
+      resources: args.resources,
+      env: args.env,
+      name: args.name
+    });
     this.dockerfile = args.dockerfile;
     this.dockerContext = args.context ?? ".";
     this.imageTag = this.computeImageTag();
@@ -6876,7 +7225,7 @@ var ComposeStrategy = class extends DockerSandboxStrategy {
   async getImage() {
     return "";
   }
-  async startContainer(_image) {
+  async startContainer(_image, _containerId) {
     try {
       await spawn3("docker", [
         "compose",
@@ -6894,25 +7243,31 @@ var ComposeStrategy = class extends DockerSandboxStrategy {
       }
       throw new ComposeStartError(this.composeFile, err.stderr || err.message);
     }
+  }
+  defaultContainerId() {
     return this.projectName;
   }
   async configure() {
   }
-  async exec(command) {
+  async exec(command, options) {
     try {
-      const result = await spawn3("docker", [
-        "compose",
-        "-f",
-        this.composeFile,
-        "-p",
-        this.projectName,
-        "exec",
-        "-T",
-        this.service,
-        "sh",
-        "-c",
-        command
-      ]);
+      const result = await spawn3(
+        "docker",
+        [
+          "compose",
+          "-f",
+          this.composeFile,
+          "-p",
+          this.projectName,
+          "exec",
+          "-T",
+          this.service,
+          "sh",
+          "-c",
+          command
+        ],
+        { signal: options?.signal }
+      );
       return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
     } catch (error) {
       const err = error;
@@ -6923,6 +7278,23 @@ var ComposeStrategy = class extends DockerSandboxStrategy {
       };
     }
   }
+  spawnProcess(command, options) {
+    const child = childSpawn("docker", [
+      "compose",
+      "-f",
+      this.composeFile,
+      "-p",
+      this.projectName,
+      "exec",
+      "-T",
+      ...buildDockerExecFlags(options),
+      this.service,
+      "sh",
+      "-c",
+      command
+    ]);
+    return toSandboxProcess(child, options?.signal);
+  }
   async stopContainer(_containerId) {
     try {
       await spawn3("docker", [
@@ -6949,17 +7321,19 @@ async function createDockerSandbox(options = {}) {
     strategy = new DockerfileStrategy({
       dockerfile: options.dockerfile,
       context: options.context,
-      mounts: options.mounts,
+      volumes: options.volumes,
       resources: options.resources,
-      env: options.env
+      env: options.env,
+      name: options.name
     });
   } else {
     strategy = new RuntimeStrategy({
       image: options.image,
       installers: options.installers,
-      mounts: options.mounts,
+      volumes: options.volumes,
       resources: options.resources,
-      env: options.env
+      env: options.env,
+      name: options.name
     });
   }
   return strategy.create();
@@ -6987,40 +7361,43 @@ async function createContainerTool(options = {}) {
     const {
       dockerfile,
       context,
-      mounts,
+      volumes,
       resources,
       env,
+      name,
       skills: skills2 = [],
       ...rest
     } = options;
-    sandboxOptions = { dockerfile, context, mounts, resources, env };
+    sandboxOptions = { dockerfile, context, volumes, resources, env, name };
     bashOptions = rest;
     skillInputs = skills2;
   } else {
     const {
       image,
       installers,
-      mounts,
+      volumes,
       resources,
       env,
+      name,
       skills: skills2 = [],
       ...rest
     } = options;
-    sandboxOptions = { image, installers, mounts, resources, env };
+    sandboxOptions = { image, installers, volumes, resources, env, name };
     bashOptions = rest;
     skillInputs = skills2;
   }
-  const sandbox = await createDockerSandbox(sandboxOptions);
+  const backend = await createDockerSandbox(sandboxOptions);
   const toolkit = await createBashTool({
     ...bashOptions,
-    sandbox,
+    sandbox: backend,
     skills: skillInputs
   });
   return {
     bash: toolkit.bash,
     tools: toolkit.tools,
-    sandbox,
-    skills: toolkit.skills
+    sandbox: toolkit.sandbox,
+    skills: toolkit.skills,
+    drainFileEvents: toolkit.drainFileEvents
   };
 }
 
@@ -7096,9 +7473,9 @@ async function downloadAndInstall(ctx, name, url, binaryPath, source = "url") {
 function buildTarGzInstallCmd(name, url, binaryPathInArchive) {
   return `
     set -e
-    NAME=${shellQuote(name)}
-    URL=${shellQuote(url)}
-    BIN_IN_ARCHIVE=${shellQuote(binaryPathInArchive)}
+    NAME=${shellQuote2(name)}
+    URL=${shellQuote2(url)}
+    BIN_IN_ARCHIVE=${shellQuote2(binaryPathInArchive)}
     TMPDIR=$(mktemp -d)
     cd "$TMPDIR"
     curl -fsSL "$URL" -o archive.tar.gz
@@ -7117,8 +7494,8 @@ function buildTarGzInstallCmd(name, url, binaryPathInArchive) {
 }
 function buildRawInstallCmd(name, url) {
   return `
-    NAME=${shellQuote(name)}
-    URL=${shellQuote(url)}
+    NAME=${shellQuote2(name)}
+    URL=${shellQuote2(url)}
     curl -fsSL "$URL" -o "/usr/local/bin/$NAME"
     chmod +x "/usr/local/bin/$NAME"
   `;
@@ -7330,8 +7707,11 @@ async function createVirtualSandbox(options) {
     customCommands: options.customCommands
   });
   return {
-    async executeCommand(command) {
-      const result = await bash.exec(command);
+    async executeCommand(command, options2) {
+      const result = await bash.exec(
+        command,
+        options2?.signal ? { signal: options2.signal } : void 0
+      );
       return {
         stdout: result.stdout,
         stderr: result.stderr,
@@ -7348,6 +7728,8 @@ async function createVirtualSandbox(options) {
           typeof file.content === "string" ? file.content : Buffer.from(file.content).toString("utf-8")
         );
       }
+    },
+    async dispose() {
     }
   };
 }
@@ -10524,9 +10906,7 @@ export {
   MarkdownRenderer,
   MissingRuntimeError,
   ModelsRegistry,
-  MountPathError,
   NpmInstaller,
-  ObservedFs,
   PackageInstallError,
   PackageInstaller,
   PipInstaller,
@@ -10536,6 +10916,7 @@ export {
   PostgresStreamStore,
   PromiseResolver,
   RuntimeStrategy,
+  SnapshotFailedError,
   SqlServerContextStore,
   SqliteContextStore,
   SqliteStreamStore,
@@ -10545,6 +10926,10 @@ export {
   TomlRenderer,
   ToonRenderer,
   UrlBinaryInstaller,
+  VolumeCreateError,
+  VolumeInspectError,
+  VolumePathError,
+  VolumeRemoveError,
   XmlRenderer,
   addUsage,
   advisorPreamble,
@@ -10639,6 +11024,7 @@ export {
   not,
   npm,
   nullUsage,
+  observeSandboxFileEvents,
   once,
   or,
   parseFrontmatter,
@@ -10663,11 +11049,12 @@ export {
   resolveTz,
   role,
   runGuardrailChain,
+  runWithAbortSignal,
   runWithBashMeta,
   seasonChanged,
   seasonReminder,
   selfCritique,
-  shellQuote,
+  shellQuote2 as shellQuote,
   skills,
   skillsReminder,
   socraticPrompting,
@@ -10696,6 +11083,7 @@ export {
   user,
   visualizeGraph,
   weekChanged,
+  withAbortSignal,
   withinLastN,
   workflow,
   yearChanged,