@poolzin/pool-bot 2026.2.11 → 2026.2.18

package/dist/agents/sandbox/docker.js

@@ -1,44 +1,118 @@
 import { spawn } from "node:child_process";
-import { defaultRuntime } from "../../runtime.js";
-import { formatCliCommand } from "../../cli/command-format.js";
-import { DEFAULT_SANDBOX_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constants.js";
-import { readRegistry, updateRegistry } from "./registry.js";
-import { computeSandboxConfigHash } from "./config-hash.js";
-import { resolveSandboxAgentId, resolveSandboxScopeKey, slugifySessionKey } from "./shared.js";
-const HOT_CONTAINER_WINDOW_MS = 5 * 60 * 1000;
-export function execDocker(args, opts) {
+function createAbortError() {
+    const err = new Error("Aborted");
+    err.name = "AbortError";
+    return err;
+}
+export function execDockerRaw(args, opts) {
     return new Promise((resolve, reject) => {
         const child = spawn("docker", args, {
-            stdio: ["ignore", "pipe", "pipe"],
+            stdio: ["pipe", "pipe", "pipe"],
         });
-        let stdout = "";
-        let stderr = "";
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let aborted = false;
+        const signal = opts?.signal;
+        const handleAbort = () => {
+            if (aborted) {
+                return;
+            }
+            aborted = true;
+            child.kill("SIGTERM");
+        };
+        if (signal) {
+            if (signal.aborted) {
+                handleAbort();
+            }
+            else {
+                signal.addEventListener("abort", handleAbort);
+            }
+        }
         child.stdout?.on("data", (chunk) => {
-            stdout += chunk.toString();
+            stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
         });
         child.stderr?.on("data", (chunk) => {
-            stderr += chunk.toString();
+            stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        child.on("error", (error) => {
+            if (signal) {
+                signal.removeEventListener("abort", handleAbort);
+            }
+            reject(error);
         });
         child.on("close", (code) => {
+            if (signal) {
+                signal.removeEventListener("abort", handleAbort);
+            }
+            const stdout = Buffer.concat(stdoutChunks);
+            const stderr = Buffer.concat(stderrChunks);
+            if (aborted || signal?.aborted) {
+                reject(createAbortError());
+                return;
+            }
             const exitCode = code ?? 0;
             if (exitCode !== 0 && !opts?.allowFailure) {
-                reject(new Error(stderr.trim() || `docker ${args.join(" ")} failed`));
+                const message = stderr.length > 0 ? stderr.toString("utf8").trim() : "";
+                const error = Object.assign(new Error(message || `docker ${args.join(" ")} failed`), {
+                    code: exitCode,
+                    stdout,
+                    stderr,
+                });
+                reject(error);
                 return;
             }
             resolve({ stdout, stderr, code: exitCode });
         });
+        const stdin = child.stdin;
+        if (stdin) {
+            if (opts?.input !== undefined) {
+                stdin.end(opts.input);
+            }
+            else {
+                stdin.end();
+            }
+        }
     });
 }
+import { formatCliCommand } from "../../cli/command-format.js";
+import { defaultRuntime } from "../../runtime.js";
+import { computeSandboxConfigHash } from "./config-hash.js";
+import { DEFAULT_SANDBOX_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constants.js";
+import { readRegistry, updateRegistry } from "./registry.js";
+import { resolveSandboxAgentId, resolveSandboxScopeKey, slugifySessionKey } from "./shared.js";
+import { validateSandboxSecurity } from "./validate-sandbox-security.js";
+const HOT_CONTAINER_WINDOW_MS = 5 * 60 * 1000;
+export async function execDocker(args, opts) {
+    const result = await execDockerRaw(args, opts);
+    return {
+        stdout: result.stdout.toString("utf8"),
+        stderr: result.stderr.toString("utf8"),
+        code: result.code,
+    };
+}
+export async function readDockerContainerLabel(containerName, label) {
+    const result = await execDocker(["inspect", "-f", `{{ index .Config.Labels "${label}" }}`, containerName], { allowFailure: true });
+    if (result.code !== 0) {
+        return null;
+    }
+    const raw = result.stdout.trim();
+    if (!raw || raw === "<no value>") {
+        return null;
+    }
+    return raw;
+}
 export async function readDockerPort(containerName, port) {
     const result = await execDocker(["port", containerName, `${port}/tcp`], {
         allowFailure: true,
     });
-    if (result.code !== 0)
+    if (result.code !== 0) {
         return null;
+    }
     const line = result.stdout.trim().split(/\r?\n/)[0] ?? "";
     const match = line.match(/:(\d+)\s*$/);
-    if (!match)
+    if (!match) {
         return null;
+    }
     const mapped = Number.parseInt(match[1] ?? "", 10);
     return Number.isFinite(mapped) ? mapped : null;
 }
@@ -46,8 +120,9 @@ async function dockerImageExists(image) {
     const result = await execDocker(["image", "inspect", image], {
         allowFailure: true,
     });
-    if (result.code === 0)
+    if (result.code === 0) {
         return true;
+    }
     const stderr = result.stderr.trim();
     if (stderr.includes("No such image")) {
         return false;
@@ -56,8 +131,9 @@ async function dockerImageExists(image) {
 }
 export async function ensureDockerImage(image) {
     const exists = await dockerImageExists(image);
-    if (exists)
+    if (exists) {
         return;
+    }
     if (image === DEFAULT_SANDBOX_IMAGE) {
         await execDocker(["pull", "debian:bookworm-slim"]);
         await execDocker(["tag", "debian:bookworm-slim", DEFAULT_SANDBOX_IMAGE]);
@@ -69,13 +145,15 @@ export async function dockerContainerState(name) {
     const result = await execDocker(["inspect", "-f", "{{.State.Running}}", name], {
         allowFailure: true,
     });
-    if (result.code !== 0)
+    if (result.code !== 0) {
         return { exists: false, running: false };
+    }
     return { exists: true, running: result.stdout.trim() === "true" };
 }
 function normalizeDockerLimit(value) {
-    if (value === undefined || value === null)
+    if (value === undefined || value === null) {
         return undefined;
+    }
     if (typeof value === "number") {
         return Number.isFinite(value) ? String(value) : undefined;
     }
@@ -83,23 +161,29 @@ function normalizeDockerLimit(value) {
     return trimmed ? trimmed : undefined;
 }
 function formatUlimitValue(name, value) {
-    if (!name.trim())
+    if (!name.trim()) {
         return null;
+    }
     if (typeof value === "number" || typeof value === "string") {
         const raw = String(value).trim();
         return raw ? `${name}=${raw}` : null;
     }
     const soft = typeof value.soft === "number" ? Math.max(0, value.soft) : undefined;
     const hard = typeof value.hard === "number" ? Math.max(0, value.hard) : undefined;
-    if (soft === undefined && hard === undefined)
+    if (soft === undefined && hard === undefined) {
         return null;
-    if (soft === undefined)
+    }
+    if (soft === undefined) {
         return `${name}=${hard}`;
-    if (hard === undefined)
+    }
+    if (hard === undefined) {
         return `${name}=${soft}`;
+    }
     return `${name}=${soft}:${hard}`;
 }
 export function buildSandboxCreateArgs(params) {
+    // Runtime security validation: blocks dangerous bind mounts, network modes, and profiles.
+    validateSandboxSecurity(params.cfg);
     const createdAtMs = params.createdAtMs ?? Date.now();
     const args = ["create", "--name", params.name];
     args.push("--label", "poolbot.sandbox=1");
@@ -109,18 +193,28 @@ export function buildSandboxCreateArgs(params) {
         args.push("--label", `poolbot.configHash=${params.configHash}`);
     }
     for (const [key, value] of Object.entries(params.labels ?? {})) {
-        if (key && value)
+        if (key && value) {
             args.push("--label", `${key}=${value}`);
+        }
     }
-    if (params.cfg.readOnlyRoot)
+    if (params.cfg.readOnlyRoot) {
         args.push("--read-only");
+    }
     for (const entry of params.cfg.tmpfs) {
         args.push("--tmpfs", entry);
     }
-    if (params.cfg.network)
+    if (params.cfg.network) {
         args.push("--network", params.cfg.network);
-    if (params.cfg.user)
+    }
+    if (params.cfg.user) {
         args.push("--user", params.cfg.user);
+    }
+    for (const [key, value] of Object.entries(params.cfg.env ?? {})) {
+        if (!key.trim()) {
+            continue;
+        }
+        args.push("--env", key + "=" + value);
+    }
     for (const cap of params.cfg.capDrop) {
         args.push("--cap-drop", cap);
     }
@@ -132,29 +226,34 @@ export function buildSandboxCreateArgs(params) {
         args.push("--security-opt", `apparmor=${params.cfg.apparmorProfile}`);
     }
     for (const entry of params.cfg.dns ?? []) {
-        if (entry.trim())
+        if (entry.trim()) {
             args.push("--dns", entry);
+        }
     }
     for (const entry of params.cfg.extraHosts ?? []) {
-        if (entry.trim())
+        if (entry.trim()) {
             args.push("--add-host", entry);
+        }
     }
     if (typeof params.cfg.pidsLimit === "number" && params.cfg.pidsLimit > 0) {
         args.push("--pids-limit", String(params.cfg.pidsLimit));
     }
     const memory = normalizeDockerLimit(params.cfg.memory);
-    if (memory)
+    if (memory) {
         args.push("--memory", memory);
+    }
     const memorySwap = normalizeDockerLimit(params.cfg.memorySwap);
-    if (memorySwap)
+    if (memorySwap) {
         args.push("--memory-swap", memorySwap);
+    }
     if (typeof params.cfg.cpus === "number" && params.cfg.cpus > 0) {
         args.push("--cpus", String(params.cfg.cpus));
     }
     for (const [name, value] of Object.entries(params.cfg.ulimits ?? {})) {
         const formatted = formatUlimitValue(name, value);
-        if (formatted)
+        if (formatted) {
             args.push("--ulimit", formatted);
+        }
     }
     if (params.cfg.binds?.length) {
         for (const bind of params.cfg.binds) {
@@ -187,13 +286,7 @@ async function createSandboxContainer(params) {
     }
 }
 async function readContainerConfigHash(containerName) {
-    const result = await execDocker(["inspect", "-f", '{{ index .Config.Labels "poolbot.configHash" }}', containerName], { allowFailure: true });
-    if (result.code !== 0)
-        return null;
-    const raw = result.stdout.trim();
-    if (!raw || raw === "<no value>")
-        return null;
-    return raw;
+    return await readDockerContainerLabel(containerName, "poolbot.configHash");
 }
 function formatSandboxRecreateHint(params) {
     if (params.scope === "session") {

package/dist/agents/sandbox/fs-bridge.js

@@ -0,0 +1,146 @@
+import { execDockerRaw } from "./docker.js";
+import { buildSandboxFsMounts, resolveSandboxFsPathWithMounts, } from "./fs-paths.js";
+export function createSandboxFsBridge(params) {
+    return new SandboxFsBridgeImpl(params.sandbox);
+}
+class SandboxFsBridgeImpl {
+    sandbox;
+    mounts;
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+        this.mounts = buildSandboxFsMounts(sandbox);
+    }
+    resolvePath(params) {
+        const target = this.resolveResolvedPath(params);
+        return {
+            hostPath: target.hostPath,
+            relativePath: target.relativePath,
+            containerPath: target.containerPath,
+        };
+    }
+    async readFile(params) {
+        const target = this.resolveResolvedPath(params);
+        const result = await this.runCommand('set -eu; cat -- "$1"', {
+            args: [target.containerPath],
+            signal: params.signal,
+        });
+        return result.stdout;
+    }
+    async writeFile(params) {
+        const target = this.resolveResolvedPath(params);
+        this.ensureWriteAccess(target, "write files");
+        const buffer = Buffer.isBuffer(params.data)
+            ? params.data
+            : Buffer.from(params.data, params.encoding ?? "utf8");
+        const script = params.mkdir === false
+            ? 'set -eu; cat >"$1"'
+            : 'set -eu; dir=$(dirname -- "$1"); if [ "$dir" != "." ]; then mkdir -p -- "$dir"; fi; cat >"$1"';
+        await this.runCommand(script, {
+            args: [target.containerPath],
+            stdin: buffer,
+            signal: params.signal,
+        });
+    }
+    async mkdirp(params) {
+        const target = this.resolveResolvedPath(params);
+        this.ensureWriteAccess(target, "create directories");
+        await this.runCommand('set -eu; mkdir -p -- "$1"', {
+            args: [target.containerPath],
+            signal: params.signal,
+        });
+    }
+    async remove(params) {
+        const target = this.resolveResolvedPath(params);
+        this.ensureWriteAccess(target, "remove files");
+        const flags = [params.force === false ? "" : "-f", params.recursive ? "-r" : ""].filter(Boolean);
+        const rmCommand = flags.length > 0 ? `rm ${flags.join(" ")}` : "rm";
+        await this.runCommand(`set -eu; ${rmCommand} -- "$1"`, {
+            args: [target.containerPath],
+            signal: params.signal,
+        });
+    }
+    async rename(params) {
+        const from = this.resolveResolvedPath({ filePath: params.from, cwd: params.cwd });
+        const to = this.resolveResolvedPath({ filePath: params.to, cwd: params.cwd });
+        this.ensureWriteAccess(from, "rename files");
+        this.ensureWriteAccess(to, "rename files");
+        await this.runCommand('set -eu; dir=$(dirname -- "$2"); if [ "$dir" != "." ]; then mkdir -p -- "$dir"; fi; mv -- "$1" "$2"', {
+            args: [from.containerPath, to.containerPath],
+            signal: params.signal,
+        });
+    }
+    async stat(params) {
+        const target = this.resolveResolvedPath(params);
+        const result = await this.runCommand('set -eu; stat -c "%F|%s|%Y" -- "$1"', {
+            args: [target.containerPath],
+            signal: params.signal,
+            allowFailure: true,
+        });
+        if (result.code !== 0) {
+            const stderr = result.stderr.toString("utf8");
+            if (stderr.includes("No such file or directory")) {
+                return null;
+            }
+            const message = stderr.trim() || `stat failed with code ${result.code}`;
+            throw new Error(`stat failed for ${target.containerPath}: ${message}`);
+        }
+        const text = result.stdout.toString("utf8").trim();
+        const [typeRaw, sizeRaw, mtimeRaw] = text.split("|");
+        const size = Number.parseInt(sizeRaw ?? "0", 10);
+        const mtime = Number.parseInt(mtimeRaw ?? "0", 10) * 1000;
+        return {
+            type: coerceStatType(typeRaw),
+            size: Number.isFinite(size) ? size : 0,
+            mtimeMs: Number.isFinite(mtime) ? mtime : 0,
+        };
+    }
+    async runCommand(script, options = {}) {
+        const dockerArgs = [
+            "exec",
+            "-i",
+            this.sandbox.containerName,
+            "sh",
+            "-c",
+            script,
+            "moltbot-sandbox-fs",
+        ];
+        if (options.args?.length) {
+            dockerArgs.push(...options.args);
+        }
+        return execDockerRaw(dockerArgs, {
+            input: options.stdin,
+            allowFailure: options.allowFailure,
+            signal: options.signal,
+        });
+    }
+    ensureWriteAccess(target, action) {
+        if (!allowsWrites(this.sandbox.workspaceAccess) || !target.writable) {
+            throw new Error(`Sandbox path is read-only; cannot ${action}: ${target.containerPath}`);
+        }
+    }
+    resolveResolvedPath(params) {
+        return resolveSandboxFsPathWithMounts({
+            filePath: params.filePath,
+            cwd: params.cwd ?? this.sandbox.workspaceDir,
+            defaultWorkspaceRoot: this.sandbox.workspaceDir,
+            defaultContainerRoot: this.sandbox.containerWorkdir,
+            mounts: this.mounts,
+        });
+    }
+}
+function allowsWrites(access) {
+    return access === "rw";
+}
+function coerceStatType(typeRaw) {
+    if (!typeRaw) {
+        return "other";
+    }
+    const normalized = typeRaw.trim().toLowerCase();
+    if (normalized.includes("directory")) {
+        return "directory";
+    }
+    if (normalized.includes("file")) {
+        return "file";
+    }
+    return "other";
+}

package/dist/agents/sandbox/fs-paths.js

@@ -0,0 +1,205 @@
+import path from "node:path";
+import { resolveSandboxInputPath, resolveSandboxPath } from "../sandbox-paths.js";
+import { SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constants.js";
+export function parseSandboxBindMount(spec) {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const parsed = splitBindSpec(trimmed);
+    if (!parsed) {
+        return null;
+    }
+    const hostToken = parsed.host.trim();
+    const containerToken = parsed.container.trim();
+    if (!hostToken || !containerToken || !path.posix.isAbsolute(containerToken)) {
+        return null;
+    }
+    const optionsToken = parsed.options.trim().toLowerCase();
+    const optionParts = optionsToken
+        ? optionsToken
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+        : [];
+    const writable = !optionParts.includes("ro");
+    return {
+        hostRoot: path.resolve(hostToken),
+        containerRoot: normalizeContainerPath(containerToken),
+        writable,
+    };
+}
+function splitBindSpec(spec) {
+    const separator = getHostContainerSeparatorIndex(spec);
+    if (separator === -1) {
+        return null;
+    }
+    const host = spec.slice(0, separator);
+    const rest = spec.slice(separator + 1);
+    const optionsStart = rest.indexOf(":");
+    if (optionsStart === -1) {
+        return { host, container: rest, options: "" };
+    }
+    return {
+        host,
+        container: rest.slice(0, optionsStart),
+        options: rest.slice(optionsStart + 1),
+    };
+}
+function getHostContainerSeparatorIndex(spec) {
+    const hasDriveLetterPrefix = /^[A-Za-z]:[\\/]/.test(spec);
+    for (let i = hasDriveLetterPrefix ? 2 : 0; i < spec.length; i += 1) {
+        if (spec[i] === ":") {
+            return i;
+        }
+    }
+    return -1;
+}
+export function buildSandboxFsMounts(sandbox) {
+    const mounts = [
+        {
+            hostRoot: path.resolve(sandbox.workspaceDir),
+            containerRoot: normalizeContainerPath(sandbox.containerWorkdir),
+            writable: sandbox.workspaceAccess === "rw",
+            source: "workspace",
+        },
+    ];
+    if (sandbox.workspaceAccess !== "none" &&
+        path.resolve(sandbox.agentWorkspaceDir) !== path.resolve(sandbox.workspaceDir)) {
+        mounts.push({
+            hostRoot: path.resolve(sandbox.agentWorkspaceDir),
+            containerRoot: SANDBOX_AGENT_WORKSPACE_MOUNT,
+            writable: sandbox.workspaceAccess === "rw",
+            source: "agent",
+        });
+    }
+    for (const bind of sandbox.docker.binds ?? []) {
+        const parsed = parseSandboxBindMount(bind);
+        if (!parsed) {
+            continue;
+        }
+        mounts.push({
+            hostRoot: parsed.hostRoot,
+            containerRoot: parsed.containerRoot,
+            writable: parsed.writable,
+            source: "bind",
+        });
+    }
+    return dedupeMounts(mounts);
+}
+export function resolveSandboxFsPathWithMounts(params) {
+    const mountsByContainer = [...params.mounts].toSorted((a, b) => b.containerRoot.length - a.containerRoot.length);
+    const mountsByHost = [...params.mounts].toSorted((a, b) => b.hostRoot.length - a.hostRoot.length);
+    const input = params.filePath;
+    const inputPosix = normalizePosixInput(input);
+    if (path.posix.isAbsolute(inputPosix)) {
+        const containerMount = findMountByContainerPath(mountsByContainer, inputPosix);
+        if (containerMount) {
+            const rel = path.posix.relative(containerMount.containerRoot, inputPosix);
+            const hostPath = rel
+                ? path.resolve(containerMount.hostRoot, ...toHostSegments(rel))
+                : containerMount.hostRoot;
+            return {
+                hostPath,
+                containerPath: rel
+                    ? path.posix.join(containerMount.containerRoot, rel)
+                    : containerMount.containerRoot,
+                relativePath: toDisplayRelative({
+                    containerPath: rel
+                        ? path.posix.join(containerMount.containerRoot, rel)
+                        : containerMount.containerRoot,
+                    defaultContainerRoot: params.defaultContainerRoot,
+                }),
+                writable: containerMount.writable,
+            };
+        }
+    }
+    const hostResolved = resolveSandboxInputPath(input, params.cwd);
+    const hostMount = findMountByHostPath(mountsByHost, hostResolved);
+    if (hostMount) {
+        const relHost = path.relative(hostMount.hostRoot, hostResolved);
+        const relPosix = relHost ? relHost.split(path.sep).join(path.posix.sep) : "";
+        const containerPath = relPosix
+            ? path.posix.join(hostMount.containerRoot, relPosix)
+            : hostMount.containerRoot;
+        return {
+            hostPath: hostResolved,
+            containerPath,
+            relativePath: toDisplayRelative({
+                containerPath,
+                defaultContainerRoot: params.defaultContainerRoot,
+            }),
+            writable: hostMount.writable,
+        };
+    }
+    // Preserve legacy error wording for out-of-sandbox paths.
+    resolveSandboxPath({
+        filePath: input,
+        cwd: params.cwd,
+        root: params.defaultWorkspaceRoot,
+    });
+    throw new Error(`Path escapes sandbox root (${params.defaultWorkspaceRoot}): ${input}`);
+}
+function dedupeMounts(mounts) {
+    const seen = new Set();
+    const deduped = [];
+    for (const mount of mounts) {
+        const key = `${mount.hostRoot}=>${mount.containerRoot}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(mount);
+    }
+    return deduped;
+}
+function findMountByContainerPath(mounts, target) {
+    for (const mount of mounts) {
+        if (isPathInsidePosix(mount.containerRoot, target)) {
+            return mount;
+        }
+    }
+    return null;
+}
+function findMountByHostPath(mounts, target) {
+    for (const mount of mounts) {
+        if (isPathInsideHost(mount.hostRoot, target)) {
+            return mount;
+        }
+    }
+    return null;
+}
+function isPathInsidePosix(root, target) {
+    const rel = path.posix.relative(root, target);
+    if (!rel) {
+        return true;
+    }
+    return !(rel.startsWith("..") || path.posix.isAbsolute(rel));
+}
+function isPathInsideHost(root, target) {
+    const rel = path.relative(root, target);
+    if (!rel) {
+        return true;
+    }
+    return !(rel.startsWith("..") || path.isAbsolute(rel));
+}
+function toHostSegments(relativePosix) {
+    return relativePosix.split("/").filter(Boolean);
+}
+function toDisplayRelative(params) {
+    const rel = path.posix.relative(params.defaultContainerRoot, params.containerPath);
+    if (!rel) {
+        return "";
+    }
+    if (!rel.startsWith("..") && !path.posix.isAbsolute(rel)) {
+        return rel;
+    }
+    return params.containerPath;
+}
+function normalizeContainerPath(value) {
+    const normalized = path.posix.normalize(value);
+    return normalized === "." ? "/" : normalized;
+}
+function normalizePosixInput(value) {
+    return value.replace(/\\/g, "/").trim();
+}

package/dist/agents/sandbox/hash.js

@@ -0,0 +1,4 @@
+import crypto from "node:crypto";
+export function hashTextSha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}