@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/agents/skills/workspace.js

@@ -1,19 +1,43 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { formatSkillsForPrompt, loadSkillsFromDir, } from "@mariozechner/pi-coding-agent";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 import { CONFIG_DIR, resolveUserPath } from "../../utils.js";
+import { resolveSandboxPath } from "../sandbox-paths.js";
 import { resolveBundledSkillsDir } from "./bundled-dir.js";
 import { shouldIncludeSkill } from "./config.js";
+import { normalizeSkillFilter } from "./filter.js";
 import { parseFrontmatter, resolvePoolbotMetadata, resolveSkillInvocationPolicy, } from "./frontmatter.js";
 import { resolvePluginSkillDirs } from "./plugin-skills.js";
 import { serializeByKey } from "./serialize.js";
 const fsp = fs.promises;
 const skillsLogger = createSubsystemLogger("skills");
 const skillCommandDebugOnce = new Set();
+/**
+ * Replace the user's home directory prefix with `~` in skill file paths
+ * to reduce system prompt token usage. Models understand `~` expansion,
+ * and the read tool resolves `~` to the home directory.
+ *
+ * Example: `/Users/alice/.bun/.../skills/github/SKILL.md`
+ *       → `~/.bun/.../skills/github/SKILL.md`
+ *
+ * Saves ~5–6 tokens per skill path × N skills ≈ 400–600 tokens total.
+ */
+function compactSkillPaths(skills) {
+    const home = os.homedir();
+    if (!home)
+        return skills;
+    const prefix = home.endsWith(path.sep) ? home : home + path.sep;
+    return skills.map((s) => ({
+        ...s,
+        filePath: s.filePath.startsWith(prefix) ? "~/" + s.filePath.slice(prefix.length) : s.filePath,
+    }));
+}
 function debugSkillCommandOnce(messageKey, message, meta) {
-    if (skillCommandDebugOnce.has(messageKey))
+    if (skillCommandDebugOnce.has(messageKey)) {
         return;
+    }
     skillCommandDebugOnce.add(messageKey);
     skillsLogger.debug(message, meta);
 }
@@ -21,14 +45,14 @@ function filterSkillEntries(entries, config, skillFilter, eligibility) {
     let filtered = entries.filter((entry) => shouldIncludeSkill({ entry, config, eligibility }));
     // If skillFilter is provided, only include skills in the filter list.
     if (skillFilter !== undefined) {
-        const normalized = skillFilter.map((entry) => String(entry).trim()).filter(Boolean);
+        const normalized = normalizeSkillFilter(skillFilter) ?? [];
         const label = normalized.length > 0 ? normalized.join(", ") : "(none)";
-        console.log(`[skills] Applying skill filter: ${label}`);
+        skillsLogger.debug(`Applying skill filter: ${label}`);
         filtered =
             normalized.length > 0
                 ? filtered.filter((entry) => normalized.includes(entry.skill.name))
                 : [];
-        console.log(`[skills] After filter: ${filtered.map((entry) => entry.skill.name).join(", ")}`);
+        skillsLogger.debug(`After skill filter: ${filtered.map((entry) => entry.skill.name).join(", ") || "(none)"}`);
     }
     return filtered;
 }
@@ -36,6 +60,11 @@ const SKILL_COMMAND_MAX_LENGTH = 32;
 const SKILL_COMMAND_FALLBACK = "skill";
 // Discord command descriptions must be ≤100 characters
 const SKILL_COMMAND_DESCRIPTION_MAX_LENGTH = 100;
+const DEFAULT_MAX_CANDIDATES_PER_ROOT = 300;
+const DEFAULT_MAX_SKILLS_LOADED_PER_SOURCE = 200;
+const DEFAULT_MAX_SKILLS_IN_PROMPT = 150;
+const DEFAULT_MAX_SKILLS_PROMPT_CHARS = 30_000;
+const DEFAULT_MAX_SKILL_FILE_BYTES = 256_000;
 function sanitizeSkillCommandName(raw) {
     const normalized = raw
         .toLowerCase()
@@ -47,35 +76,186 @@ function sanitizeSkillCommandName(raw) {
 }
 function resolveUniqueSkillCommandName(base, used) {
     const normalizedBase = base.toLowerCase();
-    if (!used.has(normalizedBase))
+    if (!used.has(normalizedBase)) {
         return base;
+    }
     for (let index = 2; index < 1000; index += 1) {
         const suffix = `_${index}`;
         const maxBaseLength = Math.max(1, SKILL_COMMAND_MAX_LENGTH - suffix.length);
         const trimmedBase = base.slice(0, maxBaseLength);
         const candidate = `${trimmedBase}${suffix}`;
         const candidateKey = candidate.toLowerCase();
-        if (!used.has(candidateKey))
+        if (!used.has(candidateKey)) {
             return candidate;
+        }
     }
     const fallback = `${base.slice(0, Math.max(1, SKILL_COMMAND_MAX_LENGTH - 2))}_x`;
     return fallback;
 }
+function resolveSkillsLimits(config) {
+    const limits = config?.skills?.limits;
+    return {
+        maxCandidatesPerRoot: limits?.maxCandidatesPerRoot ?? DEFAULT_MAX_CANDIDATES_PER_ROOT,
+        maxSkillsLoadedPerSource: limits?.maxSkillsLoadedPerSource ?? DEFAULT_MAX_SKILLS_LOADED_PER_SOURCE,
+        maxSkillsInPrompt: limits?.maxSkillsInPrompt ?? DEFAULT_MAX_SKILLS_IN_PROMPT,
+        maxSkillsPromptChars: limits?.maxSkillsPromptChars ?? DEFAULT_MAX_SKILLS_PROMPT_CHARS,
+        maxSkillFileBytes: limits?.maxSkillFileBytes ?? DEFAULT_MAX_SKILL_FILE_BYTES,
+    };
+}
+function listChildDirectories(dir) {
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const dirs = [];
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            if (entry.name === "node_modules")
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                dirs.push(entry.name);
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                try {
+                    if (fs.statSync(fullPath).isDirectory()) {
+                        dirs.push(entry.name);
+                    }
+                }
+                catch {
+                    // ignore broken symlinks
+                }
+            }
+        }
+        return dirs;
+    }
+    catch {
+        return [];
+    }
+}
+function resolveNestedSkillsRoot(dir, opts) {
+    const nested = path.join(dir, "skills");
+    try {
+        if (!fs.existsSync(nested) || !fs.statSync(nested).isDirectory()) {
+            return { baseDir: dir };
+        }
+    }
+    catch {
+        return { baseDir: dir };
+    }
+    // Heuristic: if `dir/skills/*/SKILL.md` exists for any entry, treat `dir/skills` as the real root.
+    // Note: don't stop at 25, but keep a cap to avoid pathological scans.
+    const nestedDirs = listChildDirectories(nested);
+    const scanLimit = Math.max(0, opts?.maxEntriesToScan ?? 100);
+    const toScan = scanLimit === 0 ? [] : nestedDirs.slice(0, Math.min(nestedDirs.length, scanLimit));
+    for (const name of toScan) {
+        const skillMd = path.join(nested, name, "SKILL.md");
+        if (fs.existsSync(skillMd)) {
+            return { baseDir: nested, note: `Detected nested skills root at ${nested}` };
+        }
+    }
+    return { baseDir: dir };
+}
+function unwrapLoadedSkills(loaded) {
+    if (Array.isArray(loaded)) {
+        return loaded;
+    }
+    if (loaded && typeof loaded === "object" && "skills" in loaded) {
+        const skills = loaded.skills;
+        if (Array.isArray(skills)) {
+            return skills;
+        }
+    }
+    return [];
+}
 function loadSkillEntries(workspaceDir, opts) {
+    const limits = resolveSkillsLimits(opts?.config);
     const loadSkills = (params) => {
-        const loaded = loadSkillsFromDir(params);
-        if (Array.isArray(loaded))
-            return loaded;
-        if (loaded &&
-            typeof loaded === "object" &&
-            "skills" in loaded &&
-            Array.isArray(loaded.skills)) {
-            return loaded.skills;
+        const resolved = resolveNestedSkillsRoot(params.dir, {
+            maxEntriesToScan: limits.maxCandidatesPerRoot,
+        });
+        const baseDir = resolved.baseDir;
+        // If the root itself is a skill directory, just load it directly (but enforce size cap).
+        const rootSkillMd = path.join(baseDir, "SKILL.md");
+        if (fs.existsSync(rootSkillMd)) {
+            try {
+                const size = fs.statSync(rootSkillMd).size;
+                if (size > limits.maxSkillFileBytes) {
+                    skillsLogger.warn("Skipping skills root due to oversized SKILL.md.", {
+                        dir: baseDir,
+                        filePath: rootSkillMd,
+                        size,
+                        maxSkillFileBytes: limits.maxSkillFileBytes,
+                    });
+                    return [];
+                }
+            }
+            catch {
+                return [];
+            }
+            const loaded = loadSkillsFromDir({ dir: baseDir, source: params.source });
+            return unwrapLoadedSkills(loaded);
         }
-        return [];
+        const childDirs = listChildDirectories(baseDir);
+        const suspicious = childDirs.length > limits.maxCandidatesPerRoot;
+        const maxCandidates = Math.max(0, limits.maxSkillsLoadedPerSource);
+        const limitedChildren = childDirs.slice().sort().slice(0, maxCandidates);
+        if (suspicious) {
+            skillsLogger.warn("Skills root looks suspiciously large, truncating discovery.", {
+                dir: params.dir,
+                baseDir,
+                childDirCount: childDirs.length,
+                maxCandidatesPerRoot: limits.maxCandidatesPerRoot,
+                maxSkillsLoadedPerSource: limits.maxSkillsLoadedPerSource,
+            });
+        }
+        else if (childDirs.length > maxCandidates) {
+            skillsLogger.warn("Skills root has many entries, truncating discovery.", {
+                dir: params.dir,
+                baseDir,
+                childDirCount: childDirs.length,
+                maxSkillsLoadedPerSource: limits.maxSkillsLoadedPerSource,
+            });
+        }
+        const loadedSkills = [];
+        // Only consider immediate subfolders that look like skills (have SKILL.md) and are under size cap.
+        for (const name of limitedChildren) {
+            const skillDir = path.join(baseDir, name);
+            const skillMd = path.join(skillDir, "SKILL.md");
+            if (!fs.existsSync(skillMd)) {
+                continue;
+            }
+            try {
+                const size = fs.statSync(skillMd).size;
+                if (size > limits.maxSkillFileBytes) {
+                    skillsLogger.warn("Skipping skill due to oversized SKILL.md.", {
+                        skill: name,
+                        filePath: skillMd,
+                        size,
+                        maxSkillFileBytes: limits.maxSkillFileBytes,
+                    });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            const loaded = loadSkillsFromDir({ dir: skillDir, source: params.source });
+            loadedSkills.push(...unwrapLoadedSkills(loaded));
+            if (loadedSkills.length >= limits.maxSkillsLoadedPerSource) {
+                break;
+            }
+        }
+        if (loadedSkills.length > limits.maxSkillsLoadedPerSource) {
+            return loadedSkills
+                .slice()
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(0, limits.maxSkillsLoadedPerSource);
+        }
+        return loadedSkills;
     };
     const managedSkillsDir = opts?.managedSkillsDir ?? path.join(CONFIG_DIR, "skills");
-    const workspaceSkillsDir = path.join(workspaceDir, "skills");
+    const workspaceSkillsDir = path.resolve(workspaceDir, "skills");
     const bundledSkillsDir = opts?.bundledSkillsDir ?? resolveBundledSkillsDir();
     const extraDirsRaw = opts?.config?.skills?.load?.extraDirs ?? [];
     const extraDirs = extraDirsRaw
@@ -103,20 +283,40 @@ function loadSkillEntries(workspaceDir, opts) {
         dir: managedSkillsDir,
         source: "poolbot-managed",
     });
+    const personalAgentsSkillsDir = path.resolve(os.homedir(), ".agents", "skills");
+    const personalAgentsSkills = loadSkills({
+        dir: personalAgentsSkillsDir,
+        source: "agents-skills-personal",
+    });
+    const projectAgentsSkillsDir = path.resolve(workspaceDir, ".agents", "skills");
+    const projectAgentsSkills = loadSkills({
+        dir: projectAgentsSkillsDir,
+        source: "agents-skills-project",
+    });
     const workspaceSkills = loadSkills({
         dir: workspaceSkillsDir,
         source: "poolbot-workspace",
     });
     const merged = new Map();
-    // Precedence: extra < bundled < managed < workspace
-    for (const skill of extraSkills)
+    // Precedence: extra < bundled < managed < agents-skills-personal < agents-skills-project < workspace
+    for (const skill of extraSkills) {
         merged.set(skill.name, skill);
-    for (const skill of bundledSkills)
+    }
+    for (const skill of bundledSkills) {
         merged.set(skill.name, skill);
-    for (const skill of managedSkills)
+    }
+    for (const skill of managedSkills) {
+        merged.set(skill.name, skill);
+    }
+    for (const skill of personalAgentsSkills) {
         merged.set(skill.name, skill);
-    for (const skill of workspaceSkills)
+    }
+    for (const skill of projectAgentsSkills) {
+        merged.set(skill.name, skill);
+    }
+    for (const skill of workspaceSkills) {
         merged.set(skill.name, skill);
+    }
     const skillEntries = Array.from(merged.values()).map((skill) => {
         let frontmatter = {};
         try {
@@ -135,19 +335,64 @@ function loadSkillEntries(workspaceDir, opts) {
     });
     return skillEntries;
 }
+function applySkillsPromptLimits(params) {
+    const limits = resolveSkillsLimits(params.config);
+    const total = params.skills.length;
+    const byCount = params.skills.slice(0, Math.max(0, limits.maxSkillsInPrompt));
+    let skillsForPrompt = byCount;
+    let truncated = total > byCount.length;
+    let truncatedReason = truncated ? "count" : null;
+    const fits = (skills) => {
+        const block = formatSkillsForPrompt(skills);
+        return block.length <= limits.maxSkillsPromptChars;
+    };
+    if (!fits(skillsForPrompt)) {
+        // Binary search the largest prefix that fits in the char budget.
+        let lo = 0;
+        let hi = skillsForPrompt.length;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            if (fits(skillsForPrompt.slice(0, mid))) {
+                lo = mid;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        skillsForPrompt = skillsForPrompt.slice(0, lo);
+        truncated = true;
+        truncatedReason = "chars";
+    }
+    return { skillsForPrompt, truncated, truncatedReason };
+}
 export function buildWorkspaceSkillSnapshot(workspaceDir, opts) {
     const skillEntries = opts?.entries ?? loadSkillEntries(workspaceDir, opts);
     const eligible = filterSkillEntries(skillEntries, opts?.config, opts?.skillFilter, opts?.eligibility);
     const promptEntries = eligible.filter((entry) => entry.invocation?.disableModelInvocation !== true);
     const resolvedSkills = promptEntries.map((entry) => entry.skill);
     const remoteNote = opts?.eligibility?.remote?.note?.trim();
-    const prompt = [remoteNote, formatSkillsForPrompt(resolvedSkills)].filter(Boolean).join("\n");
+    const { skillsForPrompt, truncated } = applySkillsPromptLimits({
+        skills: resolvedSkills,
+        config: opts?.config,
+    });
+    const truncationNote = truncated
+        ? `⚠️ Skills truncated: included ${skillsForPrompt.length} of ${resolvedSkills.length}. Run \`poolbot skills check\` to audit.`
+        : "";
+    const prompt = [
+        remoteNote,
+        truncationNote,
+        formatSkillsForPrompt(compactSkillPaths(skillsForPrompt)),
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const skillFilter = normalizeSkillFilter(opts?.skillFilter);
     return {
         prompt,
         skills: eligible.map((entry) => ({
             name: entry.skill.name,
             primaryEnv: entry.metadata?.primaryEnv,
         })),
+        ...(skillFilter === undefined ? {} : { skillFilter }),
         resolvedSkills,
         version: opts?.snapshotVersion,
     };
@@ -157,14 +402,23 @@ export function buildWorkspaceSkillsPrompt(workspaceDir, opts) {
     const eligible = filterSkillEntries(skillEntries, opts?.config, opts?.skillFilter, opts?.eligibility);
     const promptEntries = eligible.filter((entry) => entry.invocation?.disableModelInvocation !== true);
     const remoteNote = opts?.eligibility?.remote?.note?.trim();
-    return [remoteNote, formatSkillsForPrompt(promptEntries.map((entry) => entry.skill))]
+    const resolvedSkills = promptEntries.map((entry) => entry.skill);
+    const { skillsForPrompt, truncated } = applySkillsPromptLimits({
+        skills: resolvedSkills,
+        config: opts?.config,
+    });
+    const truncationNote = truncated
+        ? `⚠️ Skills truncated: included ${skillsForPrompt.length} of ${resolvedSkills.length}. Run \`poolbot skills check\` to audit.`
+        : "";
+    return [remoteNote, truncationNote, formatSkillsForPrompt(compactSkillPaths(skillsForPrompt))]
         .filter(Boolean)
         .join("\n");
 }
 export function resolveSkillsPromptForRun(params) {
     const snapshotPrompt = params.skillsSnapshot?.prompt?.trim();
-    if (snapshotPrompt)
+    if (snapshotPrompt) {
         return snapshotPrompt;
+    }
     if (params.entries && params.entries.length > 0) {
         const prompt = buildWorkspaceSkillsPrompt(params.workspaceDir, {
             entries: params.entries,
@@ -177,11 +431,45 @@ export function resolveSkillsPromptForRun(params) {
 export function loadWorkspaceSkillEntries(workspaceDir, opts) {
     return loadSkillEntries(workspaceDir, opts);
 }
+function resolveUniqueSyncedSkillDirName(base, used) {
+    if (!used.has(base)) {
+        used.add(base);
+        return base;
+    }
+    for (let index = 2; index < 10_000; index += 1) {
+        const candidate = `${base}-${index}`;
+        if (!used.has(candidate)) {
+            used.add(candidate);
+            return candidate;
+        }
+    }
+    let fallbackIndex = 10_000;
+    let fallback = `${base}-${fallbackIndex}`;
+    while (used.has(fallback)) {
+        fallbackIndex += 1;
+        fallback = `${base}-${fallbackIndex}`;
+    }
+    used.add(fallback);
+    return fallback;
+}
+function resolveSyncedSkillDestinationPath(params) {
+    const sourceDirName = path.basename(params.entry.skill.baseDir).trim();
+    if (!sourceDirName || sourceDirName === "." || sourceDirName === "..") {
+        return null;
+    }
+    const uniqueDirName = resolveUniqueSyncedSkillDirName(sourceDirName, params.usedDirNames);
+    return resolveSandboxPath({
+        filePath: uniqueDirName,
+        cwd: params.targetSkillsDir,
+        root: params.targetSkillsDir,
+    }).resolved;
+}
 export async function syncSkillsToWorkspace(params) {
     const sourceDir = resolveUserPath(params.sourceWorkspaceDir);
     const targetDir = resolveUserPath(params.targetWorkspaceDir);
-    if (sourceDir === targetDir)
+    if (sourceDir === targetDir) {
         return;
+    }
     await serializeByKey(`syncSkills:${targetDir}`, async () => {
         const targetSkillsDir = path.join(targetDir, "skills");
         const entries = loadSkillEntries(sourceDir, {
@@ -191,8 +479,25 @@ export async function syncSkillsToWorkspace(params) {
         });
         await fsp.rm(targetSkillsDir, { recursive: true, force: true });
         await fsp.mkdir(targetSkillsDir, { recursive: true });
+        const usedDirNames = new Set();
         for (const entry of entries) {
-            const dest = path.join(targetSkillsDir, entry.skill.name);
+            let dest = null;
+            try {
+                dest = resolveSyncedSkillDestinationPath({
+                    targetSkillsDir,
+                    entry,
+                    usedDirNames,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : JSON.stringify(error);
+                console.warn(`[skills] Failed to resolve safe destination for ${entry.skill.name}: ${message}`);
+                continue;
+            }
+            if (!dest) {
+                console.warn(`[skills] Failed to resolve safe destination for ${entry.skill.name}: invalid source directory name`);
+                continue;
+            }
             try {
                 await fsp.cp(entry.skill.baseDir, dest, {
                     recursive: true,
@@ -239,10 +544,12 @@ export function buildWorkspaceSkillCommandSpecs(workspaceDir, opts) {
                 "")
                 .trim()
                 .toLowerCase();
-            if (!kindRaw)
+            if (!kindRaw) {
                 return undefined;
-            if (kindRaw !== "tool")
+            }
+            if (kindRaw !== "tool") {
                 return undefined;
+            }
             const toolName = (entry.frontmatter?.["command-tool"] ??
                 entry.frontmatter?.["command_tool"] ??
                 "").trim();