@anvia/sandbox 0.6.0 → 1.0.0-rc.10

package/dist/index.js

@@ -1,31 +1,13 @@
 import {
-  SandboxDockerCommandError,
-  SandboxDockerUnavailableError,
-  SandboxError,
-  SandboxFileSizeError,
-  SandboxPathError,
-  SandboxPortError,
-  SandboxProcessError,
-  SandboxSessionDestroyedError,
-  SandboxTimeoutError,
-  SandboxToolPolicyError,
+  DockerSandboxError,
   assertDockerCli,
+  decodeUtf8,
   runDockerCli
-} from "./chunk-FTNNCT6S.js";
-
-// src/capabilities.ts
-function isSandboxPortSession(session) {
-  const candidate = session;
-  return Array.isArray(candidate.publishedPorts) && typeof candidate.waitForPort === "function";
-}
-function isSandboxProcessSession(session) {
-  const candidate = session;
-  return typeof candidate.startProcess === "function" && typeof candidate.listProcesses === "function" && typeof candidate.readProcessLogs === "function" && typeof candidate.stopProcess === "function";
-}
+} from "./chunk-4D2GWLEH.js";
 
 // src/docker-sandbox.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { mkdtemp, rm, writeFile } from "fs/promises";
+import { lstat, mkdtemp, readFile, realpath, rm, writeFile } from "fs/promises";
 import os from "os";
 import path2 from "path";
 
@@ -37,21 +19,25 @@ import { randomUUID } from "crypto";
 import path from "path";
 function normalizeSandboxPath(input, options = {}) {
   if (input.length === 0) {
-    throw new SandboxPathError("Sandbox path cannot be empty.");
+    throw new DockerSandboxError("Sandbox path cannot be empty.", "invalid_path");
   }
   if (input.includes("\0")) {
-    throw new SandboxPathError("Sandbox path cannot contain null bytes.");
+    throw new DockerSandboxError("Sandbox path cannot contain null bytes.", "invalid_path");
   }
   const normalized = path.posix.normalize(input.replaceAll("\\", "/"));
   if (path.posix.isAbsolute(normalized)) {
-    throw new SandboxPathError(`Sandbox path must be relative: ${input}`);
+    throw new DockerSandboxError(`Sandbox path must be relative: ${input}`, "invalid_path");
   }
   if (normalized === ".." || normalized.startsWith("../")) {
-    throw new SandboxPathError(`Sandbox path cannot leave the workspace: ${input}`);
+    throw new DockerSandboxError(
+      `Sandbox path cannot leave the workspace: ${input}`,
+      "invalid_path"
+    );
   }
   if (normalized === "." && options.allowRoot !== true) {
-    throw new SandboxPathError(
-      "Sandbox path must refer to a file or directory inside the workspace."
+    throw new DockerSandboxError(
+      "Sandbox path must refer to a file or directory inside the workspace.",
+      "invalid_path"
     );
   }
   return normalized;
@@ -69,19 +55,25 @@ function parentSandboxPath(relativePath) {
 
 // src/docker-process.ts
 var processMarkerPrefix = "ANVIA_PROCESS";
+var processLauncher = [
+  'wrapper="$1"',
+  "shift",
+  // GNU setsid forks when it is already a process-group leader. `-w` keeps that launcher alive
+  // until the new session exits, so Docker does not detach from a still-running managed process.
+  "if command -v setsid >/dev/null 2>&1 && setsid -w true >/dev/null 2>&1; then",
+  '  exec setsid -w sh -c "$wrapper" "$@"',
+  "fi",
+  'exec sh -c "$wrapper" "$@"'
+].join("\n");
 var processWrapper = [
   'marker="$1"',
   "shift",
-  "if command -v setsid >/dev/null 2>&1; then",
-  '  setsid "$@" &',
-  "  child=$!",
-  "  group=$child",
-  "else",
-  '  "$@" &',
-  "  child=$!",
-  "  group=$$",
-  "fi",
-  `printf '\\036%s:%s:%s:%s\\036' "$marker" "$$" "$child" "$group"`,
+  "group=$$",
+  `printf '\\036%s:%s:%s\\036' "$marker" "$$" "$group"`,
+  "IFS= read -r ready || exit 125",
+  '[ "$ready" = "start" ] || exit 125',
+  '"$@" &',
+  "child=$!",
   "terminate() {",
   '  wait "$child" 2>/dev/null || true',
   "  exit 143",
@@ -94,13 +86,13 @@ var DockerProcessManager = class {
   constructor(options) {
     this.options = options;
     if (!Number.isInteger(options.maxProcesses) || options.maxProcesses < 0) {
-      throw new SandboxProcessError("Sandbox maxProcesses must be a non-negative integer.");
+      throw processError("Sandbox maxProcesses must be a non-negative integer.");
     }
     if (!Number.isInteger(options.maxOutputBytes) || options.maxOutputBytes < 0) {
-      throw new SandboxProcessError("Sandbox maxOutputBytes must be a non-negative integer.");
+      throw processError("Sandbox maxOutputBytes must be a non-negative integer.");
     }
     if (!Number.isInteger(options.startupTimeoutMs) || options.startupTimeoutMs <= 0) {
-      throw new SandboxProcessError("Sandbox process startup timeout must be a positive integer.");
+      throw processError("Sandbox process startup timeout must be a positive integer.");
     }
   }
   options;
@@ -109,10 +101,11 @@ var DockerProcessManager = class {
   async start(options) {
     this.assertActive();
     assertStartOptions(options);
-    await this.pruneCompletedRecords();
+    options.abortSignal?.throwIfAborted();
+    await this.pruneCompletedRecords(options.abortSignal);
     const trackedCount = this.records.size;
     if (trackedCount >= this.options.maxProcesses) {
-      throw new SandboxProcessError(
+      throw processError(
         `Sandbox process limit reached (${trackedCount} >= ${this.options.maxProcesses}).`
       );
     }
@@ -122,7 +115,6 @@ var DockerProcessManager = class {
     const child = spawn(this.options.dockerPath, dockerArgs, {
       stdio: ["pipe", "pipe", "pipe"]
     });
-    child.stdin.end();
     let resolveStarted;
     let rejectStarted;
     const started = new Promise((resolve, reject) => {
@@ -143,7 +135,6 @@ var DockerProcessManager = class {
     if (options.cwd !== void 0) info.cwd = options.cwd;
     const record = {
       info,
-      startedAtMs: Date.now(),
       child,
       stdout: new TailOutputCollector(this.options.maxOutputBytes),
       stderr: new TailOutputCollector(this.options.maxOutputBytes),
@@ -152,7 +143,6 @@ var DockerProcessManager = class {
       spawnFailed: false,
       stopRequested: false,
       startResolved: false,
-      exitNotified: false,
       resolveStarted,
       rejectStarted,
       started,
@@ -162,10 +152,8 @@ var DockerProcessManager = class {
     this.records.set(id, record);
     this.observe(record);
     try {
-      await this.waitForStart(record);
-      await this.options.onStart?.(copyProcessInfo(record.info));
+      await this.waitForStart(record, options.abortSignal);
       record.startResolved = true;
-      if (record.info.status !== "running") this.notifyExit(record);
       return copyProcessInfo(record.info);
     } catch (error) {
       if (await this.cleanupFailedStart(record)) this.records.delete(id);
@@ -176,28 +164,27 @@ var DockerProcessManager = class {
     this.assertActive();
     return [...this.records.values()].map((record) => copyProcessInfo(record.info));
   }
-  logs(processId, options = {}) {
+  logs(processId, tailBytes) {
     this.assertActive();
     const record = this.getRecord(processId);
-    const stdout = record.stdout.snapshot(options.tailBytes);
-    const stderr = record.stderr.snapshot(options.tailBytes);
+    const stdout = record.stdout.snapshot(tailBytes);
+    const stderr = record.stderr.snapshot(tailBytes);
     return {
-      stdout: stdout.text,
-      stderr: stderr.text,
+      stdout: stdout.bytes,
+      stderr: stderr.bytes,
       stdoutTruncated: stdout.truncated,
       stderrTruncated: stderr.truncated
     };
   }
-  async stop(processId, options = {}) {
+  async stop(processId, gracePeriodMs = 5e3, abortSignal) {
     this.assertActive();
     const record = this.getRecord(processId);
-    const gracePeriodMs = options.gracePeriodMs ?? 5e3;
     if (!Number.isInteger(gracePeriodMs) || gracePeriodMs < 0) {
-      throw new SandboxProcessError("Process gracePeriodMs must be a non-negative integer.");
+      throw processError("Process gracePeriodMs must be a non-negative integer.");
     }
     try {
-      if (!await this.terminateRecord(record, gracePeriodMs)) {
-        throw new SandboxProcessError(`Sandbox process did not stop: ${processId}`);
+      if (!await this.terminateRecord(record, gracePeriodMs, abortSignal)) {
+        throw processError(`Sandbox process did not stop: ${processId}`);
       }
     } catch (error) {
       if (record.info.status === "running") record.stopRequested = false;
@@ -205,17 +192,20 @@ var DockerProcessManager = class {
     }
     return copyProcessInfo(record.info);
   }
-  async dispose() {
+  async dispose(abortSignal) {
     if (this.disposed) return;
-    this.disposed = true;
+    abortSignal?.throwIfAborted();
     await Promise.all(
       [...this.records.values()].map(async (record) => {
-        await this.terminateRecord(record, 1e3).catch(() => false);
+        if (!await this.terminateRecord(record, 1e3, abortSignal)) {
+          throw processError(`Sandbox process did not stop: ${record.info.id}`);
+        }
       })
     );
+    this.disposed = true;
   }
   createExecArgs(options, marker) {
-    const args = ["exec", "-w", containerPath(this.options.workdir, options.cwd ?? ".")];
+    const args = ["exec", "-i", "-w", containerPath(this.options.workdir, options.cwd ?? ".")];
     for (const [key, value] of Object.entries({ ...this.options.env, ...options.env })) {
       args.push("-e", `${key}=${value}`);
     }
@@ -223,6 +213,8 @@ var DockerProcessManager = class {
       this.options.containerName,
       "sh",
       "-c",
+      processLauncher,
+      "anvia-process-launcher",
       processWrapper,
       "anvia-managed-process",
       marker,
@@ -236,7 +228,9 @@ var DockerProcessManager = class {
     record.child.stderr.on("data", (chunk) => record.stderr.accept(chunk));
     record.child.on("error", (error) => {
       record.spawnFailed = true;
-      const normalized = error.code === "ENOENT" ? new SandboxDockerUnavailableError("Docker CLI was not found.", error) : error;
+      const normalized = error.code === "ENOENT" ? new DockerSandboxError("Docker CLI was not found.", "docker_unavailable", void 0, {
+        cause: error
+      }) : error;
       record.rejectStarted(normalized);
     });
     record.child.on("close", (code) => {
@@ -248,12 +242,9 @@ var DockerProcessManager = class {
       record.info.exitCode = code ?? 1;
       record.info.endedAt = (/* @__PURE__ */ new Date()).toISOString();
       record.rejectStarted(
-        new SandboxProcessError(
-          `Sandbox process exited before startup completed: ${record.info.id}`
-        )
+        processError(`Sandbox process exited before startup completed: ${record.info.id}`)
       );
       record.resolveClosed();
-      if (record.startResolved) this.notifyExit(record);
     });
   }
   acceptStdout(record, chunk) {
@@ -280,14 +271,13 @@ var DockerProcessManager = class {
       }
       return;
     }
-    const rawPids = record.markerBuffer.subarray(start + record.markerStart.length, end).toString("utf8").split(":");
+    const rawPids = decodeUtf8(
+      record.markerBuffer.subarray(start + record.markerStart.length, end)
+    ).split(":");
     const supervisorPid = Number(rawPids[0]);
-    const childPid = Number(rawPids[1]);
-    const processGroupId = Number(rawPids[2]);
-    if (!isProcessId(supervisorPid) || !isProcessId(childPid) || !isProcessId(processGroupId)) {
-      record.rejectStarted(
-        new SandboxProcessError("Sandbox process returned invalid process IDs.")
-      );
+    const processGroupId = Number(rawPids[1]);
+    if (!isProcessId(supervisorPid) || !isProcessId(processGroupId) || rawPids.length !== 2) {
+      record.rejectStarted(processError("Sandbox process returned invalid process IDs."));
       return;
     }
     if (start > 0) record.stdout.accept(record.markerBuffer.subarray(0, start));
@@ -296,28 +286,38 @@ var DockerProcessManager = class {
     }
     record.markerBuffer = Buffer.alloc(0);
     record.supervisorPid = supervisorPid;
-    record.childPid = childPid;
     record.processGroupId = processGroupId;
+    record.child.stdin.write("start\n");
     record.resolveStarted();
   }
-  async waitForStart(record) {
+  async waitForStart(record, abortSignal) {
     let timeout;
+    let abort;
     const timeoutPromise = new Promise((_, reject) => {
       timeout = setTimeout(() => {
-        reject(new SandboxTimeoutError("Starting sandbox process timed out."));
+        reject(new DockerSandboxError("Starting sandbox process timed out.", "timeout"));
       }, this.options.startupTimeoutMs);
       timeout.unref?.();
     });
     try {
-      await Promise.race([record.started, timeoutPromise]);
+      const abortPromise = new Promise((_, reject) => {
+        if (abortSignal === void 0) return;
+        abort = () => reject(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        if (abortSignal.aborted) abort();
+        else abortSignal.addEventListener("abort", abort, { once: true });
+      });
+      await Promise.race([record.started, timeoutPromise, abortPromise]);
     } finally {
       if (timeout !== void 0) clearTimeout(timeout);
+      if (abort !== void 0) abortSignal?.removeEventListener("abort", abort);
     }
   }
   async cleanupFailedStart(record) {
     record.stopRequested = true;
     if (record.processGroupId === void 0 && record.info.status === "running") {
-      await waitForPromise(record.closed, 250);
+      record.child.stdin.destroy();
+      record.child.kill("SIGKILL");
+      await waitForPromise(record.closed, 1e3);
     }
     try {
       return await this.terminateRecord(record, 1e3);
@@ -325,47 +325,49 @@ var DockerProcessManager = class {
       return false;
     }
   }
-  async terminateRecord(record, gracePeriodMs) {
+  async terminateRecord(record, gracePeriodMs, abortSignal) {
+    abortSignal?.throwIfAborted();
     record.stopRequested = true;
     if (record.processGroupId === void 0) {
       if (record.info.status === "running") {
-        await waitForPromise(record.closed, Math.min(gracePeriodMs, 250));
+        await waitForPromise(record.closed, Math.min(gracePeriodMs, 250), abortSignal);
       }
       if (record.processGroupId === void 0) {
-        return record.spawnFailed && record.info.status !== "running";
+        return record.info.status !== "running";
       }
     }
-    if (!await this.isProcessGroupRunning(record)) {
-      return this.finishAfterGroupExit(record);
+    if (!await this.isProcessGroupRunning(record, abortSignal)) {
+      return this.finishAfterGroupExit(record, abortSignal);
     }
-    await this.signal(record, "TERM");
-    if (await this.waitForRecordExit(record, gracePeriodMs)) return true;
-    await this.signal(record, "KILL");
-    if (await this.waitForRecordExit(record, 1e3)) return true;
+    await this.signal(record, "TERM", abortSignal);
+    if (await this.waitForRecordExit(record, gracePeriodMs, abortSignal)) return true;
+    await this.signal(record, "KILL", abortSignal);
+    if (await this.waitForRecordExit(record, 1e3, abortSignal)) return true;
     return false;
   }
-  async waitForRecordExit(record, timeoutMs) {
+  async waitForRecordExit(record, timeoutMs, abortSignal) {
     const deadline = Date.now() + timeoutMs;
     while (true) {
-      if (!await this.isProcessGroupRunning(record)) {
-        return this.finishAfterGroupExit(record);
+      abortSignal?.throwIfAborted();
+      if (!await this.isProcessGroupRunning(record, abortSignal)) {
+        return this.finishAfterGroupExit(record, abortSignal);
       }
       const remainingMs = deadline - Date.now();
       if (remainingMs <= 0) return false;
       const intervalMs = Math.min(50, remainingMs);
       if (record.info.status === "running") {
-        await waitForPromise(record.closed, intervalMs);
+        await waitForPromise(record.closed, intervalMs, abortSignal);
       } else {
-        await waitForDelay(intervalMs);
+        await waitForDelay(intervalMs, abortSignal);
       }
     }
   }
-  async finishAfterGroupExit(record) {
+  async finishAfterGroupExit(record, abortSignal) {
     if (record.info.status !== "running") return true;
     record.child.kill("SIGKILL");
-    return waitForPromise(record.closed, 1e3);
+    return waitForPromise(record.closed, 1e3, abortSignal);
   }
-  async isProcessGroupRunning(record) {
+  async isProcessGroupRunning(record, abortSignal) {
     if (record.processGroupId === void 0) return false;
     const result = await runDockerCli(
       [
@@ -375,17 +377,18 @@ var DockerProcessManager = class {
         "-c",
         'kill -0 "-$1" 2>/dev/null',
         "anvia-process-group-check",
-        String(record.processGroupId)
+        `${record.processGroupId}`
       ],
       {
         dockerPath: this.options.dockerPath,
         timeoutMs: 5e3,
-        maxOutputBytes: this.options.maxOutputBytes
+        maxOutputBytes: this.options.maxOutputBytes,
+        signal: abortSignal
       }
     );
     return result.exitCode === 0;
   }
-  async signal(record, signal) {
+  async signal(record, dockerSignal, abortSignal) {
     if (record.processGroupId === void 0) return;
     const result = await runDockerCli(
       [
@@ -395,18 +398,20 @@ var DockerProcessManager = class {
         "-c",
         'kill "-$2" "-$1" 2>/dev/null || ! kill -0 "-$1" 2>/dev/null',
         "anvia-process-signal",
-        String(record.processGroupId),
-        signal
+        `${record.processGroupId}`,
+        dockerSignal
       ],
       {
         dockerPath: this.options.dockerPath,
         timeoutMs: 5e3,
-        maxOutputBytes: this.options.maxOutputBytes
+        maxOutputBytes: this.options.maxOutputBytes,
+        signal: abortSignal
       }
     );
     if (result.exitCode !== 0) {
-      throw new SandboxDockerCommandError(
+      throw new DockerSandboxError(
         `Unable to stop sandbox process: ${record.info.id}`,
+        "docker_command_failed",
         result
       );
     }
@@ -414,39 +419,22 @@ var DockerProcessManager = class {
   getRecord(processId) {
     const record = this.records.get(processId);
     if (record === void 0) {
-      throw new SandboxProcessError(`Unknown sandbox process: ${processId}`);
+      throw processError(`Unknown sandbox process: ${processId}`);
     }
     return record;
   }
-  async pruneCompletedRecords() {
+  async pruneCompletedRecords(abortSignal) {
     for (const [id, record] of this.records) {
       if (this.records.size < this.options.maxProcesses) return;
-      const cleanupConfirmed = record.processGroupId === void 0 ? record.spawnFailed : !await this.isProcessGroupRunning(record);
+      const cleanupConfirmed = record.processGroupId === void 0 ? record.spawnFailed : !await this.isProcessGroupRunning(record, abortSignal);
       if (record.info.status !== "running" && cleanupConfirmed) {
         this.records.delete(id);
       }
     }
   }
-  logsUnsafe(record) {
-    const stdout = record.stdout.snapshot();
-    const stderr = record.stderr.snapshot();
-    return {
-      stdout: stdout.text,
-      stderr: stderr.text,
-      stdoutTruncated: stdout.truncated,
-      stderrTruncated: stderr.truncated
-    };
-  }
-  notifyExit(record) {
-    if (record.exitNotified) return;
-    record.exitNotified = true;
-    const durationMs = Date.now() - record.startedAtMs;
-    const notify = async () => this.options.onExit?.(copyProcessInfo(record.info), this.logsUnsafe(record), durationMs);
-    void notify().catch(() => void 0);
-  }
   assertActive() {
     if (this.disposed) {
-      throw new SandboxProcessError("Sandbox process manager has been disposed.");
+      throw processError("Sandbox process manager has been disposed.");
     }
   }
 };
@@ -488,56 +476,72 @@ var TailOutputCollector = class {
   }
   snapshot(tailBytes) {
     if (tailBytes !== void 0 && (!Number.isInteger(tailBytes) || tailBytes < 0)) {
-      throw new SandboxProcessError("Process tailBytes must be a non-negative integer.");
+      throw processError("Process tailBytes must be a non-negative integer.");
     }
     const bytes = Buffer.concat(this.chunks, this.length);
     const selected = tailBytes === 0 ? Buffer.alloc(0) : tailBytes === void 0 || bytes.length <= tailBytes ? bytes : bytes.subarray(bytes.length - tailBytes);
     return {
-      text: selected.toString("utf8"),
+      bytes: new Uint8Array(selected.buffer, selected.byteOffset, selected.byteLength).slice(),
       truncated: this.didTruncate || selected.length < bytes.length
     };
   }
 };
+function processError(message) {
+  return new DockerSandboxError(message, "process");
+}
 function assertStartOptions(options) {
   if (options.command.trim().length === 0) {
-    throw new SandboxProcessError("Sandbox process command cannot be empty.");
+    throw processError("Sandbox process command cannot be empty.");
   }
 }
 function isProcessId(value) {
   return Number.isSafeInteger(value) && value > 0;
 }
 function copyProcessInfo(info) {
-  const copy = {
+  let copy = {
     id: info.id,
     command: info.command,
     args: [...info.args],
     status: info.status,
     startedAt: info.startedAt
   };
-  if (info.cwd !== void 0) copy.cwd = info.cwd;
-  if (info.exitCode !== void 0) copy.exitCode = info.exitCode;
-  if (info.endedAt !== void 0) copy.endedAt = info.endedAt;
+  if (info.cwd !== void 0) copy = { ...copy, cwd: info.cwd };
+  if (info.exitCode !== void 0) copy = { ...copy, exitCode: info.exitCode };
+  if (info.endedAt !== void 0) copy = { ...copy, endedAt: info.endedAt };
   return copy;
 }
-async function waitForPromise(promise, timeoutMs) {
+async function waitForPromise(promise, timeoutMs, abortSignal) {
+  abortSignal?.throwIfAborted();
   let timeout;
+  let abort;
   try {
     return await Promise.race([
       promise.then(() => true),
       new Promise((resolve) => {
         timeout = setTimeout(() => resolve(false), timeoutMs);
         timeout.unref?.();
+      }),
+      new Promise((_, reject) => {
+        if (abortSignal === void 0) return;
+        abort = () => reject(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        if (abortSignal.aborted) abort();
+        else abortSignal.addEventListener("abort", abort, { once: true });
       })
     ]);
   } finally {
     if (timeout !== void 0) clearTimeout(timeout);
+    if (abort !== void 0) abortSignal?.removeEventListener("abort", abort);
   }
 }
-async function waitForDelay(timeoutMs) {
-  await new Promise((resolve) => {
-    const timeout = setTimeout(resolve, timeoutMs);
-    timeout.unref?.();
-  });
+async function waitForDelay(timeoutMs, abortSignal) {
+  await waitForPromise(
+    new Promise((resolve) => {
+      const timeout = setTimeout(resolve, timeoutMs);
+      timeout.unref?.();
+    }),
+    timeoutMs,
+    abortSignal
+  );
 }
 
 // src/text-file.ts
@@ -586,13 +590,31 @@ function decodeCompleteUtf8(bytes) {
 }
 
 // src/docker-sandbox.ts
-var defaultImage = "node:22-bookworm";
+var schemaVersion = "1";
+var labelPrefix = "anvia.sandbox.";
 var defaultWorkdir = "/workspace";
-var defaultTimeoutMs = 3e4;
+var defaultCommandTimeoutMs = 3e4;
 var defaultMaxOutputBytes = 1024 * 1024;
+var defaultMaxFileBytes = 10 * 1024 * 1024;
 var defaultMaxProcesses = 4;
 var defaultTextFilePageLines = 500;
 var defaultTextFilePageBytes = 64 * 1024;
+var defaultPortWaitTimeoutMs = 3e4;
+var defaultPortWaitIntervalMs = 100;
+var idPattern = /^[a-z0-9](?:[a-z0-9_.-]{0,62})$/;
+var envKeyPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var labels = {
+  schema: `${labelPrefix}schema`,
+  id: `${labelPrefix}id`,
+  workdir: `${labelPrefix}workdir`,
+  workspaceType: `${labelPrefix}workspace.type`,
+  workspaceVolume: `${labelPrefix}workspace.volume`,
+  networkMode: `${labelPrefix}network.mode`,
+  commandTimeoutMs: `${labelPrefix}runtime.command-timeout-ms`,
+  maxOutputBytes: `${labelPrefix}runtime.max-output-bytes`,
+  maxFileBytes: `${labelPrefix}runtime.max-file-bytes`,
+  maxProcesses: `${labelPrefix}runtime.max-processes`
+};
 var portProbeScript = [
   `port="$(printf '%04X' "$1")"`,
   "for table in /proc/net/tcp /proc/net/tcp6; do",
@@ -607,1238 +629,1851 @@ var portProbeScript = [
   "done",
   "exit 1"
 ].join("\n");
-var textFilePageScript = [
-  'start="$1"',
-  'count="$2"',
-  'max_bytes="$3"',
-  'file="$4"',
-  'end="$((start + count))"',
-  '[ -f "$file" ] || { echo "Not a readable file: $file" >&2; exit 66; }',
-  'sed -n "$start,$end p;$end q" "$file" | head -c "$max_bytes"'
-].join("\n");
-var DockerSandbox = class _DockerSandbox {
-  provider = "docker";
-  image;
-  pull;
-  workdir;
-  workspace;
-  lifecycle;
-  network;
+var DockerSandboxClient = class {
   dockerPath;
-  labels;
-  limits;
-  security;
-  hooks;
-  user;
   constructor(options = {}) {
-    this.image = options.image ?? defaultImage;
-    this.pull = options.pull ?? "missing";
-    this.workdir = options.workdir ?? defaultWorkdir;
-    this.workspace = options.workspace ?? { mode: "ephemeral" };
-    const lifecycle = {
-      autoDestroy: options.lifecycle?.autoDestroy ?? true
-    };
-    if (options.lifecycle?.ttlMs !== void 0) lifecycle.ttlMs = options.lifecycle.ttlMs;
-    if (options.lifecycle?.idleTimeoutMs !== void 0) {
-      lifecycle.idleTimeoutMs = options.lifecycle.idleTimeoutMs;
-    }
-    this.lifecycle = lifecycle;
-    this.network = options.network ?? false;
+    if (!isRecord(options)) throw new TypeError("options must be an object.");
     this.dockerPath = options.dockerPath ?? "docker";
-    this.labels = options.labels ?? {};
-    this.limits = options.limits ?? {};
-    this.security = {
-      readonlyRootfs: options.security?.readonlyRootfs ?? false,
-      noNewPrivileges: options.security?.noNewPrivileges ?? true,
-      dropCapabilities: options.security?.dropCapabilities ?? ["ALL"]
-    };
-    this.hooks = options.hooks ?? {};
-    this.user = options.user;
-  }
-  static node(options = {}) {
-    return new _DockerSandbox({ ...options, image: options.image ?? "node:22-bookworm" });
-  }
-  static python(options = {}) {
-    return new _DockerSandbox({ ...options, image: options.image ?? "python:3.13-bookworm" });
-  }
-  static deno(options = {}) {
-    return new _DockerSandbox({ ...options, image: options.image ?? "denoland/deno:debian" });
-  }
-  async createSession(options = {}) {
-    const ports = validatePublishedPorts(options.ports ?? []);
-    this.assertPortNetworkCompatible(ports);
-    await this.ensureImage();
-    const id = sanitizeResourceId(options.id ?? randomUUID2());
-    const workspace = options.workspace ?? this.workspace;
-    const workspaceId = getWorkspaceId(workspace, id);
-    const containerName = `anvia-sandbox-${id}`;
-    const volumeName = `anvia-sandbox-${workspaceId}-workspace`;
-    const removeVolumeOnDestroy = shouldDestroyWorkspace(workspace);
-    await assertDockerCli(["volume", "create", volumeName], this.cliOptions());
+    assertNonEmptyString(this.dockerPath, "dockerPath");
+  }
+  async pullImage(options) {
+    if (!isRecord(options)) throw new TypeError("options must be an object.");
+    assertNonEmptyString(options.image, "image");
+    options.abortSignal?.throwIfAborted();
+    await assertDockerCli(["pull", options.image], this.cliOptions(options.abortSignal));
+  }
+  async createSandbox(options) {
+    validateCreateOptions(options);
+    options = snapshotCreateOptions(options);
+    options.abortSignal?.throwIfAborted();
+    const id = options.id ?? randomUUID2();
+    assertSandboxId(id);
+    const containerName = containerNameFor(id);
+    const workdir = options.workdir ?? defaultWorkdir;
+    const runtime = resolveRuntimeLimits(options.runtime);
+    const workspace = copyWorkspace(options.workspace);
+    const network = copyNetwork(options.network);
+    const env = copyStringRecord(options.env, "env");
+    const userLabels = copyStringRecord(options.labels, "labels");
+    const volumeName = workspace.type === "ephemeral" ? `${containerName}-workspace-${randomUUID2()}` : workspace.name;
+    const ownsVolume = workspace.type === "ephemeral";
+    await this.assertContainerDoesNotExist(containerName, options.abortSignal);
+    await this.assertImageExists(options.image, options.abortSignal);
+    if (workspace.type === "docker-volume") {
+      await this.assertVolumeExists(workspace.name, options.abortSignal);
+    }
+    let containerCreated = false;
+    let volumeCreated = false;
     try {
+      if (workspace.type === "ephemeral") {
+        await assertDockerCli(
+          ["volume", "create", "--label", `${labels.id}=${id}`, volumeName],
+          this.cliOptions(options.abortSignal)
+        );
+        volumeCreated = true;
+      }
       await assertDockerCli(
-        this.createRunArgs(containerName, volumeName, workspace, options.metadata, ports),
+        createRunArgs({
+          id,
+          containerName,
+          image: options.image,
+          workdir,
+          workspace,
+          volumeName,
+          env,
+          user: options.user,
+          userLabels,
+          resources: options.resources,
+          runtime,
+          security: options.security,
+          network
+        }),
         {
-          ...this.cliOptions(),
-          timeoutMs: this.limits.timeoutMs ?? defaultTimeoutMs
+          ...this.cliOptions(options.abortSignal),
+          timeoutMs: runtime.commandTimeoutMs
         }
       );
-      const publishedPorts = await this.inspectPublishedPorts(containerName, ports);
-      const session = new DockerSandboxSessionImpl({
+      containerCreated = true;
+      const publishedPorts = await inspectPublishedPorts({
+        dockerPath: this.dockerPath,
+        containerName,
+        ports: network.mode === "bridge" ? [...network.ports ?? []] : [],
+        abortSignal: options.abortSignal
+      });
+      const sandbox = this.createHandle({
         id,
         containerName,
+        workdir,
+        workspace,
         volumeName,
-        workdir: this.workdir,
-        dockerPath: this.dockerPath,
-        limits: this.limits,
-        lifecycle: this.lifecycle,
-        removeVolumeOnDestroy,
-        env: options.manifest?.env ?? {},
-        hooks: this.hooks,
+        ownsVolume,
+        env,
+        runtime,
         publishedPorts
       });
-      await session.applyManifest(options.manifest);
-      await this.hooks.onSessionCreate?.(session.event());
-      return session;
+      await applyInitialContent(sandbox.runtime, options);
+      return sandbox;
     } catch (error) {
-      await this.cleanup(containerName, removeVolumeOnDestroy ? volumeName : void 0);
+      const cleanupErrors = [];
+      if (containerCreated) {
+        try {
+          await removeContainer(this.dockerPath, containerName);
+        } catch (cleanupError) {
+          cleanupErrors.push(cleanupError);
+        }
+      }
+      if (ownsVolume && volumeCreated) {
+        try {
+          await removeVolume(this.dockerPath, volumeName);
+        } catch (cleanupError) {
+          cleanupErrors.push(cleanupError);
+        }
+      }
+      if (cleanupErrors.length > 0) {
+        throw new AggregateError([error, ...cleanupErrors], "Sandbox creation and rollback failed");
+      }
       throw error;
     }
   }
-  async ensureImage() {
-    if (this.pull === "always") {
-      await assertDockerCli(["pull", this.image], this.cliOptions());
-      return;
+  async resumeSandbox(options) {
+    if (!isRecord(options)) throw new TypeError("options must be an object.");
+    assertSandboxId(options.id);
+    options.abortSignal?.throwIfAborted();
+    const containerName = containerNameFor(options.id);
+    const inspection = await inspectContainer(
+      this.dockerPath,
+      containerName,
+      options.abortSignal,
+      true
+    );
+    const configuration = configurationFromInspection(options.id, containerName, inspection);
+    if (inspection.State.Paused === true || inspection.State.Dead === true) {
+      throw new DockerSandboxError(
+        `Sandbox cannot be resumed from Docker state: ${inspection.State.Status ?? "unknown"}`,
+        "invalid_state"
+      );
     }
-    if (this.pull === "missing") {
-      const inspect = await runDockerCli(["image", "inspect", this.image], this.cliOptions());
-      if (inspect.exitCode !== 0) {
-        await assertDockerCli(["pull", this.image], this.cliOptions());
-      }
+    if (inspection.State.Running === true) {
+      await assertDockerCli(["stop", containerName], this.cliOptions(options.abortSignal));
     }
-  }
-  createRunArgs(containerName, volumeName, workspace, metadata, ports) {
-    const args = [
-      "run",
-      "-d",
-      "--name",
+    await assertDockerCli(["start", containerName], this.cliOptions(options.abortSignal));
+    configuration.publishedPorts = await inspectPublishedPorts({
+      dockerPath: this.dockerPath,
       containerName,
-      "-v",
-      `${volumeName}:${this.workdir}`,
-      "-w",
-      this.workdir,
-      "--label",
-      "anvia.sandbox=true",
-      "--label",
-      `anvia.sandbox.workspace.mode=${workspace.mode ?? "ephemeral"}`,
-      "--label",
-      `anvia.sandbox.workspace.volume=${volumeName}`
-    ];
-    for (const [key, value] of Object.entries(this.labels)) {
-      args.push("--label", `${key}=${value}`);
-    }
-    if (metadata !== void 0) {
-      for (const [key, value] of Object.entries(metadata)) {
-        args.push("--label", `anvia.sandbox.metadata.${key}=${value}`);
-      }
-    }
-    this.appendNetworkArgs(args);
-    for (const port of ports) {
-      args.push("--publish", `127.0.0.1::${port}/tcp`);
+      ports: configuredContainerPorts(inspection),
+      abortSignal: options.abortSignal
+    });
+    return this.createHandle(configuration);
+  }
+  createHandle(configuration) {
+    return new DockerSandboxHandle({
+      dockerPath: this.dockerPath,
+      configuration
+    });
+  }
+  async assertImageExists(image, abortSignal) {
+    const result = await runDockerCli(["image", "inspect", image], this.cliOptions(abortSignal));
+    if (result.exitCode === 0) return;
+    const message = safeDecode(result.stderr);
+    if (message.toLowerCase().includes("no such image")) {
+      throw new DockerSandboxError(
+        `Docker image is not available locally: ${image}`,
+        "image_not_found"
+      );
     }
-    this.appendLimitArgs(args);
-    this.appendSecurityArgs(args);
-    if (this.user !== void 0) {
-      args.push("-u", this.user);
+    throw new DockerSandboxError(
+      "Unable to inspect Docker image.",
+      "docker_command_failed",
+      result
+    );
+  }
+  async assertContainerDoesNotExist(containerName, abortSignal) {
+    const result = await runDockerCli(["container", "inspect", containerName], {
+      ...this.cliOptions(abortSignal),
+      maxOutputBytes: defaultMaxOutputBytes
+    });
+    if (result.exitCode === 0) {
+      throw new DockerSandboxError(
+        `A Docker container already exists for sandbox: ${containerName}`,
+        "invalid_state"
+      );
     }
-    args.push(
-      this.image,
-      "sh",
-      "-c",
-      "trap 'exit 0' TERM INT; while :; do sleep 3600 & wait $!; done"
+    if (safeDecode(result.stderr).toLowerCase().includes("no such")) return;
+    throw new DockerSandboxError(
+      "Unable to check whether the Docker sandbox already exists.",
+      "docker_command_failed",
+      result
     );
-    return args;
   }
-  appendNetworkArgs(args) {
-    const mode = typeof this.network === "object" ? this.network.mode : this.network;
-    if (mode === false || mode === "none") {
-      args.push("--network", "none");
-      return;
+  async assertVolumeExists(name, abortSignal) {
+    const result = await runDockerCli(["volume", "inspect", name], this.cliOptions(abortSignal));
+    if (result.exitCode === 0) return;
+    const message = safeDecode(result.stderr);
+    if (message.toLowerCase().includes("no such volume")) {
+      throw new DockerSandboxError(`Docker volume does not exist: ${name}`, "volume_not_found");
+    }
+    throw new DockerSandboxError(
+      "Unable to inspect Docker volume.",
+      "docker_command_failed",
+      result
+    );
+  }
+  cliOptions(abortSignal) {
+    return { dockerPath: this.dockerPath, signal: abortSignal };
+  }
+};
+var DockerSandboxHandle = class {
+  id;
+  runtime;
+  currentState = "running";
+  dockerPath;
+  configuration;
+  runtimeImpl;
+  stopPromise;
+  destroyPromise;
+  constructor(options) {
+    this.dockerPath = options.dockerPath;
+    this.configuration = options.configuration;
+    this.id = options.configuration.id;
+    this.runtimeImpl = new DockerSandboxRuntimeImpl({
+      configuration: options.configuration,
+      dockerPath: options.dockerPath,
+      state: () => this.currentState
+    });
+    this.runtime = Object.freeze(this.runtimeImpl.publicRuntime());
+  }
+  get state() {
+    return this.currentState;
+  }
+  inspector(options) {
+    if (!isRecord(options)) throw new TypeError("options must be an object.");
+    if (options.files !== true && options.ports !== true && options.processes !== true) {
+      throw new TypeError("Sandbox inspector must enable at least one capability.");
+    }
+    let inspector = {
+      id: this.id,
+      provider: "docker",
+      workdir: this.configuration.workdir
+    };
+    if (options.files === true) {
+      inspector = {
+        ...inspector,
+        listFiles: this.runtime.listFiles.bind(this.runtime),
+        readFile: this.runtime.readFile.bind(this.runtime)
+      };
     }
-    if (mode !== true) {
-      args.push("--network", mode);
+    if (options.ports === true) {
+      inspector = { ...inspector, publishedPorts: this.runtime.publishedPorts };
     }
+    if (options.processes === true) {
+      inspector = {
+        ...inspector,
+        listProcesses: this.runtime.listProcesses.bind(this.runtime),
+        readProcessLogs: this.runtime.readProcessLogs.bind(this.runtime)
+      };
+    }
+    return Object.freeze(inspector);
   }
-  assertPortNetworkCompatible(ports) {
-    if (ports.length === 0) return;
-    const mode = typeof this.network === "object" ? this.network.mode : this.network;
-    if (mode === false || mode === "none" || mode === "host" || typeof mode === "string" && mode.startsWith("container:")) {
-      throw new SandboxPortError(
-        "Published sandbox ports require network: true or a bridge-capable Docker network."
-      );
+  async stop(options = {}) {
+    if (!isRecord(options)) throw new TypeError("options must be an object.");
+    if (this.currentState === "stopped") return;
+    if (this.currentState === "destroyed" || this.currentState === "destroying") {
+      throw invalidState(this.id, this.currentState);
+    }
+    if (this.stopPromise !== void 0) return this.stopPromise;
+    this.stopPromise = this.performStop(options.abortSignal);
+    try {
+      await this.stopPromise;
+    } finally {
+      this.stopPromise = void 0;
     }
   }
-  async inspectPublishedPorts(containerName, ports) {
-    if (ports.length === 0) return [];
-    const raw = await assertDockerCli(
-      ["container", "inspect", "--format", "{{json .NetworkSettings.Ports}}", containerName],
-      this.cliOptions()
-    );
-    let mappings;
+  async performStop(abortSignal) {
+    abortSignal?.throwIfAborted();
+    this.currentState = "stopping";
     try {
-      mappings = JSON.parse(raw);
+      await this.runtimeImpl.closeActiveOperations("Sandbox is stopping.");
+      await this.runtimeImpl.disposeProcesses(abortSignal);
+      await assertDockerCli(["stop", this.configuration.containerName], {
+        dockerPath: this.dockerPath,
+        signal: abortSignal
+      });
+      this.currentState = "stopped";
     } catch (error) {
-      throw new SandboxPortError("Docker returned invalid published port metadata.", error);
-    }
-    if (!isRecord(mappings)) {
-      throw new SandboxPortError("Docker returned invalid published port metadata.");
+      this.currentState = "error";
+      throw error;
     }
-    return ports.map((containerPort) => {
-      const entries = mappings[`${containerPort}/tcp`];
-      if (!Array.isArray(entries)) {
-        throw new SandboxPortError(`Docker did not publish sandbox port ${containerPort}/tcp.`);
-      }
-      const entry = entries.find(
-        (candidate) => isRecord(candidate) && candidate.HostIp === "127.0.0.1" && typeof candidate.HostPort === "string"
-      );
-      if (!isRecord(entry) || typeof entry.HostPort !== "string") {
-        throw new SandboxPortError(
-          `Docker did not bind sandbox port ${containerPort}/tcp to 127.0.0.1.`
-        );
-      }
-      const hostPort = Number(entry.HostPort);
-      if (!isValidPort(hostPort)) {
-        throw new SandboxPortError(
-          `Docker returned an invalid host port for ${containerPort}/tcp.`
-        );
-      }
-      return { containerPort, host: "127.0.0.1", hostPort, protocol: "tcp" };
-    });
   }
-  appendLimitArgs(args) {
-    if (this.limits.memoryMb !== void 0) {
-      args.push("--memory", `${this.limits.memoryMb}m`);
+  async destroy() {
+    if (this.currentState === "destroyed") return;
+    if (this.destroyPromise !== void 0) return this.destroyPromise;
+    this.destroyPromise = this.performDestroy();
+    try {
+      await this.destroyPromise;
+    } finally {
+      this.destroyPromise = void 0;
     }
-    if (this.limits.cpus !== void 0) {
-      args.push("--cpus", String(this.limits.cpus));
+  }
+  async performDestroy() {
+    if (this.stopPromise !== void 0) await this.stopPromise.catch(() => void 0);
+    this.currentState = "destroying";
+    const failures = [];
+    try {
+      await this.runtimeImpl.closeActiveOperations("Sandbox is being destroyed.");
+    } catch (error) {
+      failures.push(error);
     }
-    if (this.limits.pidsLimit !== void 0) {
-      args.push("--pids-limit", String(this.limits.pidsLimit));
+    try {
+      await this.runtimeImpl.disposeProcesses();
+    } catch (error) {
+      failures.push(error);
     }
-  }
-  appendSecurityArgs(args) {
-    if (this.security.readonlyRootfs) {
-      args.push("--read-only");
+    try {
+      await removeContainer(this.dockerPath, this.configuration.containerName);
+    } catch (error) {
+      failures.push(error);
     }
-    if (this.security.noNewPrivileges) {
-      args.push("--security-opt", "no-new-privileges");
+    if (this.configuration.ownsVolume) {
+      try {
+        await removeVolume(this.dockerPath, this.configuration.volumeName);
+      } catch (error) {
+        failures.push(error);
+      }
     }
-    for (const capability of this.security.dropCapabilities) {
-      args.push("--cap-drop", capability);
+    if (failures.length > 0) {
+      this.currentState = "error";
+      throw new AggregateError(failures, `Unable to destroy sandbox: ${this.id}`);
     }
+    this.currentState = "destroyed";
   }
-  cliOptions() {
-    return {
-      dockerPath: this.dockerPath,
-      maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes
-    };
-  }
-  async cleanup(containerName, volumeName) {
-    await runDockerCli(["rm", "-f", containerName], this.cliOptions()).catch(() => void 0);
-    if (volumeName !== void 0) {
-      await runDockerCli(["volume", "rm", "-f", volumeName], this.cliOptions()).catch(
-        () => void 0
-      );
-    }
+  async [Symbol.asyncDispose]() {
+    await this.destroy();
   }
 };
-var DockerSandboxSessionImpl = class {
-  provider = "docker";
-  id;
-  workdir;
-  publishedPorts;
-  containerName;
-  volumeName;
+var DockerSandboxRuntimeImpl = class {
+  configuration;
   dockerPath;
-  limits;
-  lifecycle;
-  removeVolumeOnDestroy;
-  env;
-  hooks;
+  state;
   processManager;
-  ttlTimer;
-  idleTimer;
-  activeOperations = 0;
-  destroyed = false;
+  activeControllers = /* @__PURE__ */ new Set();
+  activeOperations = /* @__PURE__ */ new Set();
+  processDisposed = false;
   constructor(options) {
-    this.id = options.id;
-    this.containerName = options.containerName;
-    this.volumeName = options.volumeName;
-    this.workdir = options.workdir;
+    this.configuration = options.configuration;
     this.dockerPath = options.dockerPath;
-    this.limits = options.limits;
-    this.lifecycle = options.lifecycle;
-    this.removeVolumeOnDestroy = options.removeVolumeOnDestroy;
-    this.env = options.env;
-    this.hooks = options.hooks;
-    this.publishedPorts = options.publishedPorts;
+    this.state = options.state;
     this.processManager = new DockerProcessManager({
-      containerName: this.containerName,
-      dockerPath: this.dockerPath,
-      workdir: this.workdir,
-      env: this.env,
-      maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes,
-      maxProcesses: this.limits.maxProcesses ?? defaultMaxProcesses,
-      startupTimeoutMs: this.limits.timeoutMs ?? defaultTimeoutMs,
-      onStart: async (process) => {
-        const event = {
-          ...this.event(),
-          command: process.command,
-          args: process.args
-        };
-        if (process.cwd !== void 0) event.cwd = process.cwd;
-        await this.hooks.onExecStart?.(event);
-      },
-      onExit: async (process, logs, durationMs) => {
-        const event = {
-          ...this.event(),
-          command: process.command,
-          args: process.args,
-          result: {
-            stdout: logs.stdout,
-            stderr: logs.stderr,
-            exitCode: process.exitCode ?? 1,
-            durationMs,
-            timedOut: false,
-            aborted: process.status === "stopped",
-            stdoutTruncated: logs.stdoutTruncated,
-            stderrTruncated: logs.stderrTruncated
-          }
-        };
-        if (process.cwd !== void 0) event.cwd = process.cwd;
-        await this.hooks.onExecEnd?.(event);
-      }
+      containerName: options.configuration.containerName,
+      dockerPath: options.dockerPath,
+      workdir: options.configuration.workdir,
+      env: options.configuration.env,
+      maxOutputBytes: options.configuration.runtime.maxOutputBytes,
+      maxProcesses: options.configuration.runtime.maxProcesses,
+      startupTimeoutMs: options.configuration.runtime.commandTimeoutMs
     });
-    this.startLifecycleTimers();
   }
-  async applyManifest(manifest) {
-    await this.runOperation(async () => {
-      for (const directory of manifest?.directories ?? []) {
-        await this.mkdir(directory);
-      }
-      for (const [filePath, content] of Object.entries(manifest?.files ?? {})) {
-        await this.writeFile(filePath, content);
-      }
-    });
+  publicRuntime() {
+    return {
+      id: this.configuration.id,
+      provider: "docker",
+      workdir: this.configuration.workdir,
+      publishedPorts: Object.freeze(
+        this.configuration.publishedPorts.map((port) => Object.freeze({ ...port }))
+      ),
+      exec: (options) => this.exec(options),
+      execStream: (options) => this.execStream(options),
+      readFile: (options) => this.readFile(options),
+      readTextFile: (options) => this.readTextFile(options),
+      readTextFilePage: (options) => this.readTextFilePage(options),
+      writeFile: (options) => this.writeFile(options),
+      writeTextFile: (options) => this.writeTextFile(options),
+      listFiles: (options) => this.listFiles(options),
+      startProcess: (options) => this.startProcess(options),
+      listProcesses: (options) => this.listProcesses(options),
+      readProcessLogs: (options) => this.readProcessLogs(options),
+      stopProcess: (options) => this.stopProcess(options),
+      waitForPort: (options) => this.waitForPort(options)
+    };
   }
   async exec(options) {
-    return this.runOperation(async () => {
-      const startEvent = {
-        ...this.event(),
-        command: options.command,
-        args: options.args ?? []
-      };
-      if (options.cwd !== void 0) startEvent.cwd = options.cwd;
-      await this.hooks.onExecStart?.(startEvent);
-      const normalizedResult = await this.execCommand(options);
-      const endEvent = {
-        ...this.event(),
-        command: options.command,
-        args: options.args ?? [],
-        result: normalizedResult
-      };
-      if (options.cwd !== void 0) endEvent.cwd = options.cwd;
-      await this.hooks.onExecEnd?.(endEvent);
-      return normalizedResult;
+    validateExecOptions(options);
+    return this.runOperation(options.abortSignal, async (abortSignal) => {
+      const result = await runDockerCli(this.execArgs(options), {
+        dockerPath: this.dockerPath,
+        timeoutMs: options.timeoutMs ?? this.configuration.runtime.commandTimeoutMs,
+        maxOutputBytes: this.configuration.runtime.maxOutputBytes,
+        input: options.input,
+        signal: abortSignal
+      });
+      return toExecResult(result);
     });
   }
   async *execStream(options) {
-    const events = [];
-    let notify;
-    let done = false;
-    let error;
+    validateExecOptions(options);
+    this.assertRunning();
+    const streamAbort = new AbortController();
+    const combined = combineSignals(options.abortSignal, streamAbort.signal);
+    const queue = [];
+    let queuedBytes = 0;
+    let wake;
+    let complete = false;
+    let failure;
     const push = (event) => {
-      events.push(event);
-      notify?.();
-      notify = void 0;
+      if (event.type !== "result") {
+        queuedBytes += event.data.byteLength;
+        if (queuedBytes > this.configuration.runtime.maxOutputBytes) {
+          streamAbort.abort(
+            new DockerSandboxError("Sandbox stream consumer is too slow.", "docker_command_failed")
+          );
+          return;
+        }
+      }
+      queue.push(event);
+      wake?.();
+      wake = void 0;
     };
-    const wait = () => new Promise((resolve) => {
-      notify = resolve;
+    const run = this.runOperation(combined, async (abortSignal) => {
+      const result = await runDockerCli(this.execArgs(options), {
+        dockerPath: this.dockerPath,
+        timeoutMs: options.timeoutMs ?? this.configuration.runtime.commandTimeoutMs,
+        maxOutputBytes: this.configuration.runtime.maxOutputBytes,
+        input: options.input,
+        signal: abortSignal,
+        onStdout: (data) => push({ type: "stdout", data: data.slice() }),
+        onStderr: (data) => push({ type: "stderr", data: data.slice() })
+      });
+      push({ type: "result", result: toExecResult(result) });
     });
-    const run = this.exec({
-      ...options,
-      onStdout: (chunk) => {
-        options.onStdout?.(chunk);
-        push({ type: "stdout", chunk, text: Buffer.from(chunk).toString("utf8") });
+    void run.then(
+      () => {
+        complete = true;
+        wake?.();
       },
-      onStderr: (chunk) => {
-        options.onStderr?.(chunk);
-        push({ type: "stderr", chunk, text: Buffer.from(chunk).toString("utf8") });
+      (error) => {
+        failure = error;
+        complete = true;
+        wake?.();
       }
-    }).then((result) => {
-      push({ type: "exit", result });
-    }).catch((caught) => {
-      error = caught;
-    }).finally(() => {
-      done = true;
-      notify?.();
-      notify = void 0;
-    });
+    );
     try {
-      while (!done || events.length > 0) {
-        const event = events.shift();
+      while (!complete || queue.length > 0) {
+        const event = queue.shift();
         if (event !== void 0) {
+          if (event.type !== "result") queuedBytes -= event.data.byteLength;
           yield event;
           continue;
         }
-        await wait();
-      }
-      if (error !== void 0) {
-        throw error;
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
       }
+      if (failure !== void 0) throw failure;
     } finally {
-      await run;
+      if (!complete) streamAbort.abort(new DOMException("Stream closed", "AbortError"));
+      await run.catch(() => void 0);
     }
   }
-  async startProcess(options) {
-    return this.runOperation(async () => this.processManager.start(options));
-  }
-  async listProcesses() {
-    return this.runOperation(async () => this.processManager.list());
-  }
-  async readProcessLogs(processId, options) {
-    return this.runOperation(async () => this.processManager.logs(processId, options));
-  }
-  async stopProcess(processId, options) {
-    return this.runOperation(async () => this.processManager.stop(processId, options));
-  }
-  async waitForPort(containerPort, options = {}) {
-    return this.runOperation(async () => {
-      const publishedPort = this.publishedPorts.find(
-        (candidate) => candidate.containerPort === containerPort
-      );
-      if (publishedPort === void 0) {
-        throw new SandboxPortError(`Sandbox port is not published: ${containerPort}/tcp`);
-      }
-      const timeoutMs = options.timeoutMs ?? this.limits.timeoutMs ?? defaultTimeoutMs;
-      const intervalMs = options.intervalMs ?? 250;
-      assertWaitOptions(timeoutMs, intervalMs);
-      const deadline = Date.now() + timeoutMs;
-      while (true) {
-        this.assertActive();
-        if (options.signal?.aborted === true) throw abortReason(options.signal);
-        const remainingMs = deadline - Date.now();
-        if (remainingMs <= 0) {
-          throw new SandboxTimeoutError(`Waiting for sandbox port ${containerPort}/tcp timed out.`);
-        }
-        const probeTimeoutMs = Math.min(1e3, remainingMs);
-        if (await this.isPortListening(containerPort, probeTimeoutMs)) {
-          return publishedPort;
-        }
-        const remainingAfterProbeMs = deadline - Date.now();
-        if (remainingAfterProbeMs <= 0) {
-          throw new SandboxTimeoutError(`Waiting for sandbox port ${containerPort}/tcp timed out.`);
-        }
-        await waitWithSignal(Math.min(intervalMs, remainingAfterProbeMs), options.signal);
-      }
-    });
-  }
-  async readFile(filePath) {
-    return this.runOperation(async () => {
-      const normalized = normalizeSandboxPath(filePath);
+  async readFile(options) {
+    assertReadOptions(options);
+    return this.runOperation(options.abortSignal, async (abortSignal) => {
+      const normalized = normalizeSandboxPath(options.path);
       const tempDir = await mkdtemp(path2.join(os.tmpdir(), "anvia-sandbox-read-"));
       const target = path2.join(tempDir, path2.basename(normalized));
       try {
         await assertDockerCli(
-          ["cp", `${this.containerName}:${containerPath(this.workdir, normalized)}`, target],
-          this.cliOptions()
+          [
+            "cp",
+            `${this.configuration.containerName}:${containerPath(this.configuration.workdir, normalized)}`,
+            target
+          ],
+          { dockerPath: this.dockerPath, signal: abortSignal }
         );
-        const { readFile } = await import("fs/promises");
-        const bytes = await readFile(target);
-        this.assertFileSize(bytes.byteLength, filePath);
-        return bytes;
+        await assertCopiedRegularFile(tempDir, target, normalized);
+        const bytes = await readFile(target, { signal: abortSignal });
+        this.assertFileSize(bytes.byteLength, normalized);
+        return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength).slice();
       } finally {
         await rm(tempDir, { recursive: true, force: true });
       }
     });
   }
-  async readTextFile(filePath) {
-    const bytes = await this.readFile(filePath);
-    return new TextDecoder().decode(bytes);
-  }
-  async readTextFilePage(filePath, options = {}) {
-    return this.runOperation(async () => {
-      const startLine = options.startLine ?? 1;
-      const lineCount = options.lineCount ?? defaultTextFilePageLines;
-      const maxBytes = options.maxBytes ?? defaultTextFilePageBytes;
-      assertTextFileReadOptions(startLine, lineCount, maxBytes);
-      const normalized = normalizeSandboxPath(filePath);
-      const captureBytes = maxBytes + 4;
-      const result = await runDockerCli(
-        [
-          "exec",
-          "-w",
-          this.workdir,
-          this.containerName,
-          "sh",
-          "-c",
-          textFilePageScript,
-          "anvia-read-file-page",
-          String(startLine),
-          String(lineCount),
-          String(captureBytes),
-          containerPath(this.workdir, normalized)
-        ],
-        {
-          ...this.cliOptions(),
-          maxOutputBytes: captureBytes
-        }
-      );
-      if (result.exitCode !== 0) {
-        throw new SandboxDockerCommandError(
-          `Unable to read sandbox text file: ${filePath}`,
-          result
-        );
-      }
-      return createTextFilePage(result.stdout, {
-        startLine,
-        lineCount,
-        maxBytes,
-        contentStartLine: startLine
-      });
-    });
+  async readTextFile(options) {
+    return decodeUtf8(await this.readFile(options));
+  }
+  async readTextFilePage(options) {
+    assertReadOptions(options);
+    const startLine = options.startLine ?? 1;
+    const lineCount = options.lineCount ?? defaultTextFilePageLines;
+    const maxBytes = options.maxBytes ?? defaultTextFilePageBytes;
+    assertPositiveSafeInteger(startLine, "startLine");
+    assertPositiveSafeInteger(lineCount, "lineCount");
+    assertPositiveSafeInteger(maxBytes, "maxBytes");
+    let readOptions = {
+      path: options.path
+    };
+    if (options.abortSignal !== void 0) {
+      readOptions = { ...readOptions, abortSignal: options.abortSignal };
+    }
+    const text = await this.readTextFile(readOptions);
+    return createTextFilePage(text, { startLine, lineCount, maxBytes });
+  }
+  async writeFile(options) {
+    assertOptionsObject(options);
+    if (!(options.data instanceof Uint8Array)) throw new TypeError("data must be a Uint8Array.");
+    const data = options.data.slice();
+    await this.writeBytes(options.path, data, options.abortSignal);
+  }
+  async writeTextFile(options) {
+    assertOptionsObject(options);
+    if (typeof options.text !== "string") throw new TypeError("text must be a string.");
+    await this.writeBytes(
+      options.path,
+      new TextEncoder().encode(options.text),
+      options.abortSignal
+    );
   }
-  async writeFile(filePath, data) {
-    await this.runOperation(async () => {
-      const size = byteLength(data);
-      this.assertFileSize(size, filePath);
-      const normalized = normalizeSandboxPath(filePath);
-      await this.mkdir(parentSandboxPath(normalized));
+  async writeBytes(filePath, data, abortSignal) {
+    const normalized = normalizeSandboxPath(filePath);
+    this.assertFileSize(data.byteLength, normalized);
+    await this.runOperation(abortSignal, async (effectiveSignal) => {
+      await this.mkdir(parentSandboxPath(normalized), effectiveSignal);
       const tempDir = await mkdtemp(path2.join(os.tmpdir(), "anvia-sandbox-write-"));
       const source = path2.join(tempDir, path2.basename(normalized));
       try {
-        await writeFile(source, data);
+        await writeFile(source, data, { signal: effectiveSignal });
         await assertDockerCli(
-          ["cp", source, `${this.containerName}:${containerPath(this.workdir, normalized)}`],
-          this.cliOptions()
+          [
+            "cp",
+            source,
+            `${this.configuration.containerName}:${containerPath(this.configuration.workdir, normalized)}`
+          ],
+          { dockerPath: this.dockerPath, signal: effectiveSignal }
         );
-        await this.hooks.onFileWrite?.({ ...this.event(), path: normalized, size });
       } finally {
         await rm(tempDir, { recursive: true, force: true });
       }
     });
   }
-  async writeTextFile(filePath, content) {
-    await this.writeFile(filePath, content);
-  }
-  async listFiles(filePath = ".") {
-    return this.runOperation(async () => {
-      const normalized = normalizeSandboxPath(filePath, { allowRoot: true });
-      const target = containerPath(this.workdir, normalized);
-      const result = await this.execCommand({
-        command: "find",
-        args: [target, "-mindepth", "1", "-maxdepth", "1", "-printf", "%p	%y	%s\n"]
-      });
-      if (result.timedOut) {
-        throw new SandboxTimeoutError(`Listing files timed out for ${filePath}.`);
-      }
-      if (result.exitCode !== 0) {
-        throw new SandboxDockerCommandError(`Unable to list sandbox path: ${filePath}`, result);
+  async listFiles(options = {}) {
+    assertOptionsObject(options);
+    const requestedPath = options.path ?? ".";
+    const normalized = normalizeSandboxPath(requestedPath, { allowRoot: true });
+    return this.runOperation(options.abortSignal, async (abortSignal) => {
+      const result = await this.execCommand(
+        {
+          command: "find",
+          args: [
+            containerPath(this.configuration.workdir, normalized),
+            "-mindepth",
+            "1",
+            "-maxdepth",
+            "1",
+            "-printf",
+            "%p	%y	%s\n"
+          ]
+        },
+        abortSignal
+      );
+      if (result.status !== "exited" || result.exitCode !== 0) {
+        throw new DockerSandboxError(
+          "Unable to list sandbox files.",
+          "docker_command_failed",
+          result
+        );
       }
-      return result.stdout.split("\n").filter((line) => line.trim().length > 0).map((line) => this.parseFindEntry(line));
+      const output = decodeUtf8(result.stdout);
+      return output.split("\n").filter((line) => line.length > 0).map((line) => parseFindEntry(line, this.configuration.workdir));
     });
   }
-  async destroy() {
-    if (this.destroyed) {
-      return;
-    }
-    this.destroyed = true;
-    this.clearLifecycleTimers();
-    await this.processManager.dispose();
-    await runDockerCli(["rm", "-f", this.containerName], this.cliOptions()).catch(() => void 0);
-    if (this.removeVolumeOnDestroy) {
-      await runDockerCli(["volume", "rm", "-f", this.volumeName], this.cliOptions()).catch(
-        () => void 0
-      );
+  async startProcess(options) {
+    validateProcessStartOptions(options);
+    return this.runOperation(
+      options.abortSignal,
+      async (abortSignal) => this.processManager.start({ ...options, abortSignal })
+    );
+  }
+  async listProcesses(options = {}) {
+    assertOptionsObject(options);
+    return this.runOperation(options.abortSignal, async () => this.processManager.list());
+  }
+  async readProcessLogs(options) {
+    assertOptionsObject(options);
+    assertNonEmptyString(options.processId, "processId");
+    if (options.tailBytes !== void 0)
+      assertNonNegativeSafeInteger(options.tailBytes, "tailBytes");
+    return this.runOperation(
+      options.abortSignal,
+      async () => this.processManager.logs(options.processId, options.tailBytes)
+    );
+  }
+  async stopProcess(options) {
+    assertOptionsObject(options);
+    assertNonEmptyString(options.processId, "processId");
+    if (options.gracePeriodMs !== void 0) {
+      assertNonNegativeSafeInteger(options.gracePeriodMs, "gracePeriodMs");
     }
-    await this.hooks.onDestroy?.(this.event());
+    return this.runOperation(
+      options.abortSignal,
+      async (abortSignal) => this.processManager.stop(options.processId, options.gracePeriodMs, abortSignal)
+    );
   }
-  async mkdir(directoryPath) {
-    const normalized = normalizeSandboxPath(directoryPath, { allowRoot: true });
-    const result = await this.execCommand({
-      command: "mkdir",
-      args: ["-p", containerPath(this.workdir, normalized)]
-    });
-    if (result.exitCode !== 0) {
-      throw new SandboxDockerCommandError(
-        `Unable to create sandbox directory: ${directoryPath}`,
-        result
+  async waitForPort(options) {
+    assertOptionsObject(options);
+    assertPort(options.containerPort);
+    const publishedPort = this.configuration.publishedPorts.find(
+      (candidate) => candidate.containerPort === options.containerPort
+    );
+    if (publishedPort === void 0) {
+      throw new DockerSandboxError(
+        `Sandbox port is not published: ${options.containerPort}/tcp`,
+        "port"
       );
     }
+    const timeoutMs = options.timeoutMs ?? defaultPortWaitTimeoutMs;
+    const intervalMs = options.intervalMs ?? defaultPortWaitIntervalMs;
+    assertPositiveSafeInteger(timeoutMs, "timeoutMs");
+    assertPositiveSafeInteger(intervalMs, "intervalMs");
+    return this.runOperation(options.abortSignal, async (abortSignal) => {
+      const deadline = Date.now() + timeoutMs;
+      while (true) {
+        const result = await this.execCommand(
+          {
+            command: "sh",
+            args: ["-c", portProbeScript, "anvia-port-probe", `${options.containerPort}`],
+            timeoutMs: Math.min(5e3, timeoutMs)
+          },
+          abortSignal
+        );
+        if (result.status === "exited" && result.exitCode === 0) return { ...publishedPort };
+        if (Date.now() >= deadline) {
+          throw new DockerSandboxError(
+            `Waiting for sandbox port timed out: ${options.containerPort}`,
+            "timeout"
+          );
+        }
+        await waitWithSignal(Math.min(intervalMs, deadline - Date.now()), abortSignal);
+      }
+    });
   }
-  parseFindEntry(line) {
-    const [rawPath, rawType, rawSize] = line.split("	");
-    const absolutePath = rawPath ?? "";
-    const relativePath = absolutePath.startsWith(`${this.workdir}/`) ? absolutePath.slice(this.workdir.length + 1) : absolutePath;
-    const size = rawSize === void 0 ? void 0 : Number(rawSize);
-    const entry = {
-      path: relativePath,
-      type: mapFindType(rawType)
-    };
-    if (size !== void 0 && Number.isFinite(size)) {
-      entry.size = size;
+  async closeActiveOperations(message) {
+    const reason = new DockerSandboxError(message, "invalid_state");
+    for (const controller of this.activeControllers) controller.abort(reason);
+    await Promise.allSettled([...this.activeOperations]);
+  }
+  async disposeProcesses(abortSignal) {
+    if (this.processDisposed) return;
+    await this.processManager.dispose(abortSignal);
+    this.processDisposed = true;
+  }
+  async runOperation(abortSignal, operation) {
+    this.assertRunning();
+    abortSignal?.throwIfAborted();
+    const controller = new AbortController();
+    const effectiveSignal = combineSignals(abortSignal, controller.signal);
+    const execution = operation(effectiveSignal);
+    this.activeControllers.add(controller);
+    this.activeOperations.add(execution);
+    try {
+      return await execution;
+    } finally {
+      this.activeControllers.delete(controller);
+      this.activeOperations.delete(execution);
     }
-    return entry;
   }
-  cliOptions() {
-    return {
+  assertRunning() {
+    const current = this.state();
+    if (current !== "running") throw invalidState(this.configuration.id, current);
+  }
+  execArgs(options) {
+    const args = ["exec"];
+    if (options.input !== void 0) args.push("-i");
+    args.push("-w", containerPath(this.configuration.workdir, options.cwd ?? "."));
+    for (const [key, value] of Object.entries(options.env ?? {}))
+      args.push("-e", `${key}=${value}`);
+    args.push(this.configuration.containerName, options.command, ...options.args ?? []);
+    return args;
+  }
+  async execCommand(options, abortSignal) {
+    const result = await runDockerCli(this.execArgs(options), {
       dockerPath: this.dockerPath,
-      maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes
-    };
+      timeoutMs: options.timeoutMs ?? this.configuration.runtime.commandTimeoutMs,
+      maxOutputBytes: this.configuration.runtime.maxOutputBytes,
+      input: options.input,
+      signal: abortSignal
+    });
+    return toExecResult(result);
   }
-  async isPortListening(containerPort, timeoutMs) {
-    const result = await runDockerCli(
-      [
-        "exec",
-        this.containerName,
-        "sh",
-        "-c",
-        portProbeScript,
-        "anvia-port-probe",
-        String(containerPort)
-      ],
-      {
-        ...this.cliOptions(),
-        timeoutMs: Math.max(1, timeoutMs)
-      }
+  async mkdir(directory, abortSignal) {
+    if (directory === ".") return;
+    const result = await this.execCommand(
+      { command: "mkdir", args: ["-p", containerPath(this.configuration.workdir, directory)] },
+      abortSignal
     );
-    return result.exitCode === 0;
-  }
-  async execCommand(options) {
-    if (options.command.trim().length === 0) {
-      throw new SandboxDockerCommandError("Sandbox command cannot be empty.", {
-        stdout: "",
-        stderr: "",
-        exitCode: 1
-      });
+    if (result.status !== "exited" || result.exitCode !== 0) {
+      throw new DockerSandboxError(
+        "Unable to create sandbox directory.",
+        "docker_command_failed",
+        result
+      );
     }
-    const args = ["exec"];
-    if (options.input !== void 0) {
-      args.push("-i");
+  }
+  assertFileSize(size, filePath) {
+    if (size > this.configuration.runtime.maxFileBytes) {
+      throw new DockerSandboxError(
+        `Sandbox file exceeds maxFileBytes (${size} > ${this.configuration.runtime.maxFileBytes}): ${filePath}`,
+        "file_too_large"
+      );
     }
-    const cwd = containerPath(this.workdir, options.cwd ?? ".");
-    args.push("-w", cwd);
-    for (const [key, value] of Object.entries({ ...this.env, ...options.env })) {
-      args.push("-e", `${key}=${value}`);
+  }
+};
+async function applyInitialContent(runtime, options) {
+  for (const directory of options.directories ?? []) {
+    const marker = path2.posix.join(normalizeSandboxPath(directory), ".anvia-keep");
+    const abort = options.abortSignal === void 0 ? {} : { abortSignal: options.abortSignal };
+    await runtime.writeFile({ path: marker, data: new Uint8Array(), ...abort });
+    const removed = await runtime.exec({ command: "rm", args: [marker], ...abort });
+    if (removed.status !== "exited" || removed.exitCode !== 0) {
+      throw new DockerSandboxError(
+        `Unable to create initial sandbox directory: ${directory}`,
+        "docker_command_failed",
+        removed
+      );
     }
-    args.push(this.containerName, options.command, ...options.args ?? []);
-    const cliOptions = {
-      dockerPath: this.dockerPath,
-      timeoutMs: options.timeoutMs ?? this.limits.timeoutMs ?? defaultTimeoutMs,
-      maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes
-    };
-    if (options.input !== void 0) cliOptions.input = options.input;
-    if (options.signal !== void 0) cliOptions.signal = options.signal;
-    if (options.onStdout !== void 0) cliOptions.onStdout = options.onStdout;
-    if (options.onStderr !== void 0) cliOptions.onStderr = options.onStderr;
-    const result = await runDockerCli(args, cliOptions);
-    if (result.timedOut) {
-      return {
-        ...result,
-        exitCode: result.exitCode === 0 ? 124 : result.exitCode
+  }
+  for (const [filePath, content] of Object.entries(options.files ?? {})) {
+    if (typeof content === "string") {
+      let writeOptions = {
+        path: filePath,
+        text: content
+      };
+      if (options.abortSignal !== void 0) {
+        writeOptions = { ...writeOptions, abortSignal: options.abortSignal };
+      }
+      await runtime.writeTextFile(writeOptions);
+    } else {
+      let writeOptions = {
+        path: filePath,
+        data: content
       };
+      if (options.abortSignal !== void 0) {
+        writeOptions = { ...writeOptions, abortSignal: options.abortSignal };
+      }
+      await runtime.writeFile(writeOptions);
     }
-    return result;
   }
-  assertActive() {
-    if (this.destroyed) {
-      throw new SandboxSessionDestroyedError(`Sandbox session ${this.id} has been destroyed.`);
-    }
+}
+function createRunArgs(options) {
+  const runtimeLabels = {
+    [labels.schema]: schemaVersion,
+    [labels.id]: options.id,
+    [labels.workdir]: options.workdir,
+    [labels.workspaceType]: options.workspace.type,
+    [labels.workspaceVolume]: options.volumeName,
+    [labels.networkMode]: options.network.mode,
+    [labels.commandTimeoutMs]: `${options.runtime.commandTimeoutMs}`,
+    [labels.maxOutputBytes]: `${options.runtime.maxOutputBytes}`,
+    [labels.maxFileBytes]: `${options.runtime.maxFileBytes}`,
+    [labels.maxProcesses]: `${options.runtime.maxProcesses}`
+  };
+  const args = [
+    "run",
+    "-d",
+    "--name",
+    options.containerName,
+    "--mount",
+    `type=volume,src=${options.volumeName},dst=${options.workdir}`,
+    "-w",
+    options.workdir
+  ];
+  for (const [key, value] of Object.entries({ ...options.userLabels, ...runtimeLabels })) {
+    args.push("--label", `${key}=${value}`);
+  }
+  for (const [key, value] of Object.entries(options.env)) args.push("--env", `${key}=${value}`);
+  if (options.user !== void 0) args.push("--user", options.user);
+  if (options.network.mode === "none") {
+    args.push("--network", "none");
+  } else {
+    for (const port of options.network.ports ?? [])
+      args.push("--publish", `127.0.0.1::${port}/tcp`);
   }
-  event() {
-    return {
-      sessionId: this.id,
-      provider: this.provider,
-      workdir: this.workdir
-    };
+  if (options.resources?.memoryMb !== void 0)
+    args.push("--memory", `${options.resources.memoryMb}m`);
+  if (options.resources?.cpus !== void 0) args.push("--cpus", `${options.resources.cpus}`);
+  if (options.resources?.pidsLimit !== void 0) {
+    args.push("--pids-limit", `${options.resources.pidsLimit}`);
   }
-  async runOperation(operation) {
-    this.assertActive();
-    this.activeOperations += 1;
-    this.clearIdleTimer();
-    try {
-      return await operation();
-    } finally {
-      this.activeOperations -= 1;
-      this.scheduleIdleTimer();
-    }
+  if (options.resources?.sharedMemoryMb !== void 0) {
+    args.push("--shm-size", `${options.resources.sharedMemoryMb}m`);
   }
-  assertFileSize(size, filePath) {
-    if (this.limits.maxFileBytes !== void 0 && size > this.limits.maxFileBytes) {
-      throw new SandboxFileSizeError(
-        `Sandbox file exceeds maxFileBytes (${size} > ${this.limits.maxFileBytes}): ${filePath}`
+  if (options.security?.readonlyRootfs === true) args.push("--read-only");
+  if (options.security?.noNewPrivileges ?? true)
+    args.push("--security-opt", "no-new-privileges:true");
+  if (options.security?.seccompProfile !== void 0) {
+    args.push("--security-opt", `seccomp=${options.security.seccompProfile.path}`);
+  }
+  for (const capability of options.security?.dropCapabilities ?? ["ALL"]) {
+    args.push("--cap-drop", capability);
+  }
+  for (const capability of options.security?.addCapabilities ?? []) {
+    args.push("--cap-add", capability);
+  }
+  args.push(
+    options.image,
+    "sh",
+    "-c",
+    "trap 'exit 0' TERM INT; while :; do sleep 3600 & wait $!; done"
+  );
+  return args;
+}
+function validateCreateOptions(options) {
+  if (options === null || typeof options !== "object")
+    throw new TypeError("options must be an object.");
+  assertNonEmptyString(options.image, "image");
+  if (options.id !== void 0) assertSandboxId(options.id);
+  const workdir = options.workdir ?? defaultWorkdir;
+  if (!path2.posix.isAbsolute(workdir) || workdir.includes("\0")) {
+    throw new TypeError("workdir must be an absolute POSIX path.");
+  }
+  if (!isRecord(options.workspace)) throw new TypeError("workspace must be an object.");
+  if (options.workspace.type === "docker-volume") assertDockerVolumeName(options.workspace.name);
+  if (options.workspace.type !== "ephemeral" && options.workspace.type !== "docker-volume") {
+    throw new TypeError("workspace must use type ephemeral or docker-volume.");
+  }
+  if (options.workspace.type === "ephemeral" && "name" in options.workspace) {
+    throw new TypeError("An ephemeral workspace cannot specify a Docker volume name.");
+  }
+  if (!isRecord(options.network)) throw new TypeError("network must be an object.");
+  if (options.network.mode !== "none" && options.network.mode !== "bridge") {
+    throw new TypeError("network must use mode none or bridge.");
+  }
+  if (options.network.mode === "none" && "ports" in options.network) {
+    throw new TypeError("Network mode none cannot publish ports.");
+  }
+  if (options.network.mode === "bridge") {
+    if (options.network.ports !== void 0 && !Array.isArray(options.network.ports)) {
+      throw new TypeError("network.ports must be an array.");
+    }
+    validatePorts(options.network.ports ?? []);
+  }
+  validateRuntimeLimits(options.runtime);
+  validateResources(options.resources);
+  validateSecurity(options.security);
+  copyStringRecord(options.env, "env");
+  const userLabels = copyStringRecord(options.labels, "labels");
+  for (const key of Object.keys(userLabels)) {
+    if (key.startsWith(labelPrefix)) throw new TypeError(`Docker label is reserved: ${key}`);
+  }
+  if (options.user !== void 0) assertNonEmptyString(options.user, "user");
+  if (options.directories !== void 0 && !Array.isArray(options.directories)) {
+    throw new TypeError("directories must be an array.");
+  }
+  for (const directory of options.directories ?? []) {
+    if (typeof directory !== "string") throw new TypeError("directories must contain strings.");
+    normalizeSandboxPath(directory);
+  }
+  if (options.files !== void 0 && !isRecord(options.files)) {
+    throw new TypeError("files must be an object.");
+  }
+  for (const [filePath, content] of Object.entries(options.files ?? {})) {
+    normalizeSandboxPath(filePath);
+    if (typeof content !== "string" && !(content instanceof Uint8Array)) {
+      throw new TypeError(`Initial file must be a string or Uint8Array: ${filePath}`);
+    }
+    const byteLength = typeof content === "string" ? new TextEncoder().encode(content).byteLength : content.byteLength;
+    const maxFileBytes = options.runtime?.maxFileBytes ?? defaultMaxFileBytes;
+    if (byteLength > maxFileBytes) {
+      throw new DockerSandboxError(
+        `Initial file exceeds maxFileBytes (${byteLength} > ${maxFileBytes}): ${filePath}`,
+        "file_too_large"
       );
     }
   }
-  startLifecycleTimers() {
-    if (!this.lifecycle.autoDestroy) {
-      return;
-    }
-    if (this.lifecycle.ttlMs !== void 0) {
-      this.ttlTimer = setTimeout(() => {
-        void this.destroy().catch(() => void 0);
-      }, this.lifecycle.ttlMs);
-      this.ttlTimer.unref?.();
-    }
-    this.scheduleIdleTimer();
+}
+function validateRuntimeLimits(runtime) {
+  if (runtime !== void 0 && !isRecord(runtime)) {
+    throw new TypeError("runtime must be an object.");
+  }
+  if (runtime?.commandTimeoutMs !== void 0)
+    assertPositiveSafeInteger(runtime.commandTimeoutMs, "commandTimeoutMs");
+  if (runtime?.maxOutputBytes !== void 0)
+    assertNonNegativeSafeInteger(runtime.maxOutputBytes, "maxOutputBytes");
+  if (runtime?.maxFileBytes !== void 0)
+    assertNonNegativeSafeInteger(runtime.maxFileBytes, "maxFileBytes");
+  if (runtime?.maxProcesses !== void 0)
+    assertNonNegativeSafeInteger(runtime.maxProcesses, "maxProcesses");
+}
+function validateResources(resources) {
+  if (resources !== void 0 && !isRecord(resources)) {
+    throw new TypeError("resources must be an object.");
+  }
+  if (resources?.memoryMb !== void 0) assertPositiveSafeInteger(resources.memoryMb, "memoryMb");
+  if (resources?.pidsLimit !== void 0)
+    assertPositiveSafeInteger(resources.pidsLimit, "pidsLimit");
+  if (resources?.sharedMemoryMb !== void 0)
+    assertPositiveSafeInteger(resources.sharedMemoryMb, "sharedMemoryMb");
+  if (resources?.cpus !== void 0 && (!Number.isFinite(resources.cpus) || resources.cpus <= 0)) {
+    throw new RangeError("cpus must be a positive finite number.");
   }
-  scheduleIdleTimer() {
-    if (!this.lifecycle.autoDestroy || this.lifecycle.idleTimeoutMs === void 0) {
-      return;
-    }
-    if (this.destroyed || this.activeOperations > 0) {
-      return;
-    }
-    this.clearIdleTimer();
-    this.idleTimer = setTimeout(() => {
-      void this.destroy().catch(() => void 0);
-    }, this.lifecycle.idleTimeoutMs);
-    this.idleTimer.unref?.();
+}
+function validateSecurity(security) {
+  if (security !== void 0 && !isRecord(security)) {
+    throw new TypeError("security must be an object.");
   }
-  clearLifecycleTimers() {
-    if (this.ttlTimer !== void 0) {
-      clearTimeout(this.ttlTimer);
-      this.ttlTimer = void 0;
-    }
-    this.clearIdleTimer();
+  if (security?.dropCapabilities !== void 0 && !Array.isArray(security.dropCapabilities)) {
+    throw new TypeError("dropCapabilities must be an array.");
+  }
+  if (security?.addCapabilities !== void 0 && !Array.isArray(security.addCapabilities)) {
+    throw new TypeError("addCapabilities must be an array.");
   }
-  clearIdleTimer() {
-    if (this.idleTimer !== void 0) {
-      clearTimeout(this.idleTimer);
-      this.idleTimer = void 0;
+  if (security?.readonlyRootfs !== void 0 && typeof security.readonlyRootfs !== "boolean") {
+    throw new TypeError("readonlyRootfs must be a boolean.");
+  }
+  if (security?.noNewPrivileges !== void 0 && typeof security.noNewPrivileges !== "boolean") {
+    throw new TypeError("noNewPrivileges must be a boolean.");
+  }
+  if (security?.seccompProfile !== void 0) {
+    if (!isRecord(security.seccompProfile) || security.seccompProfile.type !== "path") {
+      throw new TypeError('seccompProfile must be a { type: "path", path } object.');
+    }
+    assertNonEmptyString(security.seccompProfile.path, "seccompProfile.path");
+    if (!path2.isAbsolute(security.seccompProfile.path) || security.seccompProfile.path.includes("\0")) {
+      throw new TypeError("seccompProfile.path must be an absolute host path.");
     }
   }
-};
-function getWorkspaceId(workspace, sessionId) {
-  if (workspace.mode === "persistent") {
-    return sanitizeResourceId(workspace.id);
+  const seen = /* @__PURE__ */ new Set();
+  for (const capability of security?.dropCapabilities ?? []) {
+    assertNonEmptyString(capability, "dropCapabilities value");
+    if (seen.has(capability))
+      throw new TypeError(`dropCapabilities contains a duplicate: ${capability}`);
+    seen.add(capability);
+  }
+  seen.clear();
+  for (const capability of security?.addCapabilities ?? []) {
+    assertNonEmptyString(capability, "addCapabilities value");
+    if (seen.has(capability))
+      throw new TypeError(`addCapabilities contains a duplicate: ${capability}`);
+    seen.add(capability);
   }
-  return sessionId;
 }
-function shouldDestroyWorkspace(workspace) {
-  if (workspace.mode === "persistent") {
-    return workspace.destroyOnSessionDestroy ?? false;
+function validateExecOptions(options) {
+  assertOptionsObject(options);
+  assertNonEmptyString(options.command, "command");
+  if (options.args !== void 0 && (!Array.isArray(options.args) || !options.args.every((value) => typeof value === "string"))) {
+    throw new TypeError("args must contain only strings.");
+  }
+  if (options.cwd !== void 0) normalizeSandboxPath(options.cwd, { allowRoot: true });
+  copyStringRecord(options.env, "env");
+  if (options.timeoutMs !== void 0) assertPositiveSafeInteger(options.timeoutMs, "timeoutMs");
+  if (options.input !== void 0 && typeof options.input !== "string" && !(options.input instanceof Uint8Array)) {
+    throw new TypeError("input must be a string or Uint8Array.");
   }
-  return true;
 }
-function sanitizeResourceId(id) {
-  const sanitized = id.toLowerCase().replaceAll(/[^a-z0-9_.-]/g, "-").replaceAll(/^-+|-+$/g, "");
-  return sanitized.length > 0 ? sanitized : randomUUID2();
+function validateProcessStartOptions(options) {
+  assertOptionsObject(options);
+  assertNonEmptyString(options.command, "command");
+  if (options.args !== void 0 && (!Array.isArray(options.args) || !options.args.every((value) => typeof value === "string"))) {
+    throw new TypeError("args must contain only strings.");
+  }
+  if (options.cwd !== void 0) normalizeSandboxPath(options.cwd, { allowRoot: true });
+  copyStringRecord(options.env, "env");
 }
-function byteLength(data) {
-  return typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+function assertReadOptions(options) {
+  assertOptionsObject(options);
+  normalizeSandboxPath(options.path);
 }
-function mapFindType(type) {
-  if (type === "f") {
-    return "file";
+function assertOptionsObject(value) {
+  if (!isRecord(value)) throw new TypeError("options must be an object.");
+}
+function resolveRuntimeLimits(runtime) {
+  return {
+    commandTimeoutMs: runtime?.commandTimeoutMs ?? defaultCommandTimeoutMs,
+    maxOutputBytes: runtime?.maxOutputBytes ?? defaultMaxOutputBytes,
+    maxFileBytes: runtime?.maxFileBytes ?? defaultMaxFileBytes,
+    maxProcesses: runtime?.maxProcesses ?? defaultMaxProcesses
+  };
+}
+function snapshotCreateOptions(options) {
+  const files = {};
+  for (const [filePath, content] of Object.entries(options.files ?? {})) {
+    files[filePath] = typeof content === "string" ? content : content.slice();
+  }
+  const workspace = copyWorkspace(options.workspace);
+  const network = copyNetwork(options.network);
+  let snapshot = {
+    image: options.image,
+    workspace,
+    network
+  };
+  if (options.id !== void 0) snapshot = { ...snapshot, id: options.id };
+  if (options.workdir !== void 0) snapshot = { ...snapshot, workdir: options.workdir };
+  if (options.files !== void 0) snapshot = { ...snapshot, files: Object.freeze(files) };
+  if (options.directories !== void 0) {
+    snapshot = { ...snapshot, directories: Object.freeze([...options.directories]) };
   }
-  if (type === "d") {
-    return "directory";
+  if (options.env !== void 0) {
+    snapshot = { ...snapshot, env: Object.freeze({ ...options.env }) };
   }
-  if (type === "l") {
-    return "symlink";
+  if (options.user !== void 0) snapshot = { ...snapshot, user: options.user };
+  if (options.labels !== void 0) {
+    snapshot = { ...snapshot, labels: Object.freeze({ ...options.labels }) };
   }
-  return "other";
-}
-function validatePublishedPorts(ports) {
-  const unique = /* @__PURE__ */ new Set();
-  for (const port of ports) {
-    if (!isValidPort(port)) {
-      throw new SandboxPortError(`Sandbox port must be an integer from 1 to 65535: ${port}`);
+  if (options.resources !== void 0) {
+    snapshot = { ...snapshot, resources: Object.freeze({ ...options.resources }) };
+  }
+  if (options.runtime !== void 0) {
+    snapshot = { ...snapshot, runtime: Object.freeze({ ...options.runtime }) };
+  }
+  if (options.security !== void 0) {
+    let security = {
+      ...options.security
+    };
+    if (options.security.seccompProfile !== void 0) {
+      security = {
+        ...security,
+        seccompProfile: Object.freeze({ ...options.security.seccompProfile })
+      };
+    }
+    if (options.security.dropCapabilities !== void 0) {
+      security = {
+        ...security,
+        dropCapabilities: Object.freeze([...options.security.dropCapabilities])
+      };
     }
-    if (unique.has(port)) {
-      throw new SandboxPortError(`Sandbox port is duplicated: ${port}`);
+    if (options.security.addCapabilities !== void 0) {
+      security = {
+        ...security,
+        addCapabilities: Object.freeze([...options.security.addCapabilities])
+      };
     }
-    unique.add(port);
+    snapshot = { ...snapshot, security: Object.freeze(security) };
   }
-  return [...unique];
+  if (options.abortSignal !== void 0) {
+    snapshot = { ...snapshot, abortSignal: options.abortSignal };
+  }
+  return Object.freeze(snapshot);
 }
-function isValidPort(port) {
-  return Number.isInteger(port) && port >= 1 && port <= 65535;
+function configurationFromInspection(id, containerName, inspection) {
+  const containerLabels = inspection.Config.Labels ?? {};
+  if (containerLabels[labels.schema] !== schemaVersion || containerLabels[labels.id] !== id) {
+    throw new DockerSandboxError(
+      `Container is not an Anvia sandbox: ${containerName}`,
+      "sandbox_not_found"
+    );
+  }
+  const workdir = requiredLabel(containerLabels, labels.workdir);
+  const workspaceType = requiredLabel(containerLabels, labels.workspaceType);
+  const volumeName = requiredLabel(containerLabels, labels.workspaceVolume);
+  const networkMode = requiredLabel(containerLabels, labels.networkMode);
+  if (networkMode !== "none" && networkMode !== "bridge") invalidInspection("network mode");
+  const workspace = workspaceType === "ephemeral" ? { type: "ephemeral" } : workspaceType === "docker-volume" ? { type: "docker-volume", name: volumeName } : invalidInspection("workspace type");
+  const runtime = {
+    commandTimeoutMs: parseLabelInteger(containerLabels, labels.commandTimeoutMs, true),
+    maxOutputBytes: parseLabelInteger(containerLabels, labels.maxOutputBytes, false),
+    maxFileBytes: parseLabelInteger(containerLabels, labels.maxFileBytes, false),
+    maxProcesses: parseLabelInteger(containerLabels, labels.maxProcesses, false)
+  };
+  return {
+    id,
+    containerName,
+    workdir,
+    workspace,
+    volumeName,
+    ownsVolume: workspace.type === "ephemeral",
+    env: {},
+    runtime,
+    publishedPorts: []
+  };
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+async function inspectContainer(dockerPath, containerName, abortSignal, notFoundAsSandboxError) {
+  const result = await runDockerCli(["container", "inspect", containerName], {
+    dockerPath,
+    signal: abortSignal
+  });
+  if (result.exitCode !== 0) {
+    const message = safeDecode(result.stderr);
+    if (notFoundAsSandboxError && message.toLowerCase().includes("no such")) {
+      throw new DockerSandboxError(`Sandbox does not exist: ${containerName}`, "sandbox_not_found");
+    }
+    throw new DockerSandboxError(
+      "Unable to inspect Docker sandbox.",
+      "docker_command_failed",
+      result
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(decodeUtf8(result.stdout));
+  } catch (error) {
+    throw new DockerSandboxError(
+      "Docker returned invalid container metadata.",
+      "docker_command_failed",
+      void 0,
+      { cause: error }
+    );
+  }
+  if (!Array.isArray(value) || value.length !== 1 || !isInspection(value[0])) {
+    throw new DockerSandboxError(
+      "Docker returned invalid container metadata.",
+      "docker_command_failed"
+    );
+  }
+  return value[0];
 }
-function assertWaitOptions(timeoutMs, intervalMs) {
-  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
-    throw new SandboxPortError("Port wait timeoutMs must be a positive integer.");
+function isInspection(value) {
+  return isRecord(value) && isRecord(value.Config) && isRecord(value.State);
+}
+async function inspectPublishedPorts(options) {
+  if (options.ports.length === 0) return [];
+  const inspection = await inspectContainer(
+    options.dockerPath,
+    options.containerName,
+    options.abortSignal,
+    false
+  );
+  const mappings = inspection.NetworkSettings?.Ports ?? {};
+  return options.ports.map((containerPort) => {
+    const entries = mappings[`${containerPort}/tcp`];
+    const entry = entries?.find((candidate) => candidate.HostIp === "127.0.0.1");
+    const hostPort = Number(entry?.HostPort);
+    if (!isPort(hostPort)) {
+      throw new DockerSandboxError(`Docker did not publish port: ${containerPort}`, "port");
+    }
+    return { containerPort, host: "127.0.0.1", hostPort, protocol: "tcp" };
+  });
+}
+function configuredContainerPorts(inspection) {
+  return Object.keys(inspection.HostConfig?.PortBindings ?? {}).flatMap((key) => {
+    const match = /^(\d+)\/tcp$/.exec(key);
+    if (match?.[1] === void 0) return [];
+    const value = Number(match[1]);
+    return isPort(value) ? [value] : [];
+  });
+}
+async function assertCopiedRegularFile(temporaryDirectory, target, sandboxPath) {
+  const metadata = await lstat(target);
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    throw new DockerSandboxError(
+      `Sandbox path is not a regular file: ${sandboxPath}`,
+      "invalid_path"
+    );
   }
-  if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
-    throw new SandboxPortError("Port wait intervalMs must be a positive integer.");
+  const resolvedTarget = await realpath(target);
+  const relativeTarget = path2.relative(temporaryDirectory, resolvedTarget);
+  if (relativeTarget === "" || relativeTarget === ".." || relativeTarget.startsWith(`..${path2.sep}`) || path2.isAbsolute(relativeTarget)) {
+    throw new DockerSandboxError(
+      `Sandbox file escaped its temporary read boundary: ${sandboxPath}`,
+      "invalid_path"
+    );
   }
 }
-function assertTextFileReadOptions(startLine, lineCount, maxBytes) {
-  if (!Number.isInteger(startLine) || startLine <= 0) {
-    throw new RangeError("Text file startLine must be a positive integer.");
+async function removeContainer(dockerPath, containerName) {
+  const result = await runDockerCli(["rm", "-f", containerName], { dockerPath });
+  if (result.exitCode === 0 || safeDecode(result.stderr).toLowerCase().includes("no such")) return;
+  throw new DockerSandboxError("Unable to remove Docker sandbox.", "docker_command_failed", result);
+}
+async function removeVolume(dockerPath, volumeName) {
+  const result = await runDockerCli(["volume", "rm", volumeName], { dockerPath });
+  if (result.exitCode === 0 || safeDecode(result.stderr).toLowerCase().includes("no such")) return;
+  throw new DockerSandboxError(
+    "Unable to remove Docker sandbox volume.",
+    "docker_command_failed",
+    result
+  );
+}
+function parseFindEntry(line, workdir) {
+  const [absolutePath, rawType, rawSize] = line.split("	");
+  if (absolutePath === void 0 || rawType === void 0 || rawSize === void 0) {
+    throw new DockerSandboxError("Docker returned invalid file metadata.", "docker_command_failed");
+  }
+  const relativePath = path2.posix.relative(workdir, absolutePath);
+  const size = Number(rawSize);
+  const type = mapFindType(rawType);
+  let entry = {
+    path: normalizeSandboxPath(relativePath),
+    type
+  };
+  if (type === "file" && Number.isSafeInteger(size) && size >= 0) {
+    entry = { ...entry, size };
   }
-  if (!Number.isInteger(lineCount) || lineCount <= 0) {
-    throw new RangeError("Text file lineCount must be a positive integer.");
+  return entry;
+}
+function mapFindType(value) {
+  if (value === "f") return "file";
+  if (value === "d") return "directory";
+  if (value === "l") return "symlink";
+  return "other";
+}
+function toExecResult(result) {
+  const common = {
+    stdout: result.stdout.slice(),
+    stderr: result.stderr.slice(),
+    durationMs: result.durationMs,
+    stdoutTruncated: result.stdoutTruncated,
+    stderrTruncated: result.stderrTruncated
+  };
+  return result.timedOut ? { ...common, status: "timed_out" } : { ...common, status: "exited", exitCode: result.exitCode };
+}
+function copyWorkspace(workspace) {
+  return workspace.type === "ephemeral" ? Object.freeze({ type: "ephemeral" }) : Object.freeze({ type: "docker-volume", name: workspace.name });
+}
+function copyNetwork(network) {
+  return network.mode === "none" ? Object.freeze({ mode: "none" }) : Object.freeze({ mode: "bridge", ports: Object.freeze([...network.ports ?? []]) });
+}
+function copyStringRecord(value, name) {
+  if (value === void 0) return {};
+  if (!isRecord(value)) throw new TypeError(`${name} must be an object.`);
+  const copy = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== "string") throw new TypeError(`${name}.${key} must be a string.`);
+    if (name === "env" && !envKeyPattern.test(key))
+      throw new TypeError(`Invalid environment variable name: ${key}`);
+    copy[key] = item;
   }
-  if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
-    throw new RangeError("Text file maxBytes must be a positive integer.");
+  return copy;
+}
+function requiredLabel(containerLabels, name) {
+  const value = containerLabels[name];
+  if (value === void 0 || value.length === 0) invalidInspection(name);
+  return value;
+}
+function parseLabelInteger(containerLabels, name, positive) {
+  const value = Number(requiredLabel(containerLabels, name));
+  if (!Number.isSafeInteger(value) || (positive ? value <= 0 : value < 0)) invalidInspection(name);
+  return value;
+}
+function invalidInspection(field) {
+  throw new DockerSandboxError(`Sandbox metadata is invalid: ${field}`, "invalid_state");
+}
+function validatePorts(ports) {
+  if (!Array.isArray(ports)) throw new TypeError("ports must be an array.");
+  const seen = /* @__PURE__ */ new Set();
+  for (const port of ports) {
+    assertPort(port);
+    if (seen.has(port)) throw new DockerSandboxError(`Sandbox port is duplicated: ${port}`, "port");
+    seen.add(port);
   }
 }
-async function waitWithSignal(timeoutMs, signal) {
-  if (signal?.aborted === true) throw abortReason(signal);
+function assertPort(port) {
+  if (!isPort(port))
+    throw new DockerSandboxError(
+      `Sandbox port must be an integer from 1 to 65535: ${port}`,
+      "port"
+    );
+}
+function isPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function assertSandboxId(id) {
+  if (typeof id !== "string" || !idPattern.test(id)) {
+    throw new TypeError(
+      "Sandbox id must be 1-63 lowercase letters, numbers, dots, underscores, or hyphens."
+    );
+  }
+}
+function assertDockerVolumeName(name) {
+  assertNonEmptyString(name, "workspace.name");
+  if (name.includes(",") || name.includes("\0"))
+    throw new TypeError("workspace.name is not a valid Docker volume name.");
+}
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.length === 0)
+    throw new TypeError(`${name} must be a non-empty string.`);
+}
+function assertPositiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0)
+    throw new RangeError(`${name} must be a positive safe integer.`);
+}
+function assertNonNegativeSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError(`${name} must be a non-negative safe integer.`);
+}
+function invalidState(id, state) {
+  return new DockerSandboxError(`Sandbox ${id} is not running (${state}).`, "invalid_state", {
+    state
+  });
+}
+function containerNameFor(id) {
+  return `anvia-sandbox-${id}`;
+}
+function combineSignals(first, second) {
+  return first === void 0 ? second : AbortSignal.any([first, second]);
+}
+async function waitWithSignal(timeoutMs, abortSignal) {
+  abortSignal.throwIfAborted();
   await new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
-      signal?.removeEventListener("abort", abort);
+      abortSignal.removeEventListener("abort", abort);
       resolve();
     }, timeoutMs);
     const abort = () => {
       clearTimeout(timeout);
-      reject(abortReason(signal));
+      reject(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
     };
-    signal?.addEventListener("abort", abort, { once: true });
+    abortSignal.addEventListener("abort", abort, { once: true });
   });
 }
-function abortReason(signal) {
-  return signal?.reason ?? new SandboxPortError("Waiting for sandbox port was aborted.");
+function safeDecode(bytes) {
+  try {
+    return decodeUtf8(bytes);
+  } catch {
+    return "";
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 // src/tools.ts
 import { createTool } from "@anvia/core/tool";
 import { z } from "zod";
+var allToolNames = [
+  "exec_command",
+  "read_file",
+  "write_file",
+  "list_files",
+  "list_ports",
+  "start_process",
+  "list_processes",
+  "read_process_logs",
+  "stop_process",
+  "wait_for_port"
+];
 var execCommandInput = z.object({
-  command: z.string().min(1).describe("Executable to run inside the sandbox workspace."),
-  args: z.array(z.string()).optional().describe("Command arguments."),
-  cwd: z.string().optional().describe("Relative working directory inside the sandbox."),
-  env: z.record(z.string(), z.string()).optional().describe("Environment variables for this command."),
-  timeoutMs: z.number().int().positive().max(3e5).optional().describe("Optional command timeout in milliseconds."),
-  input: z.string().optional().describe("Optional stdin text to pass to the command.")
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  cwd: z.string().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  timeoutMs: z.number().int().positive().max(3e5).optional(),
+  input: z.string().optional()
 });
+var execResultOutput = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("exited"),
+    exitCode: z.number().int(),
+    stdout: z.string(),
+    stderr: z.string(),
+    durationMs: z.number().nonnegative(),
+    stdoutTruncated: z.boolean(),
+    stderrTruncated: z.boolean()
+  }),
+  z.object({
+    status: z.literal("timed_out"),
+    stdout: z.string(),
+    stderr: z.string(),
+    durationMs: z.number().nonnegative(),
+    stdoutTruncated: z.boolean(),
+    stderrTruncated: z.boolean()
+  })
+]);
 var readFileInput = z.object({
-  path: z.string().min(1).describe("Relative file path inside the sandbox."),
-  startLine: z.number().int().positive().optional().describe("One-based first line to read. Defaults to 1."),
-  lineCount: z.number().int().positive().max(1e4).optional().describe("Maximum lines to return. Defaults to 500.")
+  path: z.string().min(1),
+  startLine: z.number().int().positive().optional(),
+  lineCount: z.number().int().positive().max(1e4).optional()
+});
+var readFileOutput = z.object({
+  content: z.string(),
+  startLine: z.number().int().positive(),
+  endLine: z.number().int().positive().nullable(),
+  nextStartLine: z.number().int().positive().nullable(),
+  truncated: z.boolean(),
+  truncatedBy: z.enum(["lines", "bytes"]).nullable()
 });
 var writeFileInput = z.object({
-  path: z.string().min(1).describe("Relative file path inside the sandbox."),
-  content: z.string().describe("Complete text content to write.")
+  path: z.string().min(1),
+  content: z.string()
+});
+var writeFileOutput = z.object({
+  path: z.string(),
+  bytesWritten: z.number().int().nonnegative()
+});
+var listFilesInput = z.object({ path: z.string().optional() });
+var fileEntryOutput = z.object({
+  path: z.string(),
+  type: z.enum(["file", "directory", "symlink", "other"]),
+  size: z.number().int().nonnegative().optional()
 });
-var listFilesInput = z.object({
-  path: z.string().optional().describe("Relative directory path inside the sandbox. Defaults to root.")
+var listFilesOutput = z.object({
+  path: z.string(),
+  entries: z.array(fileEntryOutput)
 });
 var emptyInput = z.object({});
+var publishedPortOutput = z.object({
+  containerPort: z.number().int(),
+  host: z.literal("127.0.0.1"),
+  hostPort: z.number().int(),
+  protocol: z.literal("tcp")
+});
+var listPortsOutput = z.object({ ports: z.array(publishedPortOutput) });
 var startProcessInput = z.object({
-  command: z.string().min(1).describe("Executable to run as a managed sandbox process."),
-  args: z.array(z.string()).optional().describe("Command arguments."),
-  cwd: z.string().optional().describe("Relative working directory inside the sandbox."),
-  env: z.record(z.string(), z.string()).optional().describe("Environment variables for this process.")
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  cwd: z.string().optional(),
+  env: z.record(z.string(), z.string()).optional()
 });
-var processIdInput = z.object({
-  processId: z.string().min(1).describe("Managed process identifier.")
+var processInfoOutput = z.object({
+  id: z.string(),
+  command: z.string(),
+  args: z.array(z.string()),
+  cwd: z.string().optional(),
+  status: z.enum(["running", "exited", "stopped"]),
+  exitCode: z.number().int().optional(),
+  startedAt: z.string(),
+  endedAt: z.string().optional()
 });
+var listProcessesOutput = z.object({ processes: z.array(processInfoOutput) });
+var processIdInput = z.object({ processId: z.string().min(1) });
 var readProcessLogsInput = processIdInput.extend({
-  tailBytes: z.number().int().nonnegative().max(1024 * 1024).optional().describe("Maximum trailing bytes to return from each output stream.")
+  tailBytes: z.number().int().nonnegative().max(1024 * 1024).optional()
+});
+var processLogsOutput = z.object({
+  processId: z.string(),
+  stdout: z.string(),
+  stderr: z.string(),
+  stdoutTruncated: z.boolean(),
+  stderrTruncated: z.boolean()
 });
 var waitForPortInput = z.object({
-  containerPort: z.number().int().min(1).max(65535).describe("Pre-authorized TCP port inside the sandbox container."),
-  timeoutMs: z.number().int().positive().max(3e5).optional().describe("Maximum time to wait for the port to accept connections.")
+  containerPort: z.number().int().min(1).max(65535),
+  timeoutMs: z.number().int().positive().max(3e5).optional()
 });
-var textOutput = z.string();
-var maxToolLogBytes = 1024 * 1024;
+var waitForPortOutput = z.object({ port: publishedPortOutput });
 var defaultReadFileLineCount = 500;
 var defaultReadFileMaxLineCount = 2e3;
 var defaultReadFileMaxBytes = 64 * 1024;
-var maxToolReadFileBytes = 1024 * 1024;
 var maxToolReadFileLines = 1e4;
-var readFileOutput = z.object({
-  content: z.string(),
-  startLine: z.number().int().positive(),
-  endLine: z.number().int().positive().nullable(),
-  nextStartLine: z.number().int().positive().nullable(),
-  truncated: z.boolean(),
-  truncatedBy: z.enum(["lines", "bytes"]).nullable()
-});
-var sandboxToolMetadataKey = /* @__PURE__ */ Symbol.for("anvia.sandbox.tool.metadata");
-function createSandboxTools(session, options = {}) {
-  const include = new Set(
-    options.allow ?? options.include ?? ["exec_command", "read_file", "write_file", "list_files"]
-  );
+var maxToolBytes = 1024 * 1024;
+var maxToolTimeoutMs = 3e5;
+function createDockerSandboxTools(options) {
+  validateFactoryOptions(options);
+  options = snapshotFactoryOptions(options);
+  const selected = new Set(options.tools);
   const tools = [];
-  if (include.has("exec_command")) {
-    tools.push(createExecCommandTool(session, options));
-  }
-  if (include.has("read_file")) {
-    tools.push(createReadFileTool(session, options));
-  }
-  if (include.has("write_file")) {
-    tools.push(createWriteFileTool(session, options));
-  }
-  if (include.has("list_files")) {
-    tools.push(createListFilesTool(session));
-  }
-  const portToolsRequested = include.has("list_ports") || include.has("wait_for_port");
-  const portSession = portToolsRequested ? requirePortSession(session) : void 0;
-  if (include.has("list_ports") && portSession !== void 0) {
-    tools.push(createListPortsTool(portSession));
-  }
-  const processToolsRequested = include.has("start_process") || include.has("list_processes") || include.has("read_process_logs") || include.has("stop_process");
-  if (include.has("wait_for_port") || processToolsRequested) assertProcessToolPolicy(options);
-  const processSession = processToolsRequested ? requireProcessSession(session) : void 0;
-  if (include.has("start_process") && processSession !== void 0) {
-    tools.push(createStartProcessTool(processSession, options));
-  }
-  if (include.has("list_processes") && processSession !== void 0) {
-    tools.push(createListProcessesTool(processSession));
-  }
-  if (include.has("read_process_logs") && processSession !== void 0) {
-    tools.push(createReadProcessLogsTool(processSession, options));
-  }
-  if (include.has("stop_process") && processSession !== void 0) {
-    tools.push(createStopProcessTool(processSession, options));
-  }
-  if (include.has("wait_for_port") && portSession !== void 0) {
-    tools.push(createWaitForPortTool(portSession, options));
-  }
-  for (const tool of tools) {
-    Object.defineProperty(tool, sandboxToolMetadataKey, {
-      value: { session },
-      enumerable: false
-    });
-  }
-  return tools;
+  for (const name of options.tools) {
+    if (name === "exec_command") tools.push(createExecCommandTool(options));
+    else if (name === "read_file") tools.push(createReadFileTool(options));
+    else if (name === "write_file") tools.push(createWriteFileTool(options));
+    else if (name === "list_files") tools.push(createListFilesTool(options.sandbox));
+    else if (name === "list_ports") tools.push(createListPortsTool(options.sandbox));
+    else if (name === "start_process") tools.push(createStartProcessTool(options));
+    else if (name === "list_processes") tools.push(createListProcessesTool(options.sandbox));
+    else if (name === "read_process_logs") tools.push(createReadProcessLogsTool(options));
+    else if (name === "stop_process") tools.push(createStopProcessTool(options));
+    else if (name === "wait_for_port") tools.push(createWaitForPortTool(options));
+  }
+  if (tools.length !== selected.size) {
+    throw toolPolicyError("Sandbox tool selection contains an unsupported tool name.");
+  }
+  return Object.freeze(tools);
 }
-function createExecCommandTool(session, options) {
-  const policy = options.exec ?? {};
+function createExecCommandTool(options) {
   return createTool({
     name: "exec_command",
-    description: "Run a command inside the sandbox workspace. Use structured args instead of shell quoting.",
-    input: execCommandInput,
-    output: textOutput,
-    execute: async ({ command, args, cwd, env, timeoutMs, input }) => {
-      assertCommandAllowed(command, options);
-      const execOptions = {
+    description: "Run one executable inside the sandbox with structured arguments.",
+    inputSchema: execCommandInput,
+    outputSchema: execResultOutput,
+    execute: async ({ command, args, cwd, env, timeoutMs, input }, context) => {
+      assertCommandAllowed(command, options.exec?.commands);
+      const effectiveTimeoutMs = timeoutMs ?? options.exec?.defaultTimeoutMs;
+      assertTimeoutAllowed(effectiveTimeoutMs, options.exec?.maxTimeoutMs);
+      let execOptions = {
         command
       };
-      if (args !== void 0) {
-        execOptions.args = args;
-      }
-      if (cwd !== void 0) {
-        execOptions.cwd = cwd;
-      }
-      if (env !== void 0) {
-        execOptions.env = env;
-      }
-      const effectiveTimeoutMs = timeoutMs ?? policy.defaultTimeoutMs ?? options.execTimeoutMs;
+      if (args !== void 0) execOptions = { ...execOptions, args };
+      if (cwd !== void 0) execOptions = { ...execOptions, cwd };
+      if (env !== void 0) execOptions = { ...execOptions, env };
       if (effectiveTimeoutMs !== void 0) {
-        assertTimeoutAllowed(effectiveTimeoutMs, options);
-        execOptions.timeoutMs = effectiveTimeoutMs;
+        execOptions = { ...execOptions, timeoutMs: effectiveTimeoutMs };
       }
-      if (input !== void 0) {
-        execOptions.input = input;
+      if (input !== void 0) execOptions = { ...execOptions, input };
+      if (context.abortSignal !== void 0) {
+        execOptions = { ...execOptions, abortSignal: context.abortSignal };
       }
-      const result = await session.exec(execOptions);
-      return formatExecResult(result);
+      return serializeExecResult(await options.sandbox.exec(execOptions));
     }
   });
 }
-function createReadFileTool(session, options) {
+function createReadFileTool(options) {
+  const limits = resolveReadFileLimits(options);
   return createTool({
     name: "read_file",
-    description: "Read a bounded page of a text file from the sandbox workspace. Continue with nextStartLine when provided.",
-    input: readFileInput,
-    output: readFileOutput,
-    execute: async ({ path: path3, startLine, lineCount }) => {
-      const limits = resolveReadFileLimits(options);
-      const effectiveStartLine = startLine ?? 1;
+    description: "Read a bounded page of a UTF-8 text file from the sandbox workspace.",
+    inputSchema: readFileInput,
+    outputSchema: readFileOutput,
+    execute: async ({ path: path3, startLine, lineCount }, context) => {
       const effectiveLineCount = lineCount ?? limits.defaultLineCount;
       if (effectiveLineCount > limits.maxLineCount) {
-        throw new SandboxToolPolicyError(
-          `File read line count exceeds sandbox tool policy (${effectiveLineCount} > ${limits.maxLineCount}).`
+        throw toolPolicyError(
+          `File read line count exceeds policy (${effectiveLineCount} > ${limits.maxLineCount}).`
         );
       }
-      if (session.readTextFilePage !== void 0) {
-        return session.readTextFilePage(path3, {
-          startLine: effectiveStartLine,
-          lineCount: effectiveLineCount,
-          maxBytes: limits.maxBytes
-        });
-      }
-      return createTextFilePage(await session.readTextFile(path3), {
-        startLine: effectiveStartLine,
+      let readOptions = {
+        path: path3,
+        startLine: startLine ?? 1,
         lineCount: effectiveLineCount,
         maxBytes: limits.maxBytes
-      });
+      };
+      if (context.abortSignal !== void 0) {
+        readOptions = { ...readOptions, abortSignal: context.abortSignal };
+      }
+      return options.sandbox.readTextFilePage(readOptions);
     }
   });
 }
-function createWriteFileTool(session, options) {
+function createWriteFileTool(options) {
   return createTool({
     name: "write_file",
-    description: "Write a text file inside the sandbox workspace. Creates parent directories.",
-    input: writeFileInput,
-    output: textOutput,
-    execute: async ({ path: path3, content }) => {
-      assertContentAllowed(content, options);
-      await session.writeTextFile(path3, content);
-      return `Wrote ${path3}`;
+    description: "Write a complete UTF-8 text file inside the sandbox workspace.",
+    inputSchema: writeFileInput,
+    outputSchema: writeFileOutput,
+    execute: async ({ path: path3, content }, context) => {
+      const bytesWritten = new TextEncoder().encode(content).byteLength;
+      const maxBytes = options.writeFile?.maxBytes;
+      if (maxBytes !== void 0 && bytesWritten > maxBytes) {
+        throw toolPolicyError(`File content exceeds policy (${bytesWritten} > ${maxBytes}).`);
+      }
+      let writeOptions = {
+        path: path3,
+        text: content
+      };
+      if (context.abortSignal !== void 0) {
+        writeOptions = { ...writeOptions, abortSignal: context.abortSignal };
+      }
+      await options.sandbox.writeTextFile(writeOptions);
+      return { path: path3, bytesWritten };
     }
   });
 }
-function createListFilesTool(session) {
+function createListFilesTool(sandbox) {
   return createTool({
     name: "list_files",
-    description: "List files and directories inside the sandbox workspace.",
-    input: listFilesInput,
-    output: textOutput,
-    execute: async ({ path: path3 }) => {
-      const entries = await session.listFiles(path3);
-      if (entries.length === 0) {
-        return "No files found.";
+    description: "List direct children of a directory in the sandbox workspace.",
+    inputSchema: listFilesInput,
+    outputSchema: listFilesOutput,
+    execute: async ({ path: path3 }, context) => {
+      let listOptions = {};
+      if (path3 !== void 0) listOptions = { ...listOptions, path: path3 };
+      if (context.abortSignal !== void 0) {
+        listOptions = { ...listOptions, abortSignal: context.abortSignal };
       }
-      return entries.map((entry) => {
-        const size = entry.size === void 0 ? "" : ` ${entry.size}b`;
-        return `${entry.type}${size}	${entry.path}`;
-      }).join("\n");
+      return { path: path3 ?? ".", entries: [...await sandbox.listFiles(listOptions)] };
     }
   });
 }
-function createListPortsTool(session) {
+function createListPortsTool(sandbox) {
   return createTool({
     name: "list_ports",
-    description: "List pre-authorized sandbox preview ports. Servers must bind to 0.0.0.0 on a listed container port.",
-    input: emptyInput,
-    output: textOutput,
-    execute: async () => {
-      if (session.publishedPorts.length === 0) {
-        return "No sandbox ports are published.";
-      }
-      return session.publishedPorts.map((port) => `${port.containerPort}/${port.protocol}	${port.host}:${port.hostPort}`).join("\n");
-    }
+    description: "List explicitly published localhost TCP ports for the sandbox.",
+    inputSchema: emptyInput,
+    outputSchema: listPortsOutput,
+    execute: async () => ({ ports: [...sandbox.publishedPorts] })
   });
 }
-function createStartProcessTool(session, options) {
+function createStartProcessTool(options) {
   return createTool({
     name: "start_process",
-    description: "Start a managed long-running process inside the sandbox. Use list_ports first and bind web servers to 0.0.0.0.",
-    input: startProcessInput,
-    output: textOutput,
-    execute: async ({ command, args, cwd, env }) => {
-      assertCommandAllowed(command, options);
-      const processOptions = { command };
-      if (args !== void 0) processOptions.args = args;
-      if (cwd !== void 0) processOptions.cwd = cwd;
-      if (env !== void 0) processOptions.env = env;
-      return formatProcessInfo(await session.startProcess(processOptions));
+    description: "Start a managed long-running process inside the sandbox.",
+    inputSchema: startProcessInput,
+    outputSchema: processInfoOutput,
+    execute: async ({ command, args, cwd, env }, context) => {
+      assertCommandAllowed(command, options.exec?.commands);
+      let startOptions = { command };
+      if (args !== void 0) startOptions = { ...startOptions, args };
+      if (cwd !== void 0) startOptions = { ...startOptions, cwd };
+      if (env !== void 0) startOptions = { ...startOptions, env };
+      if (context.abortSignal !== void 0) {
+        startOptions = { ...startOptions, abortSignal: context.abortSignal };
+      }
+      return serializeProcessInfo(await options.sandbox.startProcess(startOptions));
     }
   });
 }
-function createListProcessesTool(session) {
+function createListProcessesTool(sandbox) {
   return createTool({
     name: "list_processes",
-    description: "List managed sandbox processes and their current status.",
-    input: emptyInput,
-    output: textOutput,
-    execute: async () => {
-      const processes = await session.listProcesses();
-      if (processes.length === 0) return "No managed processes.";
-      return processes.map(formatProcessInfo).join("\n\n");
-    }
+    description: "List processes managed by this live sandbox handle.",
+    inputSchema: emptyInput,
+    outputSchema: listProcessesOutput,
+    execute: async (_, context) => ({
+      processes: (await sandbox.listProcesses(
+        context.abortSignal === void 0 ? {} : { abortSignal: context.abortSignal }
+      )).map(serializeProcessInfo)
+    })
   });
 }
-function createReadProcessLogsTool(session, options) {
+function createReadProcessLogsTool(options) {
+  const maxLogBytes = options.process?.maxLogBytes ?? 64 * 1024;
   return createTool({
     name: "read_process_logs",
-    description: "Read recent stdout and stderr from a managed sandbox process.",
-    input: readProcessLogsInput,
-    output: textOutput,
-    execute: async ({ processId, tailBytes }) => {
-      const configuredMaxLogBytes = options.process?.maxLogBytes ?? 64 * 1024;
-      if (!Number.isInteger(configuredMaxLogBytes) || configuredMaxLogBytes < 0) {
-        throw new SandboxToolPolicyError("Process maxLogBytes must be a non-negative integer.");
-      }
-      const maxLogBytes = Math.min(configuredMaxLogBytes, maxToolLogBytes);
+    description: "Read bounded UTF-8 output from a managed sandbox process.",
+    inputSchema: readProcessLogsInput,
+    outputSchema: processLogsOutput,
+    execute: async ({ processId, tailBytes }, context) => {
       const effectiveTailBytes = tailBytes ?? maxLogBytes;
       if (effectiveTailBytes > maxLogBytes) {
-        throw new SandboxToolPolicyError(
-          `Process log request exceeds sandbox tool policy (${effectiveTailBytes} > ${maxLogBytes}).`
+        throw toolPolicyError(
+          `Process log request exceeds policy (${effectiveTailBytes} > ${maxLogBytes}).`
         );
       }
-      const logs = await session.readProcessLogs(processId, {
+      let readOptions = {
+        processId,
         tailBytes: effectiveTailBytes
-      });
-      const parts = [];
-      if (logs.stdout.length > 0) parts.push(`stdout:
-${logs.stdout.trimEnd()}`);
-      if (logs.stderr.length > 0) parts.push(`stderr:
-${logs.stderr.trimEnd()}`);
-      if (logs.stdoutTruncated || logs.stderrTruncated) parts.push("output_truncated: true");
-      return parts.length > 0 ? parts.join("\n\n") : "No process output.";
+      };
+      if (context.abortSignal !== void 0) {
+        readOptions = { ...readOptions, abortSignal: context.abortSignal };
+      }
+      const logs = await options.sandbox.readProcessLogs(readOptions);
+      return {
+        processId,
+        stdout: decodeUtf8(logs.stdout),
+        stderr: decodeUtf8(logs.stderr),
+        stdoutTruncated: logs.stdoutTruncated,
+        stderrTruncated: logs.stderrTruncated
+      };
     }
   });
 }
-function createStopProcessTool(session, options) {
+function createStopProcessTool(options) {
   return createTool({
     name: "stop_process",
-    description: "Stop a managed sandbox process.",
-    input: processIdInput,
-    output: textOutput,
-    execute: async ({ processId }) => formatProcessInfo(
-      await session.stopProcess(processId, {
+    description: "Stop a process managed by this live sandbox handle.",
+    inputSchema: processIdInput,
+    outputSchema: processInfoOutput,
+    execute: async ({ processId }, context) => {
+      let stopOptions = {
+        processId,
         gracePeriodMs: options.process?.stopGracePeriodMs ?? 5e3
-      })
-    )
+      };
+      if (context.abortSignal !== void 0) {
+        stopOptions = { ...stopOptions, abortSignal: context.abortSignal };
+      }
+      return serializeProcessInfo(await options.sandbox.stopProcess(stopOptions));
+    }
   });
 }
-function createWaitForPortTool(session, options) {
+function createWaitForPortTool(options) {
   return createTool({
     name: "wait_for_port",
-    description: "Wait until a pre-authorized sandbox TCP port is accepting connections.",
-    input: waitForPortInput,
-    output: textOutput,
-    execute: async ({ containerPort, timeoutMs }) => {
+    description: "Wait until an explicitly published sandbox TCP port is listening.",
+    inputSchema: waitForPortInput,
+    outputSchema: waitForPortOutput,
+    execute: async ({ containerPort, timeoutMs }, context) => {
       const effectiveTimeoutMs = timeoutMs ?? options.process?.defaultWaitTimeoutMs ?? 3e4;
-      const maxWaitTimeoutMs = options.process?.maxWaitTimeoutMs ?? 3e5;
+      const maxWaitTimeoutMs = options.process?.maxWaitTimeoutMs ?? maxToolTimeoutMs;
       if (effectiveTimeoutMs > maxWaitTimeoutMs) {
-        throw new SandboxToolPolicyError(
-          `Port wait timeout exceeds sandbox tool policy (${effectiveTimeoutMs} > ${maxWaitTimeoutMs}).`
+        throw toolPolicyError(
+          `Port wait timeout exceeds policy (${effectiveTimeoutMs} > ${maxWaitTimeoutMs}).`
         );
       }
-      const port = await session.waitForPort(containerPort, {
+      let waitOptions = {
+        containerPort,
         timeoutMs: effectiveTimeoutMs
-      });
-      return `ready: ${port.containerPort}/${port.protocol} -> ${port.host}:${port.hostPort}`;
+      };
+      if (context.abortSignal !== void 0) {
+        waitOptions = { ...waitOptions, abortSignal: context.abortSignal };
+      }
+      return { port: await options.sandbox.waitForPort(waitOptions) };
     }
   });
 }
-function formatExecResult(result) {
-  const parts = [`exit_code: ${result.exitCode}`];
-  if (result.timedOut) {
-    parts.push("timed_out: true");
-  }
-  if (result.aborted) {
-    parts.push("aborted: true");
-  }
-  if (result.stdout.length > 0) {
-    parts.push(`stdout:
-${result.stdout.trimEnd()}`);
-  }
-  if (result.stderr.length > 0) {
-    parts.push(`stderr:
-${result.stderr.trimEnd()}`);
-  }
-  if (result.stdoutTruncated || result.stderrTruncated) {
-    parts.push("output_truncated: true");
-  }
-  return parts.join("\n\n");
+function serializeExecResult(result) {
+  const output = {
+    status: result.status,
+    stdout: decodeUtf8(result.stdout),
+    stderr: decodeUtf8(result.stderr),
+    durationMs: result.durationMs,
+    stdoutTruncated: result.stdoutTruncated,
+    stderrTruncated: result.stderrTruncated
+  };
+  return result.status === "exited" ? { ...output, status: "exited", exitCode: result.exitCode } : { ...output, status: "timed_out" };
 }
-function formatProcessInfo(process) {
-  const parts = [
-    `process_id: ${process.id}`,
-    `status: ${process.status}`,
-    `command: ${[process.command, ...process.args].join(" ")}`
-  ];
-  if (process.exitCode !== void 0) parts.push(`exit_code: ${process.exitCode}`);
-  return parts.join("\n");
+function serializeProcessInfo(process) {
+  let serialized = {
+    id: process.id,
+    command: process.command,
+    args: [...process.args],
+    status: process.status,
+    startedAt: process.startedAt
+  };
+  if (process.cwd !== void 0) serialized = { ...serialized, cwd: process.cwd };
+  if (process.exitCode !== void 0) serialized = { ...serialized, exitCode: process.exitCode };
+  if (process.endedAt !== void 0) serialized = { ...serialized, endedAt: process.endedAt };
+  return serialized;
 }
-function requirePortSession(session) {
-  if (!isSandboxPortSession(session)) {
-    throw new SandboxToolPolicyError("The sandbox session does not support published port tools.");
+function validateFactoryOptions(options) {
+  if (!isRecord2(options)) {
+    throw new TypeError("options must be an object.");
+  }
+  if (!isDockerSandboxRuntime(options.sandbox)) {
+    throw new TypeError("sandbox must be a DockerSandboxRuntime.");
+  }
+  if (!Array.isArray(options.tools) || options.tools.length === 0) {
+    throw new TypeError("tools must be a non-empty array.");
+  }
+  const known = new Set(allToolNames);
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of options.tools) {
+    if (typeof name !== "string" || !known.has(name)) {
+      throw new TypeError("tools contains an unsupported sandbox tool name.");
+    }
+    if (seen.has(name)) throw new TypeError(`tools contains a duplicate: ${name}`);
+    seen.add(name);
+  }
+  for (const [name, policy] of [
+    ["exec", options.exec],
+    ["readFile", options.readFile],
+    ["writeFile", options.writeFile],
+    ["process", options.process]
+  ]) {
+    if (policy !== void 0 && !isRecord2(policy)) {
+      throw new TypeError(`${name} must be an object.`);
+    }
+  }
+  validateCommandPolicy(options.exec?.commands);
+  assertOptionalPositiveInteger(options.exec?.defaultTimeoutMs, "exec.defaultTimeoutMs");
+  assertOptionalPositiveInteger(options.exec?.maxTimeoutMs, "exec.maxTimeoutMs");
+  if ((options.exec?.defaultTimeoutMs ?? 0) > maxToolTimeoutMs || (options.exec?.maxTimeoutMs ?? 0) > maxToolTimeoutMs) {
+    throw toolPolicyError(`Sandbox tool command timeouts cannot exceed ${maxToolTimeoutMs}.`);
+  }
+  if (options.exec?.defaultTimeoutMs !== void 0 && options.exec.maxTimeoutMs !== void 0 && options.exec.defaultTimeoutMs > options.exec.maxTimeoutMs) {
+    throw toolPolicyError("exec.defaultTimeoutMs cannot exceed exec.maxTimeoutMs.");
+  }
+  assertOptionalBoundedPositiveInteger(options.readFile?.maxBytes, "readFile.maxBytes");
+  assertOptionalPositiveInteger(options.readFile?.defaultLineCount, "readFile.defaultLineCount");
+  assertOptionalPositiveInteger(options.readFile?.maxLineCount, "readFile.maxLineCount");
+  assertOptionalBoundedNonNegativeInteger(options.writeFile?.maxBytes, "writeFile.maxBytes");
+  assertOptionalBoundedNonNegativeInteger(options.process?.maxLogBytes, "process.maxLogBytes");
+  assertOptionalPositiveInteger(
+    options.process?.defaultWaitTimeoutMs,
+    "process.defaultWaitTimeoutMs"
+  );
+  assertOptionalPositiveInteger(options.process?.maxWaitTimeoutMs, "process.maxWaitTimeoutMs");
+  assertOptionalNonNegativeInteger(options.process?.stopGracePeriodMs, "process.stopGracePeriodMs");
+  const defaultWaitTimeoutMs = options.process?.defaultWaitTimeoutMs;
+  const maxWaitTimeoutMs = options.process?.maxWaitTimeoutMs ?? maxToolTimeoutMs;
+  if (maxWaitTimeoutMs > maxToolTimeoutMs) {
+    throw toolPolicyError(`process.maxWaitTimeoutMs cannot exceed ${maxToolTimeoutMs}.`);
   }
-  return session;
-}
-function requireProcessSession(session) {
-  if (!isSandboxProcessSession(session)) {
-    throw new SandboxToolPolicyError("The sandbox session does not support managed process tools.");
+  if (defaultWaitTimeoutMs !== void 0 && defaultWaitTimeoutMs > maxWaitTimeoutMs) {
+    throw toolPolicyError("process.defaultWaitTimeoutMs cannot exceed process.maxWaitTimeoutMs.");
   }
-  return session;
 }
-function assertProcessToolPolicy(options) {
-  const policy = options.process;
-  if (policy === void 0) return;
-  if (policy.maxLogBytes !== void 0 && (!Number.isInteger(policy.maxLogBytes) || policy.maxLogBytes < 0 || policy.maxLogBytes > maxToolLogBytes)) {
-    throw new SandboxToolPolicyError(
-      `Process maxLogBytes must be an integer from 0 to ${maxToolLogBytes}.`
-    );
+function snapshotFactoryOptions(options) {
+  const toolNames = Object.freeze([...options.tools]);
+  const commands = options.exec?.commands === void 0 ? void 0 : Object.freeze({
+    mode: options.exec.commands.mode,
+    values: Object.freeze([...options.exec.commands.values])
+  });
+  let snapshot = {
+    sandbox: options.sandbox,
+    tools: toolNames
+  };
+  if (options.exec !== void 0) {
+    let exec = { ...options.exec };
+    if (commands !== void 0) exec = { ...exec, commands };
+    snapshot = { ...snapshot, exec: Object.freeze(exec) };
   }
-  const maxWaitTimeoutMs = policy.maxWaitTimeoutMs ?? 3e5;
-  if (!Number.isInteger(maxWaitTimeoutMs) || maxWaitTimeoutMs <= 0 || maxWaitTimeoutMs > 3e5) {
-    throw new SandboxToolPolicyError(
-      "Process maxWaitTimeoutMs must be an integer from 1 to 300000."
-    );
+  if (options.readFile !== void 0) {
+    snapshot = { ...snapshot, readFile: Object.freeze({ ...options.readFile }) };
   }
-  if (policy.defaultWaitTimeoutMs !== void 0 && (!Number.isInteger(policy.defaultWaitTimeoutMs) || policy.defaultWaitTimeoutMs <= 0 || policy.defaultWaitTimeoutMs > maxWaitTimeoutMs)) {
-    throw new SandboxToolPolicyError(
-      "Process defaultWaitTimeoutMs must be positive and no greater than maxWaitTimeoutMs."
-    );
+  if (options.writeFile !== void 0) {
+    snapshot = { ...snapshot, writeFile: Object.freeze({ ...options.writeFile }) };
   }
-  if (policy.stopGracePeriodMs !== void 0 && (!Number.isInteger(policy.stopGracePeriodMs) || policy.stopGracePeriodMs < 0)) {
-    throw new SandboxToolPolicyError("Process stopGracePeriodMs must be a non-negative integer.");
+  if (options.process !== void 0) {
+    snapshot = { ...snapshot, process: Object.freeze({ ...options.process }) };
   }
+  return Object.freeze(snapshot);
 }
-function assertCommandAllowed(command, options) {
-  const policy = options.exec;
-  if (policy?.blockedCommands?.includes(command)) {
-    throw new SandboxToolPolicyError(`Command is blocked by sandbox tool policy: ${command}`);
+function validateCommandPolicy(policy) {
+  if (policy === void 0) return;
+  if (!isRecord2(policy)) throw toolPolicyError("exec.commands must be an object.");
+  if (policy.mode !== "allow" && policy.mode !== "block") {
+    throw toolPolicyError("exec.commands must use mode allow or block.");
   }
-  if (policy?.allowedCommands !== void 0 && !policy.allowedCommands.includes(command)) {
-    throw new SandboxToolPolicyError(`Command is not allowed by sandbox tool policy: ${command}`);
+  if (!Array.isArray(policy.values))
+    throw toolPolicyError("exec.commands.values must be an array.");
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of policy.values) {
+    if (typeof value !== "string" || value.length === 0) {
+      throw toolPolicyError("exec.commands.values must contain non-empty strings.");
+    }
+    if (seen.has(value))
+      throw toolPolicyError(`exec.commands.values contains a duplicate: ${value}`);
+    seen.add(value);
   }
 }
-function assertTimeoutAllowed(timeoutMs, options) {
-  const maxTimeoutMs = options.exec?.maxTimeoutMs;
-  if (maxTimeoutMs !== void 0 && timeoutMs > maxTimeoutMs) {
-    throw new SandboxToolPolicyError(
-      `Command timeout exceeds sandbox tool policy (${timeoutMs} > ${maxTimeoutMs}).`
-    );
+function assertCommandAllowed(command, policy) {
+  if (policy === void 0) return;
+  const included = policy.values.includes(command);
+  if (policy.mode === "allow" && !included || policy.mode === "block" && included) {
+    throw toolPolicyError(`Command is rejected by sandbox tool policy: ${command}`);
   }
 }
-function assertContentAllowed(content, options) {
-  const maxBytes = options.writeFile?.maxBytes;
-  if (maxBytes !== void 0 && Buffer.byteLength(content) > maxBytes) {
-    throw new SandboxToolPolicyError("File content exceeds sandbox tool policy.");
+function assertTimeoutAllowed(timeoutMs, maxTimeoutMs) {
+  if (timeoutMs !== void 0 && maxTimeoutMs !== void 0 && timeoutMs > maxTimeoutMs) {
+    throw toolPolicyError(`Command timeout exceeds policy (${timeoutMs} > ${maxTimeoutMs}).`);
   }
 }
 function resolveReadFileLimits(options) {
   const defaultLineCount = options.readFile?.defaultLineCount ?? defaultReadFileLineCount;
   const maxLineCount = options.readFile?.maxLineCount ?? defaultReadFileMaxLineCount;
   const maxBytes = options.readFile?.maxBytes ?? defaultReadFileMaxBytes;
-  if (!Number.isInteger(defaultLineCount) || defaultLineCount <= 0) {
-    throw new SandboxToolPolicyError("File defaultLineCount must be a positive integer.");
-  }
-  if (!Number.isInteger(maxLineCount) || maxLineCount <= 0 || maxLineCount > maxToolReadFileLines) {
-    throw new SandboxToolPolicyError(
-      `File maxLineCount must be a positive integer no greater than ${maxToolReadFileLines}.`
-    );
-  }
   if (defaultLineCount > maxLineCount) {
-    throw new SandboxToolPolicyError(
-      `File defaultLineCount exceeds maxLineCount (${defaultLineCount} > ${maxLineCount}).`
-    );
+    throw toolPolicyError("readFile.defaultLineCount cannot exceed readFile.maxLineCount.");
   }
-  if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > maxToolReadFileBytes) {
-    throw new SandboxToolPolicyError(
-      `File maxBytes must be a positive integer no greater than ${maxToolReadFileBytes}.`
-    );
+  if (maxLineCount > maxToolReadFileLines) {
+    throw toolPolicyError(`readFile.maxLineCount cannot exceed ${maxToolReadFileLines}.`);
   }
   return { defaultLineCount, maxLineCount, maxBytes };
 }
+function assertOptionalPositiveInteger(value, name) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
+    throw toolPolicyError(`${name} must be a positive safe integer.`);
+  }
+}
+function assertOptionalNonNegativeInteger(value, name) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) {
+    throw toolPolicyError(`${name} must be a non-negative safe integer.`);
+  }
+}
+function assertOptionalBoundedNonNegativeInteger(value, name) {
+  assertOptionalNonNegativeInteger(value, name);
+  if (value !== void 0 && value > maxToolBytes) {
+    throw toolPolicyError(`${name} cannot exceed ${maxToolBytes}.`);
+  }
+}
+function assertOptionalBoundedPositiveInteger(value, name) {
+  assertOptionalPositiveInteger(value, name);
+  if (value !== void 0 && value > maxToolBytes) {
+    throw toolPolicyError(`${name} cannot exceed ${maxToolBytes}.`);
+  }
+}
+function isDockerSandboxRuntime(value) {
+  if (!isRecord2(value)) return false;
+  return typeof value.id === "string" && value.provider === "docker" && typeof value.workdir === "string" && Array.isArray(value.publishedPorts) && [
+    "exec",
+    "execStream",
+    "readFile",
+    "readTextFile",
+    "readTextFilePage",
+    "writeFile",
+    "writeTextFile",
+    "listFiles",
+    "startProcess",
+    "listProcesses",
+    "readProcessLogs",
+    "stopProcess",
+    "waitForPort"
+  ].every((name) => typeof value[name] === "function");
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toolPolicyError(message) {
+  return new DockerSandboxError(message, "tool_policy");
+}
 export {
-  DockerSandbox,
-  SandboxDockerCommandError,
-  SandboxDockerUnavailableError,
-  SandboxError,
-  SandboxFileSizeError,
-  SandboxPathError,
-  SandboxPortError,
-  SandboxProcessError,
-  SandboxSessionDestroyedError,
-  SandboxTimeoutError,
-  SandboxToolPolicyError,
-  createSandboxTools,
-  isSandboxPortSession,
-  isSandboxProcessSession
+  DockerSandboxClient,
+  DockerSandboxError,
+  createDockerSandboxTools
 };
 //# sourceMappingURL=index.js.map