@poolzin/pool-bot 2026.2.17 → 2026.2.18

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");
+}

package/dist/agents/sandbox-paths.js

@@ -24,6 +24,9 @@ function resolveToCwd(filePath, cwd) {
         return expanded;
     return path.resolve(cwd, expanded);
 }
+export function resolveSandboxInputPath(filePath, cwd) {
+    return resolveToCwd(filePath, cwd);
+}
 export function resolveSandboxPath(params) {
     const resolved = resolveToCwd(params.filePath, params.cwd);
     const rootResolved = path.resolve(params.root);

package/dist/agents/session-dirs.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function resolveAgentSessionDirs(stateDir) {
+    const agentsDir = path.join(stateDir, "agents");
+    let entries = [];
+    try {
+        entries = await fs.readdir(agentsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(agentsDir, entry.name, "sessions"))
+        .toSorted((a, b) => a.localeCompare(b));
+}

package/dist/agents/skills/filter.js

@@ -0,0 +1,24 @@
+export function normalizeSkillFilter(skillFilter) {
+    if (skillFilter === undefined) {
+        return undefined;
+    }
+    return skillFilter.map((entry) => String(entry).trim()).filter(Boolean);
+}
+export function normalizeSkillFilterForComparison(skillFilter) {
+    const normalized = normalizeSkillFilter(skillFilter);
+    if (normalized === undefined) {
+        return undefined;
+    }
+    return Array.from(new Set(normalized)).toSorted();
+}
+export function matchesSkillFilter(cached, next) {
+    const cachedNormalized = normalizeSkillFilterForComparison(cached);
+    const nextNormalized = normalizeSkillFilterForComparison(next);
+    if (cachedNormalized === undefined || nextNormalized === undefined) {
+        return cachedNormalized === nextNormalized;
+    }
+    if (cachedNormalized.length !== nextNormalized.length) {
+        return false;
+    }
+    return cachedNormalized.every((entry, index) => entry === nextNormalized[index]);
+}

package/dist/agents/skills/tools-dir.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+import { safePathSegmentHashed } from "../../infra/install-safe-path.js";
+import { resolveConfigDir } from "../../utils.js";
+import { resolveSkillKey } from "./frontmatter.js";
+export function resolveSkillToolsRootDir(entry) {
+    const key = resolveSkillKey(entry.skill, entry);
+    const safeKey = safePathSegmentHashed(key);
+    return path.join(resolveConfigDir(), "tools", safeKey);
+}

package/dist/agents/skills-install-download.js

@@ -0,0 +1,290 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { extractArchive as extractArchiveSafe } from "../infra/archive.js";
+import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
+import { isWithinDir, resolveSafeBaseDir } from "../infra/path-safety.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { ensureDir, resolveUserPath } from "../utils.js";
+import { formatInstallFailureMessage } from "./skills-install-output.js";
+import { hasBinary } from "./skills.js";
+import { resolveSkillToolsRootDir } from "./skills/tools-dir.js";
+function isNodeReadableStream(value) {
+    return Boolean(value && typeof value.pipe === "function");
+}
+function isWindowsDrivePath(p) {
+    return /^[a-zA-Z]:[\\/]/.test(p);
+}
+function resolveDownloadTargetDir(entry, spec) {
+    const safeRoot = resolveSkillToolsRootDir(entry);
+    const raw = spec.targetDir?.trim();
+    if (!raw) {
+        return safeRoot;
+    }
+    // Treat non-absolute paths as relative to the per-skill tools root.
+    const resolved = raw.startsWith("~") || path.isAbsolute(raw) || isWindowsDrivePath(raw)
+        ? resolveUserPath(raw)
+        : path.resolve(safeRoot, raw);
+    if (!isWithinDir(safeRoot, resolved)) {
+        throw new Error(`Refusing to install outside the skill tools directory. targetDir="${raw}" resolves to "${resolved}". Allowed root: "${safeRoot}".`);
+    }
+    return resolved;
+}
+function resolveArchiveType(spec, filename) {
+    const explicit = spec.archive?.trim().toLowerCase();
+    if (explicit) {
+        return explicit;
+    }
+    const lower = filename.toLowerCase();
+    if (lower.endsWith(".tar.gz") || lower.endsWith(".tgz")) {
+        return "tar.gz";
+    }
+    if (lower.endsWith(".tar.bz2") || lower.endsWith(".tbz2")) {
+        return "tar.bz2";
+    }
+    if (lower.endsWith(".zip")) {
+        return "zip";
+    }
+    return undefined;
+}
+function normalizeArchiveEntryPath(raw) {
+    return raw.replaceAll("\\", "/");
+}
+function validateArchiveEntryPath(entryPath) {
+    if (!entryPath || entryPath === "." || entryPath === "./") {
+        return;
+    }
+    if (isWindowsDrivePath(entryPath)) {
+        throw new Error(`archive entry uses a drive path: ${entryPath}`);
+    }
+    const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new Error(`archive entry escapes targetDir: ${entryPath}`);
+    }
+    if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
+        throw new Error(`archive entry is absolute: ${entryPath}`);
+    }
+}
+function stripArchivePath(entryPath, stripComponents) {
+    const raw = normalizeArchiveEntryPath(entryPath);
+    if (!raw || raw === "." || raw === "./") {
+        return null;
+    }
+    // Important: tar's --strip-components semantics operate on raw path segments,
+    // before any normalization that would collapse "..". We mimic that so we
+    // can detect strip-induced escapes like "a/../b" with stripComponents=1.
+    const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
+    const strip = Math.max(0, Math.floor(stripComponents));
+    const stripped = strip === 0 ? parts.join("/") : parts.slice(strip).join("/");
+    const result = path.posix.normalize(stripped);
+    if (!result || result === "." || result === "./") {
+        return null;
+    }
+    return result;
+}
+function validateExtractedPathWithinRoot(params) {
+    const safeBase = resolveSafeBaseDir(params.rootDir);
+    const outPath = path.resolve(params.rootDir, params.relPath);
+    if (!outPath.startsWith(safeBase)) {
+        throw new Error(`archive entry escapes targetDir: ${params.originalPath}`);
+    }
+}
+async function downloadFile(url, destPath, timeoutMs) {
+    const { response, release } = await fetchWithSsrFGuard({
+        url,
+        timeoutMs: Math.max(1_000, timeoutMs),
+    });
+    try {
+        if (!response.ok || !response.body) {
+            throw new Error(`Download failed (${response.status} ${response.statusText})`);
+        }
+        await ensureDir(path.dirname(destPath));
+        const file = fs.createWriteStream(destPath);
+        const body = response.body;
+        const readable = isNodeReadableStream(body)
+            ? body
+            : Readable.fromWeb(body);
+        await pipeline(readable, file);
+        const stat = await fs.promises.stat(destPath);
+        return { bytes: stat.size };
+    }
+    finally {
+        await release();
+    }
+}
+async function extractArchive(params) {
+    const { archivePath, archiveType, targetDir, stripComponents, timeoutMs } = params;
+    const strip = typeof stripComponents === "number" && Number.isFinite(stripComponents)
+        ? Math.max(0, Math.floor(stripComponents))
+        : 0;
+    try {
+        if (archiveType === "zip") {
+            await extractArchiveSafe({
+                archivePath,
+                destDir: targetDir,
+                timeoutMs,
+                kind: "zip",
+                stripComponents: strip,
+            });
+            return { stdout: "", stderr: "", code: 0 };
+        }
+        if (archiveType === "tar.gz") {
+            await extractArchiveSafe({
+                archivePath,
+                destDir: targetDir,
+                timeoutMs,
+                kind: "tar",
+                stripComponents: strip,
+                tarGzip: true,
+            });
+            return { stdout: "", stderr: "", code: 0 };
+        }
+        if (archiveType === "tar.bz2") {
+            if (!hasBinary("tar")) {
+                return { stdout: "", stderr: "tar not found on PATH", code: null };
+            }
+            // Preflight list to prevent zip-slip style traversal before extraction.
+            const listResult = await runCommandWithTimeout(["tar", "tf", archivePath], { timeoutMs });
+            if (listResult.code !== 0) {
+                return {
+                    stdout: listResult.stdout,
+                    stderr: listResult.stderr || "tar list failed",
+                    code: listResult.code,
+                };
+            }
+            const entries = listResult.stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean);
+            const verboseResult = await runCommandWithTimeout(["tar", "tvf", archivePath], { timeoutMs });
+            if (verboseResult.code !== 0) {
+                return {
+                    stdout: verboseResult.stdout,
+                    stderr: verboseResult.stderr || "tar verbose list failed",
+                    code: verboseResult.code,
+                };
+            }
+            for (const line of verboseResult.stdout.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    continue;
+                }
+                const typeChar = trimmed[0];
+                if (typeChar === "l" || typeChar === "h" || trimmed.includes(" -> ")) {
+                    return {
+                        stdout: verboseResult.stdout,
+                        stderr: "tar archive contains link entries; refusing to extract for safety",
+                        code: 1,
+                    };
+                }
+            }
+            for (const entry of entries) {
+                validateArchiveEntryPath(entry);
+                const relPath = stripArchivePath(entry, strip);
+                if (!relPath) {
+                    continue;
+                }
+                validateArchiveEntryPath(relPath);
+                validateExtractedPathWithinRoot({ rootDir: targetDir, relPath, originalPath: entry });
+            }
+            const argv = ["tar", "xf", archivePath, "-C", targetDir];
+            if (strip > 0) {
+                argv.push("--strip-components", String(strip));
+            }
+            return await runCommandWithTimeout(argv, { timeoutMs });
+        }
+        return { stdout: "", stderr: `unsupported archive type: ${archiveType}`, code: null };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { stdout: "", stderr: message, code: 1 };
+    }
+}
+export async function installDownloadSpec(params) {
+    const { entry, spec, timeoutMs } = params;
+    const url = spec.url?.trim();
+    if (!url) {
+        return {
+            ok: false,
+            message: "missing download url",
+            stdout: "",
+            stderr: "",
+            code: null,
+        };
+    }
+    let filename = "";
+    try {
+        const parsed = new URL(url);
+        filename = path.basename(parsed.pathname);
+    }
+    catch {
+        filename = path.basename(url);
+    }
+    if (!filename) {
+        filename = "download";
+    }
+    let targetDir = "";
+    try {
+        targetDir = resolveDownloadTargetDir(entry, spec);
+        await ensureDir(targetDir);
+        const stat = await fs.promises.lstat(targetDir);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`targetDir is a symlink: ${targetDir}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`targetDir is not a directory: ${targetDir}`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, message, stdout: "", stderr: message, code: null };
+    }
+    const archivePath = path.join(targetDir, filename);
+    let downloaded = 0;
+    try {
+        const result = await downloadFile(url, archivePath, timeoutMs);
+        downloaded = result.bytes;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, message, stdout: "", stderr: message, code: null };
+    }
+    const archiveType = resolveArchiveType(spec, filename);
+    const shouldExtract = spec.extract ?? Boolean(archiveType);
+    if (!shouldExtract) {
+        return {
+            ok: true,
+            message: `Downloaded to ${archivePath}`,
+            stdout: `downloaded=${downloaded}`,
+            stderr: "",
+            code: 0,
+        };
+    }
+    if (!archiveType) {
+        return {
+            ok: false,
+            message: "extract requested but archive type could not be detected",
+            stdout: "",
+            stderr: "",
+            code: null,
+        };
+    }
+    const extractResult = await extractArchive({
+        archivePath,
+        archiveType,
+        targetDir,
+        stripComponents: spec.stripComponents,
+        timeoutMs,
+    });
+    const success = extractResult.code === 0;
+    return {
+        ok: success,
+        message: success
+            ? `Downloaded and extracted to ${targetDir}`
+            : formatInstallFailureMessage(extractResult),
+        stdout: extractResult.stdout.trim(),
+        stderr: extractResult.stderr.trim(),
+        code: extractResult.code,
+    };
+}

package/dist/agents/skills-install-output.js

@@ -0,0 +1,30 @@
+function summarizeInstallOutput(text) {
+    const raw = text.trim();
+    if (!raw) {
+        return undefined;
+    }
+    const lines = raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        return undefined;
+    }
+    const preferred = lines.find((line) => /^error\b/i.test(line)) ??
+        lines.find((line) => /\b(err!|error:|failed)\b/i.test(line)) ??
+        lines.at(-1);
+    if (!preferred) {
+        return undefined;
+    }
+    const normalized = preferred.replace(/\s+/g, " ").trim();
+    const maxLen = 200;
+    return normalized.length > maxLen ? `${normalized.slice(0, maxLen - 1)}…` : normalized;
+}
+export function formatInstallFailureMessage(result) {
+    const code = typeof result.code === "number" ? `exit ${result.code}` : "unknown exit";
+    const summary = summarizeInstallOutput(result.stderr) ?? summarizeInstallOutput(result.stdout);
+    if (!summary) {
+        return `Install failed (${code})`;
+    }
+    return `Install failed (${code}): ${summary}`;
+}

package/dist/agents/skills-install.download-test-utils.js

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export function setTempStateDir(workspaceDir) {
+    const stateDir = path.join(workspaceDir, "state");
+    process.env.POOLBOT_STATE_DIR = stateDir;
+    return stateDir;
+}
+export async function writeDownloadSkill(params) {
+    const skillDir = path.join(params.workspaceDir, "skills", params.name);
+    await fs.mkdir(skillDir, { recursive: true });
+    const meta = {
+        openclaw: {
+            install: [
+                {
+                    id: params.installId,
+                    kind: "download",
+                    url: params.url,
+                    archive: params.archive,
+                    extract: true,
+                    stripComponents: params.stripComponents,
+                    targetDir: params.targetDir,
+                },
+            ],
+        },
+    };
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), `---
+name: ${params.name}
+description: test skill
+metadata: ${JSON.stringify(meta)}
+---
+
+# ${params.name}
+`, "utf-8");
+    await fs.writeFile(path.join(skillDir, "runner.js"), "export {};\n", "utf-8");
+    return skillDir;
+}

package/dist/agents/skills.e2e-test-helpers.js

@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function writeSkill(params) {
+    const { dir, name, description, metadata, body } = params;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, "SKILL.md"), `---
+name: ${name}
+description: ${description}${metadata ? `\nmetadata: ${metadata}` : ""}
+---
+
+${body ?? `# ${name}\n`}
+`, "utf-8");
+}