@anvia/sandbox 0.3.7 → 0.4.1

package/dist/index.js

@@ -1,5 +1,15 @@
+// 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";
+}
+
 // src/docker-sandbox.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { mkdtemp, rm, writeFile } from "fs/promises";
 import os from "os";
 import path2 from "path";
@@ -35,6 +45,10 @@ var SandboxFileSizeError = class extends SandboxError {
 };
 var SandboxToolPolicyError = class extends SandboxError {
 };
+var SandboxPortError = class extends SandboxError {
+};
+var SandboxProcessError = class extends SandboxError {
+};
 
 // src/docker-cli.ts
 var defaultMaxOutputBytes = 1024 * 1024;
@@ -138,6 +152,10 @@ function createOutputCollector(maxBytes, onChunk) {
   };
 }
 
+// src/docker-process.ts
+import { spawn as spawn2 } from "child_process";
+import { randomUUID } from "crypto";
+
 // src/path.ts
 import path from "path";
 function normalizeSandboxPath(input, options = {}) {
@@ -172,11 +190,499 @@ function parentSandboxPath(relativePath) {
   return parent === "." ? "." : parent;
 }
 
+// src/docker-process.ts
+var processMarkerPrefix = "ANVIA_PROCESS";
+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"`,
+  "terminate() {",
+  '  wait "$child" 2>/dev/null || true',
+  "  exit 143",
+  "}",
+  "trap terminate TERM INT",
+  'wait "$child"',
+  "exit $?"
+].join("\n");
+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.");
+    }
+    if (!Number.isInteger(options.maxOutputBytes) || options.maxOutputBytes < 0) {
+      throw new SandboxProcessError("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.");
+    }
+  }
+  options;
+  records = /* @__PURE__ */ new Map();
+  disposed = false;
+  async start(options) {
+    this.assertActive();
+    assertStartOptions(options);
+    await this.pruneCompletedRecords();
+    const trackedCount = this.records.size;
+    if (trackedCount >= this.options.maxProcesses) {
+      throw new SandboxProcessError(
+        `Sandbox process limit reached (${trackedCount} >= ${this.options.maxProcesses}).`
+      );
+    }
+    const id = randomUUID();
+    const marker = `${processMarkerPrefix}:${id}`;
+    const dockerArgs = this.createExecArgs(options, marker);
+    const child = spawn2(this.options.dockerPath, dockerArgs, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    child.stdin.end();
+    let resolveStarted;
+    let rejectStarted;
+    const started = new Promise((resolve, reject) => {
+      resolveStarted = resolve;
+      rejectStarted = reject;
+    });
+    let resolveClosed;
+    const closed = new Promise((resolve) => {
+      resolveClosed = resolve;
+    });
+    const info = {
+      id,
+      command: options.command,
+      args: [...options.args ?? []],
+      status: "running",
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    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),
+      markerStart: Buffer.from(`${marker}:`),
+      markerBuffer: Buffer.alloc(0),
+      spawnFailed: false,
+      stopRequested: false,
+      startResolved: false,
+      exitNotified: false,
+      resolveStarted,
+      rejectStarted,
+      started,
+      resolveClosed,
+      closed
+    };
+    this.records.set(id, record);
+    this.observe(record);
+    try {
+      await this.waitForStart(record);
+      await this.options.onStart?.(copyProcessInfo(record.info));
+      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);
+      throw error;
+    }
+  }
+  list() {
+    this.assertActive();
+    return [...this.records.values()].map((record) => copyProcessInfo(record.info));
+  }
+  logs(processId, options = {}) {
+    this.assertActive();
+    const record = this.getRecord(processId);
+    const stdout = record.stdout.snapshot(options.tailBytes);
+    const stderr = record.stderr.snapshot(options.tailBytes);
+    return {
+      stdout: stdout.text,
+      stderr: stderr.text,
+      stdoutTruncated: stdout.truncated,
+      stderrTruncated: stderr.truncated
+    };
+  }
+  async stop(processId, options = {}) {
+    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.");
+    }
+    try {
+      if (!await this.terminateRecord(record, gracePeriodMs)) {
+        throw new SandboxProcessError(`Sandbox process did not stop: ${processId}`);
+      }
+    } catch (error) {
+      if (record.info.status === "running") record.stopRequested = false;
+      throw error;
+    }
+    return copyProcessInfo(record.info);
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    await Promise.all(
+      [...this.records.values()].map(async (record) => {
+        await this.terminateRecord(record, 1e3).catch(() => false);
+      })
+    );
+  }
+  createExecArgs(options, marker) {
+    const args = ["exec", "-w", containerPath(this.options.workdir, options.cwd ?? ".")];
+    for (const [key, value] of Object.entries({ ...this.options.env, ...options.env })) {
+      args.push("-e", `${key}=${value}`);
+    }
+    args.push(
+      this.options.containerName,
+      "sh",
+      "-c",
+      processWrapper,
+      "anvia-managed-process",
+      marker,
+      options.command,
+      ...options.args ?? []
+    );
+    return args;
+  }
+  observe(record) {
+    record.child.stdout.on("data", (chunk) => this.acceptStdout(record, chunk));
+    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;
+      record.rejectStarted(normalized);
+    });
+    record.child.on("close", (code) => {
+      if (record.markerBuffer.length > 0) {
+        record.stdout.accept(record.markerBuffer);
+        record.markerBuffer = Buffer.alloc(0);
+      }
+      record.info.status = record.stopRequested ? "stopped" : "exited";
+      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}`
+        )
+      );
+      record.resolveClosed();
+      if (record.startResolved) this.notifyExit(record);
+    });
+  }
+  acceptStdout(record, chunk) {
+    if (record.supervisorPid !== void 0) {
+      record.stdout.accept(chunk);
+      return;
+    }
+    record.markerBuffer = Buffer.concat([record.markerBuffer, chunk]);
+    const start = record.markerBuffer.indexOf(record.markerStart);
+    if (start < 0) {
+      const retainedBytes = Math.max(0, record.markerStart.length - 1);
+      if (record.markerBuffer.length > retainedBytes) {
+        const split = record.markerBuffer.length - retainedBytes;
+        record.stdout.accept(record.markerBuffer.subarray(0, split));
+        record.markerBuffer = record.markerBuffer.subarray(split);
+      }
+      return;
+    }
+    const end = record.markerBuffer.indexOf(30, start + record.markerStart.length);
+    if (end < 0) {
+      if (start > 0) {
+        record.stdout.accept(record.markerBuffer.subarray(0, start));
+        record.markerBuffer = record.markerBuffer.subarray(start);
+      }
+      return;
+    }
+    const rawPids = record.markerBuffer.subarray(start + record.markerStart.length, end).toString("utf8").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.")
+      );
+      return;
+    }
+    if (start > 0) record.stdout.accept(record.markerBuffer.subarray(0, start));
+    if (end + 1 < record.markerBuffer.length) {
+      record.stdout.accept(record.markerBuffer.subarray(end + 1));
+    }
+    record.markerBuffer = Buffer.alloc(0);
+    record.supervisorPid = supervisorPid;
+    record.childPid = childPid;
+    record.processGroupId = processGroupId;
+    record.resolveStarted();
+  }
+  async waitForStart(record) {
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeout = setTimeout(() => {
+        reject(new SandboxTimeoutError("Starting sandbox process timed out."));
+      }, this.options.startupTimeoutMs);
+      timeout.unref?.();
+    });
+    try {
+      await Promise.race([record.started, timeoutPromise]);
+    } finally {
+      if (timeout !== void 0) clearTimeout(timeout);
+    }
+  }
+  async cleanupFailedStart(record) {
+    record.stopRequested = true;
+    if (record.processGroupId === void 0 && record.info.status === "running") {
+      await waitForPromise(record.closed, 250);
+    }
+    try {
+      return await this.terminateRecord(record, 1e3);
+    } catch {
+      return false;
+    }
+  }
+  async terminateRecord(record, gracePeriodMs) {
+    record.stopRequested = true;
+    if (record.processGroupId === void 0) {
+      if (record.info.status === "running") {
+        await waitForPromise(record.closed, Math.min(gracePeriodMs, 250));
+      }
+      if (record.processGroupId === void 0) {
+        return record.spawnFailed && record.info.status !== "running";
+      }
+    }
+    if (!await this.isProcessGroupRunning(record)) {
+      return this.finishAfterGroupExit(record);
+    }
+    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;
+    return false;
+  }
+  async waitForRecordExit(record, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      if (!await this.isProcessGroupRunning(record)) {
+        return this.finishAfterGroupExit(record);
+      }
+      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);
+      } else {
+        await waitForDelay(intervalMs);
+      }
+    }
+  }
+  async finishAfterGroupExit(record) {
+    if (record.info.status !== "running") return true;
+    record.child.kill("SIGKILL");
+    return waitForPromise(record.closed, 1e3);
+  }
+  async isProcessGroupRunning(record) {
+    if (record.processGroupId === void 0) return false;
+    const result = await runDockerCli(
+      [
+        "exec",
+        this.options.containerName,
+        "sh",
+        "-c",
+        'kill -0 "-$1" 2>/dev/null',
+        "anvia-process-group-check",
+        String(record.processGroupId)
+      ],
+      {
+        dockerPath: this.options.dockerPath,
+        timeoutMs: 5e3,
+        maxOutputBytes: this.options.maxOutputBytes
+      }
+    );
+    return result.exitCode === 0;
+  }
+  async signal(record, signal) {
+    if (record.processGroupId === void 0) return;
+    const result = await runDockerCli(
+      [
+        "exec",
+        this.options.containerName,
+        "sh",
+        "-c",
+        'kill "-$2" "-$1" 2>/dev/null || ! kill -0 "-$1" 2>/dev/null',
+        "anvia-process-signal",
+        String(record.processGroupId),
+        signal
+      ],
+      {
+        dockerPath: this.options.dockerPath,
+        timeoutMs: 5e3,
+        maxOutputBytes: this.options.maxOutputBytes
+      }
+    );
+    if (result.exitCode !== 0) {
+      throw new SandboxDockerCommandError(
+        `Unable to stop sandbox process: ${record.info.id}`,
+        result
+      );
+    }
+  }
+  getRecord(processId) {
+    const record = this.records.get(processId);
+    if (record === void 0) {
+      throw new SandboxProcessError(`Unknown sandbox process: ${processId}`);
+    }
+    return record;
+  }
+  async pruneCompletedRecords() {
+    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);
+      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.");
+    }
+  }
+};
+var TailOutputCollector = class {
+  constructor(maxBytes) {
+    this.maxBytes = maxBytes;
+  }
+  maxBytes;
+  chunks = [];
+  length = 0;
+  didTruncate = false;
+  accept(chunk) {
+    if (chunk.length === 0) return;
+    if (this.maxBytes <= 0) {
+      this.didTruncate = true;
+      return;
+    }
+    if (chunk.length >= this.maxBytes) {
+      this.chunks = [chunk.subarray(chunk.length - this.maxBytes)];
+      this.length = this.maxBytes;
+      this.didTruncate = true;
+      return;
+    }
+    this.chunks.push(chunk);
+    this.length += chunk.length;
+    while (this.length > this.maxBytes) {
+      const first = this.chunks[0];
+      if (first === void 0) break;
+      const overflow = this.length - this.maxBytes;
+      if (first.length <= overflow) {
+        this.chunks.shift();
+        this.length -= first.length;
+      } else {
+        this.chunks[0] = first.subarray(overflow);
+        this.length -= overflow;
+      }
+      this.didTruncate = true;
+    }
+  }
+  snapshot(tailBytes) {
+    if (tailBytes !== void 0 && (!Number.isInteger(tailBytes) || tailBytes < 0)) {
+      throw new SandboxProcessError("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"),
+      truncated: this.didTruncate || selected.length < bytes.length
+    };
+  }
+};
+function assertStartOptions(options) {
+  if (options.command.trim().length === 0) {
+    throw new SandboxProcessError("Sandbox process command cannot be empty.");
+  }
+}
+function isProcessId(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+function copyProcessInfo(info) {
+  const 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;
+  return copy;
+}
+async function waitForPromise(promise, timeoutMs) {
+  let timeout;
+  try {
+    return await Promise.race([
+      promise.then(() => true),
+      new Promise((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs);
+        timeout.unref?.();
+      })
+    ]);
+  } finally {
+    if (timeout !== void 0) clearTimeout(timeout);
+  }
+}
+async function waitForDelay(timeoutMs) {
+  await new Promise((resolve) => {
+    const timeout = setTimeout(resolve, timeoutMs);
+    timeout.unref?.();
+  });
+}
+
 // src/docker-sandbox.ts
 var defaultImage = "node:22-bookworm";
 var defaultWorkdir = "/workspace";
 var defaultTimeoutMs = 3e4;
 var defaultMaxOutputBytes2 = 1024 * 1024;
+var defaultMaxProcesses = 4;
+var portProbeScript = [
+  `port="$(printf '%04X' "$1")"`,
+  "for table in /proc/net/tcp /proc/net/tcp6; do",
+  '  [ -r "$table" ] || continue',
+  "  while read -r _ local _ state _; do",
+  '    case "$local" in',
+  '      "00000000:$port"|"00000000000000000000000000000000:$port")',
+  '        [ "$state" = "0A" ] && exit 0',
+  "        ;;",
+  "    esac",
+  '  done < "$table"',
+  "done",
+  "exit 1"
+].join("\n");
 var DockerSandbox = class _DockerSandbox {
   provider = "docker";
   image;
@@ -226,8 +732,10 @@ var DockerSandbox = class _DockerSandbox {
     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 ?? randomUUID());
+    const id = sanitizeResourceId(options.id ?? randomUUID2());
     const workspace = options.workspace ?? this.workspace;
     const workspaceId = getWorkspaceId(workspace, id);
     const containerName = `anvia-sandbox-${id}`;
@@ -236,13 +744,14 @@ var DockerSandbox = class _DockerSandbox {
     await assertDockerCli(["volume", "create", volumeName], this.cliOptions());
     try {
       await assertDockerCli(
-        this.createRunArgs(containerName, volumeName, workspace, options.metadata),
+        this.createRunArgs(containerName, volumeName, workspace, options.metadata, ports),
         {
           ...this.cliOptions(),
           timeoutMs: this.limits.timeoutMs ?? defaultTimeoutMs
         }
       );
-      const session = new DockerSandboxSession({
+      const publishedPorts = await this.inspectPublishedPorts(containerName, ports);
+      const session = new DockerSandboxSessionImpl({
         id,
         containerName,
         volumeName,
@@ -252,7 +761,8 @@ var DockerSandbox = class _DockerSandbox {
         lifecycle: this.lifecycle,
         removeVolumeOnDestroy,
         env: options.manifest?.env ?? {},
-        hooks: this.hooks
+        hooks: this.hooks,
+        publishedPorts
       });
       await session.applyManifest(options.manifest);
       await this.hooks.onSessionCreate?.(session.event());
@@ -274,7 +784,7 @@ var DockerSandbox = class _DockerSandbox {
       }
     }
   }
-  createRunArgs(containerName, volumeName, workspace, metadata) {
+  createRunArgs(containerName, volumeName, workspace, metadata, ports) {
     const args = [
       "run",
       "-d",
@@ -300,6 +810,9 @@ var DockerSandbox = class _DockerSandbox {
       }
     }
     this.appendNetworkArgs(args);
+    for (const port of ports) {
+      args.push("--publish", `127.0.0.1::${port}/tcp`);
+    }
     this.appendLimitArgs(args);
     this.appendSecurityArgs(args);
     if (this.user !== void 0) {
@@ -323,6 +836,52 @@ var DockerSandbox = class _DockerSandbox {
       args.push("--network", mode);
     }
   }
+  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 inspectPublishedPorts(containerName, ports) {
+    if (ports.length === 0) return [];
+    const raw = await assertDockerCli(
+      ["container", "inspect", "--format", "{{json .NetworkSettings.Ports}}", containerName],
+      this.cliOptions()
+    );
+    let mappings;
+    try {
+      mappings = JSON.parse(raw);
+    } catch (error) {
+      throw new SandboxPortError("Docker returned invalid published port metadata.", error);
+    }
+    if (!isRecord(mappings)) {
+      throw new SandboxPortError("Docker returned invalid published port metadata.");
+    }
+    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`);
@@ -360,10 +919,11 @@ var DockerSandbox = class _DockerSandbox {
     }
   }
 };
-var DockerSandboxSession = class {
+var DockerSandboxSessionImpl = class {
   provider = "docker";
   id;
   workdir;
+  publishedPorts;
   containerName;
   volumeName;
   dockerPath;
@@ -372,6 +932,7 @@ var DockerSandboxSession = class {
   removeVolumeOnDestroy;
   env;
   hooks;
+  processManager;
   ttlTimer;
   idleTimer;
   activeOperations = 0;
@@ -387,6 +948,44 @@ var DockerSandboxSession = class {
     this.removeVolumeOnDestroy = options.removeVolumeOnDestroy;
     this.env = options.env;
     this.hooks = options.hooks;
+    this.publishedPorts = options.publishedPorts;
+    this.processManager = new DockerProcessManager({
+      containerName: this.containerName,
+      dockerPath: this.dockerPath,
+      workdir: this.workdir,
+      env: this.env,
+      maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes2,
+      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);
+      }
+    });
     this.startLifecycleTimers();
   }
   async applyManifest(manifest) {
@@ -468,6 +1067,49 @@ var DockerSandboxSession = class {
       await run;
     }
   }
+  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);
@@ -537,6 +1179,7 @@ var DockerSandboxSession = class {
     }
     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(
@@ -578,6 +1221,24 @@ var DockerSandboxSession = class {
       maxOutputBytes: this.limits.maxOutputBytes ?? defaultMaxOutputBytes2
     };
   }
+  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)
+      }
+    );
+    return result.exitCode === 0;
+  }
   async execCommand(options) {
     if (options.command.trim().length === 0) {
       throw new SandboxDockerCommandError("Sandbox command cannot be empty.", {
@@ -697,7 +1358,7 @@ function shouldDestroyWorkspace(workspace) {
 }
 function sanitizeResourceId(id) {
   const sanitized = id.toLowerCase().replaceAll(/[^a-z0-9_.-]/g, "-").replaceAll(/^-+|-+$/g, "");
-  return sanitized.length > 0 ? sanitized : randomUUID();
+  return sanitized.length > 0 ? sanitized : randomUUID2();
 }
 function byteLength(data) {
   return typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
@@ -714,6 +1375,50 @@ function mapFindType(type) {
   }
   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 (unique.has(port)) {
+      throw new SandboxPortError(`Sandbox port is duplicated: ${port}`);
+    }
+    unique.add(port);
+  }
+  return [...unique];
+}
+function isValidPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertWaitOptions(timeoutMs, intervalMs) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new SandboxPortError("Port wait timeoutMs must be a positive integer.");
+  }
+  if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+    throw new SandboxPortError("Port wait intervalMs must be a positive integer.");
+  }
+}
+async function waitWithSignal(timeoutMs, signal) {
+  if (signal?.aborted === true) throw abortReason(signal);
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, timeoutMs);
+    const abort = () => {
+      clearTimeout(timeout);
+      reject(abortReason(signal));
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+function abortReason(signal) {
+  return signal?.reason ?? new SandboxPortError("Waiting for sandbox port was aborted.");
+}
 
 // src/tools.ts
 import { createTool } from "@anvia/core/tool";
@@ -736,7 +1441,26 @@ var writeFileInput = z.object({
 var listFilesInput = z.object({
   path: z.string().optional().describe("Relative directory path inside the sandbox. Defaults to root.")
 });
+var emptyInput = z.object({});
+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.")
+});
+var processIdInput = z.object({
+  processId: z.string().min(1).describe("Managed process identifier.")
+});
+var readProcessLogsInput = processIdInput.extend({
+  tailBytes: z.number().int().nonnegative().max(1024 * 1024).optional().describe("Maximum trailing bytes to return from each output stream.")
+});
+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.")
+});
 var textOutput = z.string();
+var maxToolLogBytes = 1024 * 1024;
+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"]
@@ -754,6 +1478,35 @@ function createSandboxTools(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;
 }
 function createExecCommandTool(session, options) {
@@ -834,6 +1587,114 @@ function createListFilesTool(session) {
     }
   });
 }
+function createListPortsTool(session) {
+  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");
+    }
+  });
+}
+function createStartProcessTool(session, 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));
+    }
+  });
+}
+function createListProcessesTool(session) {
+  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");
+    }
+  });
+}
+function createReadProcessLogsTool(session, options) {
+  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);
+      const effectiveTailBytes = tailBytes ?? maxLogBytes;
+      if (effectiveTailBytes > maxLogBytes) {
+        throw new SandboxToolPolicyError(
+          `Process log request exceeds sandbox tool policy (${effectiveTailBytes} > ${maxLogBytes}).`
+        );
+      }
+      const logs = await session.readProcessLogs(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.";
+    }
+  });
+}
+function createStopProcessTool(session, options) {
+  return createTool({
+    name: "stop_process",
+    description: "Stop a managed sandbox process.",
+    input: processIdInput,
+    output: textOutput,
+    execute: async ({ processId }) => formatProcessInfo(
+      await session.stopProcess(processId, {
+        gracePeriodMs: options.process?.stopGracePeriodMs ?? 5e3
+      })
+    )
+  });
+}
+function createWaitForPortTool(session, 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 }) => {
+      const effectiveTimeoutMs = timeoutMs ?? options.process?.defaultWaitTimeoutMs ?? 3e4;
+      const maxWaitTimeoutMs = options.process?.maxWaitTimeoutMs ?? 3e5;
+      if (effectiveTimeoutMs > maxWaitTimeoutMs) {
+        throw new SandboxToolPolicyError(
+          `Port wait timeout exceeds sandbox tool policy (${effectiveTimeoutMs} > ${maxWaitTimeoutMs}).`
+        );
+      }
+      const port = await session.waitForPort(containerPort, {
+        timeoutMs: effectiveTimeoutMs
+      });
+      return `ready: ${port.containerPort}/${port.protocol} -> ${port.host}:${port.hostPort}`;
+    }
+  });
+}
 function formatExecResult(result) {
   const parts = [`exit_code: ${result.exitCode}`];
   if (result.timedOut) {
@@ -855,6 +1716,50 @@ ${result.stderr.trimEnd()}`);
   }
   return parts.join("\n\n");
 }
+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 requirePortSession(session) {
+  if (!isSandboxPortSession(session)) {
+    throw new SandboxToolPolicyError("The sandbox session does not support published port tools.");
+  }
+  return session;
+}
+function requireProcessSession(session) {
+  if (!isSandboxProcessSession(session)) {
+    throw new SandboxToolPolicyError("The sandbox session does not support managed process tools.");
+  }
+  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}.`
+    );
+  }
+  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 (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 (policy.stopGracePeriodMs !== void 0 && (!Number.isInteger(policy.stopGracePeriodMs) || policy.stopGracePeriodMs < 0)) {
+    throw new SandboxToolPolicyError("Process stopGracePeriodMs must be a non-negative integer.");
+  }
+}
 function assertCommandAllowed(command, options) {
   const policy = options.exec;
   if (policy?.blockedCommands?.includes(command)) {
@@ -891,9 +1796,13 @@ export {
   SandboxError,
   SandboxFileSizeError,
   SandboxPathError,
+  SandboxPortError,
+  SandboxProcessError,
   SandboxSessionDestroyedError,
   SandboxTimeoutError,
   SandboxToolPolicyError,
-  createSandboxTools
+  createSandboxTools,
+  isSandboxPortSession,
+  isSandboxProcessSession
 };
 //# sourceMappingURL=index.js.map