@poolzin/pool-bot 2026.2.11 → 2026.2.18

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

package/dist/agents/subagent-announce-queue.js

@@ -2,6 +2,31 @@ import { defaultRuntime } from "../runtime.js";
 import { deliveryContextKey, normalizeDeliveryContext, } from "../utils/delivery-context.js";
 import { applyQueueDropPolicy, buildCollectPrompt, buildQueueSummaryPrompt, hasCrossChannelItems, waitForQueueDebounce, } from "../utils/queue-helpers.js";
 const ANNOUNCE_QUEUES = new Map();
+function previewQueueSummaryPrompt(queue) {
+    return buildQueueSummaryPrompt({
+        state: {
+            dropPolicy: queue.dropPolicy,
+            droppedCount: queue.droppedCount,
+            summaryLines: [...queue.summaryLines],
+        },
+        noun: "announce",
+    });
+}
+function clearQueueSummaryState(queue) {
+    queue.droppedCount = 0;
+    queue.summaryLines = [];
+}
+export function resetAnnounceQueuesForTests() {
+    // Test isolation: other suites may leave a draining queue behind in the worker.
+    // Clearing the map alone isn't enough because drain loops capture `queue` by reference.
+    for (const queue of ANNOUNCE_QUEUES.values()) {
+        queue.items.length = 0;
+        queue.summaryLines.length = 0;
+        queue.droppedCount = 0;
+        queue.lastEnqueuedAt = 0;
+    }
+    ANNOUNCE_QUEUES.clear();
+}
 function getAnnounceQueue(key, settings, send) {
     const existing = ANNOUNCE_QUEUES.get(key);
     if (existing) {
@@ -35,8 +60,9 @@ function getAnnounceQueue(key, settings, send) {
 }
 function scheduleAnnounceDrain(key) {
     const queue = ANNOUNCE_QUEUES.get(key);
-    if (!queue || queue.draining)
+    if (!queue || queue.draining) {
         return;
+    }
     queue.draining = true;
     void (async () => {
         try {
@@ -45,29 +71,35 @@ function scheduleAnnounceDrain(key) {
                 await waitForQueueDebounce(queue);
                 if (queue.mode === "collect") {
                     if (forceIndividualCollect) {
-                        const next = queue.items.shift();
-                        if (!next)
+                        const next = queue.items[0];
+                        if (!next) {
                             break;
+                        }
                         await queue.send(next);
+                        queue.items.shift();
                         continue;
                     }
                     const isCrossChannel = hasCrossChannelItems(queue.items, (item) => {
-                        if (!item.origin)
+                        if (!item.origin) {
                             return {};
-                        if (!item.originKey)
+                        }
+                        if (!item.originKey) {
                             return { cross: true };
+                        }
                         return { key: item.originKey };
                     });
                     if (isCrossChannel) {
                         forceIndividualCollect = true;
-                        const next = queue.items.shift();
-                        if (!next)
+                        const next = queue.items[0];
+                        if (!next) {
                             break;
+                        }
                         await queue.send(next);
+                        queue.items.shift();
                         continue;
                     }
-                    const items = queue.items.splice(0, queue.items.length);
-                    const summary = buildQueueSummaryPrompt({ state: queue, noun: "announce" });
+                    const items = queue.items.slice();
+                    const summary = previewQueueSummaryPrompt(queue);
                     const prompt = buildCollectPrompt({
                         title: "[Queued announce messages while agent was busy]",
                         items,
@@ -75,26 +107,38 @@ function scheduleAnnounceDrain(key) {
                         renderItem: (item, idx) => `---\nQueued #${idx + 1}\n${item.prompt}`.trim(),
                     });
                     const last = items.at(-1);
-                    if (!last)
+                    if (!last) {
                         break;
+                    }
                     await queue.send({ ...last, prompt });
+                    queue.items.splice(0, items.length);
+                    if (summary) {
+                        clearQueueSummaryState(queue);
+                    }
                     continue;
                 }
-                const summaryPrompt = buildQueueSummaryPrompt({ state: queue, noun: "announce" });
+                const summaryPrompt = previewQueueSummaryPrompt(queue);
                 if (summaryPrompt) {
-                    const next = queue.items.shift();
-                    if (!next)
+                    const next = queue.items[0];
+                    if (!next) {
                         break;
+                    }
                     await queue.send({ ...next, prompt: summaryPrompt });
+                    queue.items.shift();
+                    clearQueueSummaryState(queue);
                     continue;
                 }
-                const next = queue.items.shift();
-                if (!next)
+                const next = queue.items[0];
+                if (!next) {
                     break;
+                }
                 await queue.send(next);
+                queue.items.shift();
             }
         }
         catch (err) {
+            // Keep items in queue and retry after debounce; avoid hot-loop retries.
+            queue.lastEnqueuedAt = Date.now();
             defaultRuntime.error?.(`announce queue drain failed for ${key}: ${String(err)}`);
         }
         finally {

package/dist/agents/subagent-depth.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import JSON5 from "json5";
+import { resolveStorePath } from "../config/sessions/paths.js";
+import { getSubagentDepth, parseAgentSessionKey } from "../sessions/session-key-utils.js";
+import { resolveDefaultAgentId } from "./agent-scope.js";
+function normalizeSpawnDepth(value) {
+    if (typeof value === "number") {
+        return Number.isInteger(value) && value >= 0 ? value : undefined;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        const numeric = Number(trimmed);
+        return Number.isInteger(numeric) && numeric >= 0 ? numeric : undefined;
+    }
+    return undefined;
+}
+function normalizeSessionKey(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function readSessionStore(storePath) {
+    try {
+        const raw = fs.readFileSync(storePath, "utf-8");
+        const parsed = JSON5.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // ignore missing/invalid stores
+    }
+    return {};
+}
+function buildKeyCandidates(rawKey, cfg) {
+    if (!cfg) {
+        return [rawKey];
+    }
+    if (rawKey === "global" || rawKey === "unknown") {
+        return [rawKey];
+    }
+    if (parseAgentSessionKey(rawKey)) {
+        return [rawKey];
+    }
+    const defaultAgentId = resolveDefaultAgentId(cfg);
+    const prefixed = `agent:${defaultAgentId}:${rawKey}`;
+    return prefixed === rawKey ? [rawKey] : [rawKey, prefixed];
+}
+function findEntryBySessionId(store, sessionId) {
+    const normalizedSessionId = normalizeSessionKey(sessionId);
+    if (!normalizedSessionId) {
+        return undefined;
+    }
+    for (const entry of Object.values(store)) {
+        const candidateSessionId = normalizeSessionKey(entry?.sessionId);
+        if (candidateSessionId && candidateSessionId === normalizedSessionId) {
+            return entry;
+        }
+    }
+    return undefined;
+}
+function resolveEntryForSessionKey(params) {
+    const candidates = buildKeyCandidates(params.sessionKey, params.cfg);
+    if (params.store) {
+        for (const key of candidates) {
+            const entry = params.store[key];
+            if (entry) {
+                return entry;
+            }
+        }
+        return findEntryBySessionId(params.store, params.sessionKey);
+    }
+    if (!params.cfg) {
+        return undefined;
+    }
+    for (const key of candidates) {
+        const parsed = parseAgentSessionKey(key);
+        if (!parsed?.agentId) {
+            continue;
+        }
+        const storePath = resolveStorePath(params.cfg.session?.store, { agentId: parsed.agentId });
+        let store = params.cache.get(storePath);
+        if (!store) {
+            store = readSessionStore(storePath);
+            params.cache.set(storePath, store);
+        }
+        const entry = store[key] ?? findEntryBySessionId(store, params.sessionKey);
+        if (entry) {
+            return entry;
+        }
+    }
+    return undefined;
+}
+export function getSubagentDepthFromSessionStore(sessionKey, opts) {
+    const raw = (sessionKey ?? "").trim();
+    const fallbackDepth = getSubagentDepth(raw);
+    if (!raw) {
+        return fallbackDepth;
+    }
+    const cache = new Map();
+    const visited = new Set();
+    const depthFromStore = (key) => {
+        const normalizedKey = normalizeSessionKey(key);
+        if (!normalizedKey) {
+            return undefined;
+        }
+        if (visited.has(normalizedKey)) {
+            return undefined;
+        }
+        visited.add(normalizedKey);
+        const entry = resolveEntryForSessionKey({
+            sessionKey: normalizedKey,
+            cfg: opts?.cfg,
+            store: opts?.store,
+            cache,
+        });
+        const storedDepth = normalizeSpawnDepth(entry?.spawnDepth);
+        if (storedDepth !== undefined) {
+            return storedDepth;
+        }
+        const spawnedBy = normalizeSessionKey(entry?.spawnedBy);
+        if (!spawnedBy) {
+            return undefined;
+        }
+        const parentDepth = depthFromStore(spawnedBy);
+        if (parentDepth !== undefined) {
+            return parentDepth + 1;
+        }
+        return getSubagentDepth(spawnedBy) + 1;
+    };
+    return depthFromStore(raw) ?? fallbackDepth;
+}