@poolzin/pool-bot 2026.3.7 → 2026.3.9

package/dist/skills/loader.js

@@ -0,0 +1,282 @@
+/**
+ * Progressive disclosure loader for skills
+ * Loads skills at different levels of detail
+ *
+ * @module skills/loader
+ */
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { SkillError, } from "./types.js";
+// ============================================================================
+// Token Estimation
+// ============================================================================
+/**
+ * Rough token estimation (4 chars ≈ 1 token for English text)
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ============================================================================
+// Progressive Disclosure Loader
+// ============================================================================
+export class SkillLoader {
+    /**
+     * Load skill content at specified disclosure level
+     */
+    async loadSkill(skill, level = "full") {
+        switch (level) {
+            case "metadata":
+                return this.loadMetadataOnly(skill);
+            case "summary":
+                return this.loadSummary(skill);
+            case "full":
+                return this.loadFull(skill);
+            default:
+                throw new SkillError("LOAD_ERROR", `Unknown disclosure level: ${level}`, skill.metadata.id);
+        }
+    }
+    /**
+     * Load minimal metadata (no content)
+     */
+    loadMetadataOnly(skill) {
+        return {
+            usage: skill.metadata.description,
+        };
+    }
+    /**
+     * Load summary (quickstart + usage overview)
+     */
+    loadSummary(skill) {
+        return {
+            quickstart: skill.content.quickstart,
+            usage: skill.content.usage.slice(0, 2000), // First 2000 chars
+        };
+    }
+    /**
+     * Load full content
+     */
+    loadFull(skill) {
+        return { ...skill.content };
+    }
+    /**
+     * Load linked file content
+     */
+    async loadLinkedFile(skill, filePath) {
+        const linkedFile = skill.linkedFiles.find((f) => f.path === filePath);
+        if (!linkedFile) {
+            throw new SkillError("LOAD_ERROR", `Linked file not found: ${filePath}`, skill.metadata.id);
+        }
+        const fullPath = join(dirname(skill.sourcePath.toString()), filePath);
+        try {
+            const content = await readFile(fullPath, "utf-8");
+            return {
+                ...linkedFile,
+                content,
+            };
+        }
+        catch (error) {
+            throw new SkillError("LOAD_ERROR", `Failed to load linked file: ${error}`, skill.metadata.id, error);
+        }
+    }
+    /**
+     * Load all linked files for a skill
+     */
+    async loadAllLinkedFiles(skill) {
+        const results = [];
+        for (const linkedFile of skill.linkedFiles) {
+            try {
+                const loaded = await this.loadLinkedFile(skill, linkedFile.path);
+                results.push(loaded);
+            }
+            catch (error) {
+                // Skip files that fail to load
+                if (linkedFile.required) {
+                    throw error;
+                }
+            }
+        }
+        return results;
+    }
+    // ========================================================================
+    // Context Engine Integration
+    // ========================================================================
+    /**
+     * Prepare skill content for context injection
+     * Respects token limits and disclosure levels
+     */
+    async prepareForContext(skill, config) {
+        const sections = [];
+        let content = "";
+        let currentTokens = 0;
+        // Load content at appropriate level
+        const skillContent = await this.loadSkill(skill, config.disclosureLevel);
+        // Add header
+        const header = `## Skill: ${skill.metadata.name}\n\n`;
+        content += header;
+        currentTokens += estimateTokens(header);
+        // Add sections in priority order
+        const sectionsToAdd = [
+            { name: "quickstart", content: skillContent.quickstart },
+            { name: "usage", content: skillContent.usage },
+            { name: "examples", content: skillContent.examples },
+            { name: "configuration", content: skillContent.configuration },
+            { name: "api", content: skillContent.api },
+        ];
+        for (const section of sectionsToAdd) {
+            if (!section.content)
+                continue;
+            const sectionHeader = `### ${section.name}\n\n`;
+            const sectionTokens = estimateTokens(sectionHeader + section.content);
+            if (currentTokens + sectionTokens > config.maxTokens) {
+                // Add truncated notice if we're out of tokens
+                if (currentTokens < config.maxTokens - 50) {
+                    const notice = "\n*[Content truncated due to token limits]*\n";
+                    content += notice;
+                }
+                break;
+            }
+            content += sectionHeader + section.content + "\n\n";
+            currentTokens += sectionTokens;
+            sections.push(section.name);
+        }
+        // Add linked files if requested and we have room
+        if (config.includeLinkedFiles && skill.linkedFiles.length > 0) {
+            const linkedHeader = "### Linked Files\n\n";
+            const linkedTokens = estimateTokens(linkedHeader);
+            if (currentTokens + linkedTokens < config.maxTokens) {
+                content += linkedHeader;
+                currentTokens += linkedTokens;
+                for (const linkedFile of skill.linkedFiles) {
+                    try {
+                        const loaded = await this.loadLinkedFile(skill, linkedFile.path);
+                        const fileContent = `**${linkedFile.path}**:\n\n\`\`\`\n${loaded.content.slice(0, 500)}\n\`\`\`\n\n`;
+                        const fileTokens = estimateTokens(fileContent);
+                        if (currentTokens + fileTokens < config.maxTokens) {
+                            content += fileContent;
+                            currentTokens += fileTokens;
+                            sections.push(`linked:${linkedFile.path}`);
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    catch {
+                        // Skip files that fail to load
+                    }
+                }
+            }
+        }
+        return {
+            skillId: skill.metadata.id,
+            content,
+            tokenCount: currentTokens,
+            sections,
+        };
+    }
+    /**
+     * Prepare multiple skills for context
+     */
+    async prepareMultipleForContext(skills, config) {
+        const results = [];
+        let remainingTokens = config.maxTokens;
+        for (const skill of skills) {
+            const skillConfig = {
+                ...config,
+                maxTokens: Math.floor(remainingTokens / (skills.length - results.length)),
+            };
+            try {
+                const prepared = await this.prepareForContext(skill, skillConfig);
+                results.push(prepared);
+                remainingTokens -= prepared.tokenCount;
+            }
+            catch (error) {
+                // Log error but continue with other skills
+                console.warn(`Failed to prepare skill ${skill.metadata.id} for context:`, error);
+            }
+        }
+        return results;
+    }
+    // ========================================================================
+    // Smart Loading
+    // ========================================================================
+    /**
+     * Intelligently load skill based on query context
+     */
+    async loadForQuery(skill, query) {
+        const queryLower = query.toLowerCase();
+        // Check if query matches specific sections
+        if (queryLower.includes("config") ||
+            queryLower.includes("setup") ||
+            queryLower.includes("env")) {
+            return {
+                usage: skill.content.usage,
+                quickstart: skill.content.quickstart,
+                examples: skill.content.examples,
+                configuration: skill.content.configuration,
+                environment: skill.content.environment,
+                api: skill.content.api,
+                troubleshooting: skill.content.troubleshooting,
+            };
+        }
+        if (queryLower.includes("example") ||
+            queryLower.includes("demo") ||
+            queryLower.includes("how to")) {
+            return {
+                usage: skill.content.usage,
+                quickstart: skill.content.quickstart,
+                examples: skill.content.examples,
+                configuration: skill.content.configuration,
+                environment: skill.content.environment,
+                api: skill.content.api,
+                troubleshooting: skill.content.troubleshooting,
+            };
+        }
+        if (queryLower.includes("api") ||
+            queryLower.includes("reference") ||
+            queryLower.includes("function")) {
+            return {
+                usage: skill.content.usage,
+                quickstart: skill.content.quickstart,
+                examples: skill.content.examples,
+                configuration: skill.content.configuration,
+                environment: skill.content.environment,
+                api: skill.content.api,
+                troubleshooting: skill.content.troubleshooting,
+            };
+        }
+        if (queryLower.includes("troubleshoot") ||
+            queryLower.includes("error") ||
+            queryLower.includes("fix")) {
+            return {
+                usage: skill.content.usage,
+                quickstart: skill.content.quickstart,
+                examples: skill.content.examples,
+                configuration: skill.content.configuration,
+                environment: skill.content.environment,
+                api: skill.content.api,
+                troubleshooting: skill.content.troubleshooting,
+            };
+        }
+        // Default to summary
+        return this.loadSummary(skill);
+    }
+}
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+let globalLoader = null;
+/**
+ * Get or create global loader instance
+ */
+export function getLoader() {
+    if (!globalLoader) {
+        globalLoader = new SkillLoader();
+    }
+    return globalLoader;
+}
+/**
+ * Reset global loader
+ */
+export function resetLoader() {
+    globalLoader = null;
+}