@agentforge-ai/sandbox 0.6.0

package/dist/index.js

@@ -0,0 +1,701 @@
+// src/docker-sandbox.ts
+import Dockerode from "dockerode";
+import { randomUUID } from "crypto";
+
+// src/security.ts
+var BLOCKED_BIND_PREFIXES = [
+  "/var/run/docker.sock",
+  "/etc",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/boot",
+  "/root"
+];
+var DEFAULT_CAP_DROP = ["ALL"];
+var BASE_ALLOWED_IMAGE_PREFIXES = [
+  "node:",
+  "python:",
+  "ubuntu:",
+  "debian:",
+  "alpine:",
+  "agentforge/"
+];
+function validateBind(bind) {
+  const hostPath = bind.split(":")[0];
+  if (!hostPath) {
+    throw new SecurityError(`Invalid bind mount spec: "${bind}"`);
+  }
+  for (const blocked of BLOCKED_BIND_PREFIXES) {
+    if (hostPath === blocked || hostPath.startsWith(blocked + "/") || hostPath.startsWith(blocked)) {
+      throw new SecurityError(
+        `Bind mount "${bind}" is blocked. Host path "${hostPath}" matches blocked prefix "${blocked}".`
+      );
+    }
+  }
+}
+function validateBinds(binds) {
+  for (const bind of binds) {
+    validateBind(bind);
+  }
+}
+function validateImageName(image) {
+  if (!image || typeof image !== "string") {
+    throw new SecurityError("Image name must be a non-empty string.");
+  }
+  if (/[;&|`$(){}[\]<>]/.test(image)) {
+    throw new SecurityError(`Image name "${image}" contains forbidden characters.`);
+  }
+  if (process.env["NODE_ENV"] !== "production") {
+    return;
+  }
+  const extraPrefixes = (process.env["AGENTFORGE_ALLOWED_IMAGES"] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const allowedPrefixes = [...BASE_ALLOWED_IMAGE_PREFIXES, ...extraPrefixes];
+  const allowed = allowedPrefixes.some((prefix) => image.startsWith(prefix));
+  if (!allowed) {
+    throw new SecurityError(
+      `Image "${image}" is not on the allow-list. Allowed prefixes: ${allowedPrefixes.join(", ")}. Add custom prefixes via AGENTFORGE_ALLOWED_IMAGES env var.`
+    );
+  }
+}
+function validateCommand(command) {
+  if (!command || typeof command !== "string") {
+    throw new SecurityError("Command must be a non-empty string.");
+  }
+  const dangerousPatterns = [
+    /docker\.sock/i,
+    /nsenter\s/i,
+    /mount\s+-t\s+proc/i
+  ];
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      throw new SecurityError(
+        `Command contains a potentially dangerous pattern: ${pattern.source}`
+      );
+    }
+  }
+}
+var SecurityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SecurityError";
+  }
+};
+
+// src/docker-sandbox.ts
+var DEFAULT_IMAGE = "node:22-slim";
+var DEFAULT_EXEC_TIMEOUT_MS = 3e4;
+var DEFAULT_CONTAINER_WORKSPACE = "/workspace";
+function demuxDockerStream(buffer) {
+  let stdout = "";
+  let stderr = "";
+  let offset = 0;
+  while (offset + 8 <= buffer.length) {
+    const streamType = buffer[offset];
+    const frameSize = buffer.readUInt32BE(offset + 4);
+    offset += 8;
+    if (offset + frameSize > buffer.length) break;
+    const chunk = buffer.slice(offset, offset + frameSize).toString("utf8");
+    offset += frameSize;
+    if (streamType === 1) {
+      stdout += chunk;
+    } else if (streamType === 2) {
+      stderr += chunk;
+    }
+  }
+  return { stdout, stderr };
+}
+var DockerSandbox = class {
+  config;
+  docker;
+  container = null;
+  containerId = null;
+  killTimer = null;
+  /**
+   * @param config - Sandbox configuration.
+   * @param docker - Optional pre-configured Dockerode instance (useful in tests).
+   */
+  constructor(config, docker) {
+    const image = config.image ?? DEFAULT_IMAGE;
+    validateImageName(image);
+    if (config.binds && config.binds.length > 0) {
+      validateBinds(config.binds);
+    }
+    this.config = {
+      ...config,
+      image,
+      containerWorkspacePath: config.containerWorkspacePath ?? DEFAULT_CONTAINER_WORKSPACE
+    };
+    this.docker = docker ?? new Dockerode(
+      process.env["DOCKER_HOST"] ? { host: process.env["DOCKER_HOST"] } : { socketPath: "/var/run/docker.sock" }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /**
+   * Create and start the Docker container.
+   * Idempotent — calling start() on an already-running sandbox is a no-op.
+   */
+  async start() {
+    if (this.container) return;
+    const { image, scope, resourceLimits, binds, env, timeout, workspaceAccess, workspacePath, containerWorkspacePath } = this.config;
+    const name = `agentforge-${scope}-${randomUUID().slice(0, 8)}`;
+    const envArray = Object.entries(env ?? {}).map(([k, v]) => `${k}=${v}`);
+    const allBinds = [...binds ?? []];
+    if (workspaceAccess !== "none" && workspacePath) {
+      const mode = workspaceAccess === "ro" ? "ro" : "rw";
+      allBinds.push(`${workspacePath}:${containerWorkspacePath}:${mode}`);
+    }
+    const hostConfig = {
+      // Resource limits
+      CpuShares: resourceLimits?.cpuShares,
+      Memory: resourceLimits?.memoryMb ? resourceLimits.memoryMb * 1024 * 1024 : void 0,
+      PidsLimit: resourceLimits?.pidsLimit ?? 256,
+      // Security hardening
+      CapDrop: [...DEFAULT_CAP_DROP],
+      SecurityOpt: ["no-new-privileges:true"],
+      ReadonlyRootfs: false,
+      // Bind mounts
+      Binds: allBinds.length > 0 ? allBinds : void 0
+    };
+    this.container = await this.docker.createContainer({
+      name,
+      Image: image,
+      // Keep container alive — we run commands via exec
+      Cmd: ["/bin/sh", "-c", "while true; do sleep 3600; done"],
+      Env: envArray,
+      AttachStdin: false,
+      AttachStdout: false,
+      AttachStderr: false,
+      Tty: false,
+      NetworkDisabled: resourceLimits?.networkDisabled ?? false,
+      WorkingDir: containerWorkspacePath,
+      Labels: {
+        "agentforge.scope": scope,
+        "agentforge.managed": "true"
+      },
+      HostConfig: hostConfig
+    });
+    await this.container.start();
+    this.containerId = this.container.id;
+    if (timeout && timeout > 0) {
+      this.killTimer = setTimeout(() => {
+        void this.destroy();
+      }, timeout * 1e3);
+    }
+  }
+  /**
+   * Stop the container gracefully (10 s grace period then SIGKILL).
+   * The container is kept for potential restart.
+   */
+  async stop() {
+    this._clearKillTimer();
+    if (!this.container) return;
+    try {
+      const info = await this.container.inspect();
+      if (info.State.Running) {
+        await this.container.stop({ t: 10 });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Destroy the container and release all resources.
+   * Safe to call multiple times.
+   */
+  async destroy() {
+    this._clearKillTimer();
+    const container = this.container;
+    this.container = null;
+    this.containerId = null;
+    if (!container) return;
+    try {
+      await container.remove({ force: true });
+    } catch {
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a shell command inside the running container.
+   *
+   * @param command - Shell command string passed to `/bin/sh -c`.
+   * @param options - Per-call options (timeout, cwd, env overrides).
+   */
+  async exec(command, options = {}) {
+    if (!this.container) {
+      throw new Error("DockerSandbox: container is not running. Call start() first.");
+    }
+    validateCommand(command);
+    const timeoutMs = options.timeout ?? DEFAULT_EXEC_TIMEOUT_MS;
+    const envOverride = Object.entries(options.env ?? {}).map(([k, v]) => `${k}=${v}`);
+    const execInstance = await this.container.exec({
+      Cmd: ["/bin/sh", "-c", command],
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: false,
+      WorkingDir: options.cwd,
+      Env: envOverride.length > 0 ? envOverride : void 0
+    });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`DockerSandbox: exec timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      execInstance.start({ hijack: true, stdin: false }, (err, stream) => {
+        if (err) {
+          clearTimeout(timer);
+          reject(err);
+          return;
+        }
+        if (!stream) {
+          clearTimeout(timer);
+          reject(new Error("DockerSandbox: no stream returned from exec"));
+          return;
+        }
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", async () => {
+          clearTimeout(timer);
+          try {
+            const raw = Buffer.concat(chunks);
+            const { stdout, stderr } = demuxDockerStream(raw);
+            const inspectResult = await execInstance.inspect();
+            const exitCode = inspectResult.ExitCode ?? 0;
+            resolve({ stdout, stderr, exitCode });
+          } catch (inspectErr) {
+            reject(inspectErr);
+          }
+        });
+        stream.on("error", (streamErr) => {
+          clearTimeout(timer);
+          reject(streamErr);
+        });
+      });
+    });
+  }
+  /**
+   * Read a file from the container filesystem by running `cat`.
+   *
+   * @param path - Absolute path inside the container.
+   */
+  async readFile(path) {
+    const result = await this.exec(`cat "${path.replace(/"/g, '\\"')}"`);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `DockerSandbox.readFile: failed to read "${path}" (exit ${result.exitCode}): ${result.stderr}`
+      );
+    }
+    return result.stdout;
+  }
+  /**
+   * Write content to a file inside the container using base64 encoding
+   * to avoid shell quoting issues.
+   *
+   * @param path    - Absolute path inside the container.
+   * @param content - UTF-8 string content.
+   */
+  async writeFile(path, content) {
+    const b64 = Buffer.from(content, "utf8").toString("base64");
+    const cmd = `printf '%s' "${b64}" | base64 -d > "${path.replace(/"/g, '\\"')}"`;
+    const result = await this.exec(cmd);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `DockerSandbox.writeFile: failed to write "${path}" (exit ${result.exitCode}): ${result.stderr}`
+      );
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Health
+  // ---------------------------------------------------------------------------
+  /**
+   * Returns true if the underlying Docker container is running.
+   */
+  async isRunning() {
+    if (!this.container) return false;
+    try {
+      const info = await this.container.inspect();
+      return info.State.Running === true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Returns the Docker container ID or null if not yet started.
+   */
+  getContainerId() {
+    return this.containerId;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  _clearKillTimer() {
+    if (this.killTimer !== null) {
+      clearTimeout(this.killTimer);
+      this.killTimer = null;
+    }
+  }
+};
+
+// src/container-pool.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var DEFAULT_MAX_SIZE = 3;
+var DEFAULT_IDLE_TIMEOUT_SECONDS = 300;
+var SWEEP_INTERVAL_MS = 3e4;
+var ContainerPool = class {
+  config;
+  docker;
+  entries = /* @__PURE__ */ new Map();
+  sweepTimer = null;
+  draining = false;
+  constructor(config, docker) {
+    this.config = {
+      maxSize: DEFAULT_MAX_SIZE,
+      idleTimeoutSeconds: DEFAULT_IDLE_TIMEOUT_SECONDS,
+      ...config
+    };
+    this.docker = docker;
+  }
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+  /**
+   * Pre-warm the pool up to `maxSize` containers.
+   * Resolves once all warm containers are started.
+   */
+  async warmUp() {
+    const needed = this.config.maxSize - this.entries.size;
+    if (needed <= 0) return;
+    await Promise.all(
+      Array.from({ length: needed }).map(async () => {
+        await this._addEntry();
+      })
+    );
+    this._startSweep();
+  }
+  /**
+   * Acquire an idle sandbox from the pool.
+   *
+   * If an idle entry is available, it is marked in-use and returned immediately.
+   * If the pool is not yet at capacity, a new container is started and returned.
+   * If the pool is at capacity and all containers are in use, the LRU idle
+   * container is evicted and a fresh one is started.
+   *
+   * @throws If the pool is draining.
+   */
+  async acquire() {
+    if (this.draining) {
+      throw new Error("ContainerPool: pool is draining \u2014 cannot acquire new sandboxes.");
+    }
+    const idle = this._lruIdle();
+    if (idle) {
+      idle.inUse = true;
+      idle.lastUsedAt = Date.now();
+      return idle.sandbox;
+    }
+    if (this.entries.size < this.config.maxSize) {
+      const entry2 = await this._addEntry();
+      entry2.inUse = true;
+      entry2.lastUsedAt = Date.now();
+      return entry2.sandbox;
+    }
+    const lruKey = this._lruAnyKey();
+    if (lruKey) {
+      const evicted = this.entries.get(lruKey);
+      this.entries.delete(lruKey);
+      void evicted.sandbox.destroy().catch(() => {
+      });
+    }
+    const entry = await this._addEntry();
+    entry.inUse = true;
+    entry.lastUsedAt = Date.now();
+    return entry.sandbox;
+  }
+  /**
+   * Release a previously acquired sandbox back to the pool.
+   * The sandbox is reset to an idle state for future reuse.
+   */
+  async release(sandbox) {
+    for (const entry of this.entries.values()) {
+      if (entry.sandbox === sandbox) {
+        entry.inUse = false;
+        entry.lastUsedAt = Date.now();
+        return;
+      }
+    }
+    await sandbox.destroy();
+  }
+  /**
+   * Drain the pool: stop acquiring and destroy all containers.
+   * After draining, the pool stays in a drained state and rejects new acquires.
+   */
+  async drain() {
+    if (this.draining && this.entries.size === 0) return;
+    this.draining = true;
+    this._stopSweep();
+    await Promise.all(
+      Array.from(this.entries.values()).map(
+        (entry) => entry.sandbox.destroy().catch(() => {
+        })
+      )
+    );
+    this.entries.clear();
+  }
+  /**
+   * Returns the current number of entries (in-use + idle).
+   */
+  get size() {
+    return this.entries.size;
+  }
+  /**
+   * Returns the number of idle (available) entries.
+   */
+  get idleCount() {
+    let count = 0;
+    for (const entry of this.entries.values()) {
+      if (!entry.inUse) count++;
+    }
+    return count;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  async _addEntry() {
+    const sandboxConfig = {
+      image: this.config.image,
+      scope: this.config.scope,
+      workspaceAccess: "none"
+    };
+    const sandbox = new DockerSandbox(sandboxConfig, this.docker);
+    await sandbox.start();
+    const id = randomUUID2();
+    const entry = {
+      sandbox,
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+      inUse: false
+    };
+    this.entries.set(id, entry);
+    return entry;
+  }
+  /** Return the idle entry with the smallest lastUsedAt (LRU idle). */
+  _lruIdle() {
+    let best = null;
+    for (const entry of this.entries.values()) {
+      if (!entry.inUse) {
+        if (!best || entry.lastUsedAt < best.lastUsedAt) {
+          best = entry;
+        }
+      }
+    }
+    return best;
+  }
+  /** Return the key of the entry with the smallest lastUsedAt (LRU any). */
+  _lruAnyKey() {
+    let bestKey = null;
+    let bestTime = Infinity;
+    for (const [key, entry] of this.entries) {
+      if (entry.lastUsedAt < bestTime) {
+        bestTime = entry.lastUsedAt;
+        bestKey = key;
+      }
+    }
+    return bestKey;
+  }
+  /** Start periodic idle-eviction sweep. */
+  _startSweep() {
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(() => void this._sweep(), SWEEP_INTERVAL_MS);
+    if (this.sweepTimer.unref) this.sweepTimer.unref();
+  }
+  _stopSweep() {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+  /** Remove and destroy containers that have been idle past the timeout. */
+  async _sweep() {
+    if (this.draining) return;
+    const nowMs = Date.now();
+    const idleTimeoutMs = this.config.idleTimeoutSeconds * 1e3;
+    const evictions = [];
+    for (const [key, entry] of this.entries) {
+      if (!entry.inUse && nowMs - entry.lastUsedAt > idleTimeoutMs) {
+        evictions.push([key, entry]);
+      }
+    }
+    for (const [key, entry] of evictions) {
+      this.entries.delete(key);
+      await entry.sandbox.destroy().catch(() => {
+      });
+    }
+  }
+};
+
+// src/sandbox-manager.ts
+import Dockerode2 from "dockerode";
+import { randomUUID as randomUUID3 } from "crypto";
+var E2BProviderStub = class {
+  async start() {
+    throw new Error(
+      "SandboxManager: E2B provider is not bundled in @agentforge-ai/sandbox. Use the SandboxManager from @agentforge-ai/core instead."
+    );
+  }
+  async stop() {
+  }
+  async destroy() {
+  }
+  async exec(_cmd, _opts) {
+    throw new Error("E2BProviderStub: not implemented");
+  }
+  async readFile(_path) {
+    throw new Error("E2BProviderStub: not implemented");
+  }
+  async writeFile(_path, _content) {
+    throw new Error("E2BProviderStub: not implemented");
+  }
+  async isRunning() {
+    return false;
+  }
+  getContainerId() {
+    return null;
+  }
+};
+async function isDockerAvailable(docker) {
+  try {
+    await docker.ping();
+    return true;
+  } catch {
+    return false;
+  }
+}
+var SandboxManager = class {
+  config;
+  docker;
+  active = /* @__PURE__ */ new Map();
+  shutdownRegistered = false;
+  constructor(config = {}) {
+    this.config = { provider: "docker", ...config };
+    const dockerHostCfg = config.dockerHost;
+    if (dockerHostCfg?.host) {
+      this.docker = new Dockerode2({
+        host: dockerHostCfg.host,
+        port: dockerHostCfg.port ?? 2376,
+        protocol: dockerHostCfg.protocol ?? "http"
+      });
+    } else {
+      this.docker = new Dockerode2({
+        socketPath: dockerHostCfg?.socketPath ?? "/var/run/docker.sock"
+      });
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+  /**
+   * Initialize the manager. For the Docker provider this verifies that the
+   * Docker daemon is reachable. Call this once at application startup.
+   *
+   * @throws Error if the Docker daemon cannot be reached (Docker provider only).
+   */
+  async initialize() {
+    if (this.config.provider === "docker") {
+      const available = await isDockerAvailable(this.docker);
+      if (!available) {
+        console.warn(
+          "[SandboxManager] Docker daemon is not reachable. Agent tool execution will fail until Docker is started. Install Docker: https://docs.docker.com/get-docker/"
+        );
+      }
+    }
+    this._registerShutdownHandlers();
+  }
+  /**
+   * Create and start a new sandbox.
+   *
+   * The sandbox is registered internally; call {@link SandboxManager.destroy}
+   * or {@link SandboxManager.shutdown} to release it.
+   *
+   * @param overrides - Per-sandbox config overrides merged with manager defaults.
+   */
+  async create(overrides) {
+    if (this.config.provider === "e2b") {
+      const stub = new E2BProviderStub();
+      const id2 = this._generateId(overrides.scope);
+      this.active.set(id2, stub);
+      return stub;
+    }
+    const mergedConfig = {
+      image: "node:22-slim",
+      ...this.config.dockerConfig,
+      ...overrides
+    };
+    const sandbox = new DockerSandbox(mergedConfig, this.docker);
+    await sandbox.start();
+    const id = this._generateId(overrides.scope);
+    this.active.set(id, sandbox);
+    return sandbox;
+  }
+  /**
+   * Destroy a specific sandbox and remove it from the active registry.
+   */
+  async destroy(sandbox) {
+    await sandbox.destroy();
+    for (const [key, value] of this.active) {
+      if (value === sandbox) {
+        this.active.delete(key);
+        break;
+      }
+    }
+  }
+  /**
+   * Destroy all active sandboxes and shut the manager down.
+   * Called automatically on SIGTERM / SIGINT when registered.
+   */
+  async shutdown() {
+    const destroyAll = Array.from(this.active.values()).map(
+      (sb) => sb.destroy().catch((err) => {
+        console.error("[SandboxManager] Error destroying sandbox during shutdown:", err);
+      })
+    );
+    await Promise.all(destroyAll);
+    this.active.clear();
+  }
+  /**
+   * Returns the number of currently active sandboxes.
+   */
+  get activeCount() {
+    return this.active.size;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  _generateId(scope) {
+    return `agentforge-${scope}-${randomUUID3().slice(0, 8)}`;
+  }
+  _registerShutdownHandlers() {
+    if (this.shutdownRegistered) return;
+    this.shutdownRegistered = true;
+    const handler = () => {
+      void this.shutdown().finally(() => process.exit(0));
+    };
+    process.once("SIGTERM", handler);
+    process.once("SIGINT", handler);
+    process.once("beforeExit", () => void this.shutdown());
+  }
+};
+export {
+  BLOCKED_BIND_PREFIXES,
+  ContainerPool,
+  DEFAULT_CAP_DROP,
+  DockerSandbox,
+  SandboxManager,
+  SecurityError,
+  isDockerAvailable,
+  validateBind,
+  validateBinds,
+  validateCommand,
+  validateImageName
+};
+//# sourceMappingURL=index.js.map