@elizaos/agent 2.0.0-alpha.173 → 2.0.0-alpha.192

package/packages/skills/src/loader.js

@@ -0,0 +1,369 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, resolveSkillProvenance, } from "./frontmatter.js";
+import { getCuratedActiveDir, getSkillsDir } from "./resolver.js";
+/** Maximum skill name length per Agent Skills spec */
+const MAX_NAME_LENGTH = 64;
+/** Maximum description length per Agent Skills spec */
+const MAX_DESCRIPTION_LENGTH = 1024;
+/** Default config directory name */
+const CONFIG_DIR_NAME = ".elizaos";
+/** Default agent directory for user skills */
+const DEFAULT_AGENT_DIR = join(homedir(), CONFIG_DIR_NAME);
+/**
+ * Validate skill name per Agent Skills spec.
+ * Returns array of validation error messages (empty if valid).
+ *
+ * @param name - The skill name to validate
+ * @param parentDirName - The parent directory name (should match)
+ * @returns Array of validation error messages
+ */
+function validateName(name, parentDirName) {
+    const errors = [];
+    if (name !== parentDirName) {
+        errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        errors.push(`name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
+    }
+    if (name.startsWith("-") || name.endsWith("-")) {
+        errors.push(`name must not start or end with a hyphen`);
+    }
+    if (name.includes("--")) {
+        errors.push(`name must not contain consecutive hyphens`);
+    }
+    return errors;
+}
+/**
+ * Validate description per Agent Skills spec.
+ *
+ * @param description - The skill description to validate
+ * @returns Array of validation error messages
+ */
+function validateDescription(description) {
+    const errors = [];
+    if (!description || description.trim() === "") {
+        errors.push("description is required");
+    }
+    else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+/**
+ * Load a single skill from a SKILL.md file
+ *
+ * @param filePath - Absolute path to the SKILL.md file
+ * @param source - Source identifier for this skill
+ * @returns Loaded skill and diagnostics
+ */
+function loadSkillFromFile(filePath, source) {
+    const diagnostics = [];
+    const rawContent = readFileSync(filePath, "utf-8");
+    const { frontmatter } = parseFrontmatter(rawContent);
+    const skillDir = dirname(filePath);
+    const parentDirName = basename(skillDir);
+    // Validate description
+    const descErrors = validateDescription(frontmatter.description);
+    for (const error of descErrors) {
+        diagnostics.push({ type: "warning", message: error, path: filePath });
+    }
+    // Use name from frontmatter, or fall back to parent directory name
+    const name = frontmatter.name || parentDirName;
+    // Validate name
+    const nameErrors = validateName(name, parentDirName);
+    for (const error of nameErrors) {
+        diagnostics.push({ type: "warning", message: error, path: filePath });
+    }
+    // Don't load the skill if description is completely missing
+    if (!frontmatter.description || frontmatter.description.trim() === "") {
+        return { skill: null, diagnostics };
+    }
+    const provenance = resolveSkillProvenance(frontmatter);
+    return {
+        skill: {
+            name,
+            description: frontmatter.description,
+            filePath,
+            baseDir: skillDir,
+            source,
+            disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+            ...(provenance ? { provenance } : {}),
+        },
+        diagnostics,
+    };
+}
+/**
+ * Internal recursive skill loader
+ *
+ * @param dir - Directory to scan
+ * @param source - Source identifier
+ * @param includeRootFiles - Whether to include .md files at root level
+ * @returns Loaded skills and diagnostics
+ */
+function loadSkillsFromDirInternal(dir, source, includeRootFiles) {
+    const skills = [];
+    const diagnostics = [];
+    if (!existsSync(dir)) {
+        return { skills, diagnostics };
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Skip hidden files and directories
+        if (entry.name.startsWith(".")) {
+            continue;
+        }
+        // Skip node_modules to avoid scanning dependencies
+        if (entry.name === "node_modules") {
+            continue;
+        }
+        const fullPath = join(dir, entry.name);
+        // For symlinks, check if they point to a directory and follow them
+        let isDirectory = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            const stats = statSync(fullPath);
+            isDirectory = stats.isDirectory();
+            isFile = stats.isFile();
+        }
+        if (isDirectory) {
+            const subResult = loadSkillsFromDirInternal(fullPath, source, false);
+            skills.push(...subResult.skills);
+            diagnostics.push(...subResult.diagnostics);
+            continue;
+        }
+        if (!isFile) {
+            continue;
+        }
+        const isRootMd = includeRootFiles && entry.name.endsWith(".md");
+        const isSkillMd = !includeRootFiles && entry.name === "SKILL.md";
+        if (!isRootMd && !isSkillMd) {
+            continue;
+        }
+        const result = loadSkillFromFile(fullPath, source);
+        if (result.skill) {
+            skills.push(result.skill);
+        }
+        diagnostics.push(...result.diagnostics);
+    }
+    return { skills, diagnostics };
+}
+/**
+ * Load skills from a single directory.
+ *
+ * Discovery rules:
+ * - Direct .md children in the root
+ * - Recursive SKILL.md under subdirectories
+ *
+ * @param options - Loading options
+ * @returns Loaded skills and diagnostics
+ */
+export function loadSkillsFromDir(options) {
+    const { dir, source } = options;
+    return loadSkillsFromDirInternal(dir, source, true);
+}
+/**
+ * Normalize a path, expanding ~ to home directory
+ *
+ * @param input - Path that may contain ~
+ * @returns Normalized absolute path
+ */
+function normalizePath(input) {
+    const trimmed = input.trim();
+    if (trimmed === "~")
+        return homedir();
+    if (trimmed.startsWith("~/"))
+        return join(homedir(), trimmed.slice(2));
+    if (trimmed.startsWith("~"))
+        return join(homedir(), trimmed.slice(1));
+    return trimmed;
+}
+/**
+ * Resolve a skill path relative to cwd
+ *
+ * @param p - Path to resolve
+ * @param cwd - Current working directory
+ * @returns Absolute path
+ */
+function resolveSkillPath(p, cwd) {
+    const normalized = normalizePath(p);
+    return isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
+}
+/**
+ * Check if a target path is under a root path
+ *
+ * @param target - Path to check
+ * @param root - Root path
+ * @returns True if target is under root
+ */
+function isUnderPath(target, root) {
+    const normalizedRoot = resolve(root);
+    if (target === normalizedRoot) {
+        return true;
+    }
+    const prefix = normalizedRoot.endsWith(sep)
+        ? normalizedRoot
+        : `${normalizedRoot}${sep}`;
+    return target.startsWith(prefix);
+}
+/**
+ * Load skills from all configured locations.
+ *
+ * Sources are loaded in precedence order (later sources override earlier):
+ * 1. Bundled skills (from this package)
+ * 2. User/managed skills (~/.elizaos/skills)
+ * 3. Project skills (<cwd>/.elizaos/skills)
+ * 4. Explicit skill paths
+ *
+ * @param options - Loading options
+ * @returns Loaded skills and diagnostics
+ */
+export function loadSkills(options = {}) {
+    const { cwd = process.cwd(), agentDir, skillPaths = [], includeDefaults = true, bundledSkillsDir, managedSkillsDir, } = options;
+    // Resolve directories
+    const resolvedAgentDir = agentDir ?? DEFAULT_AGENT_DIR;
+    const resolvedBundledDir = bundledSkillsDir ?? getSkillsDir();
+    const resolvedManagedDir = managedSkillsDir ?? join(resolvedAgentDir, "skills");
+    const projectSkillsDir = resolve(cwd, CONFIG_DIR_NAME, "skills");
+    const userSkillsDir = join(resolvedAgentDir, "skills");
+    const skillMap = new Map();
+    const realPathSet = new Set();
+    const allDiagnostics = [];
+    const collisionDiagnostics = [];
+    function addSkills(result) {
+        allDiagnostics.push(...result.diagnostics);
+        for (const skill of result.skills) {
+            // Skip skills without file paths (inline skills) - they can't be deduplicated
+            if (!skill.filePath) {
+                const existing = skillMap.get(skill.name);
+                if (!existing) {
+                    skillMap.set(skill.name, skill);
+                }
+                continue;
+            }
+            // Resolve symlinks to detect duplicate files
+            let realPath;
+            try {
+                realPath = realpathSync(skill.filePath);
+            }
+            catch {
+                realPath = skill.filePath;
+            }
+            // Skip silently if we've already loaded this exact file (via symlink)
+            if (realPathSet.has(realPath)) {
+                continue;
+            }
+            const existing = skillMap.get(skill.name);
+            if (existing) {
+                collisionDiagnostics.push({
+                    type: "collision",
+                    message: `name "${skill.name}" collision`,
+                    path: skill.filePath,
+                    collision: {
+                        resourceType: "skill",
+                        name: skill.name,
+                        winnerPath: existing.filePath ?? "(inline)",
+                        loserPath: skill.filePath,
+                    },
+                });
+            }
+            else {
+                skillMap.set(skill.name, skill);
+                realPathSet.add(realPath);
+            }
+        }
+    }
+    if (includeDefaults) {
+        // Load in precedence order: bundled < managed < curated < project.
+        // The curated namespace holds agent-derived skills that were promoted to
+        // "active" by the closed learning loop or the user. Skills under the
+        // sibling "proposed" directory are intentionally NOT scanned here — they
+        // are pending human review and only surfaced via the curated-skills API.
+        if (resolvedBundledDir) {
+            addSkills(loadSkillsFromDirInternal(resolvedBundledDir, "bundled", true));
+        }
+        addSkills(loadSkillsFromDirInternal(resolvedManagedDir, "managed", true));
+        addSkills(loadSkillsFromDirInternal(getCuratedActiveDir(), "curated", true));
+        addSkills(loadSkillsFromDirInternal(projectSkillsDir, "project", true));
+    }
+    // Determine source for explicit paths
+    const getSource = (resolvedPath) => {
+        if (!includeDefaults) {
+            if (isUnderPath(resolvedPath, userSkillsDir))
+                return "user";
+            if (isUnderPath(resolvedPath, projectSkillsDir))
+                return "project";
+        }
+        return "path";
+    };
+    // Load explicit skill paths
+    for (const rawPath of skillPaths) {
+        const resolvedPath = resolveSkillPath(rawPath, cwd);
+        if (!existsSync(resolvedPath)) {
+            allDiagnostics.push({
+                type: "warning",
+                message: "skill path does not exist",
+                path: resolvedPath,
+            });
+            continue;
+        }
+        const stats = statSync(resolvedPath);
+        const source = getSource(resolvedPath);
+        if (stats.isDirectory()) {
+            addSkills(loadSkillsFromDirInternal(resolvedPath, source, true));
+        }
+        else if (stats.isFile() && resolvedPath.endsWith(".md")) {
+            const result = loadSkillFromFile(resolvedPath, source);
+            if (result.skill) {
+                addSkills({ skills: [result.skill], diagnostics: result.diagnostics });
+            }
+            else {
+                allDiagnostics.push(...result.diagnostics);
+            }
+        }
+        else {
+            allDiagnostics.push({
+                type: "warning",
+                message: "skill path is not a markdown file",
+                path: resolvedPath,
+            });
+        }
+    }
+    return {
+        skills: Array.from(skillMap.values()),
+        diagnostics: [...allDiagnostics, ...collisionDiagnostics],
+    };
+}
+/**
+ * Load skill entries with full metadata parsing
+ *
+ * @param options - Loading options
+ * @returns Skill entries with parsed metadata
+ */
+export function loadSkillEntries(options = {}) {
+    const { skills } = loadSkills(options);
+    return skills.map((skill) => {
+        let frontmatter = {};
+        // Only parse frontmatter for file-based skills
+        if (skill.filePath) {
+            try {
+                const raw = readFileSync(skill.filePath, "utf-8");
+                const parsed = parseFrontmatter(raw);
+                frontmatter = parsed.frontmatter;
+            }
+            catch {
+                // Use empty frontmatter if parsing fails
+            }
+        }
+        return {
+            skill,
+            frontmatter,
+            metadata: resolveSkillMetadata(frontmatter),
+            invocation: resolveSkillInvocationPolicy(frontmatter),
+        };
+    });
+}

package/packages/skills/src/resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Get the absolute path to the bundled skills directory.
+ *
+ * Resolution order:
+ * 1. ELIZAOS_BUNDLED_SKILLS_DIR environment variable
+ * 2. Sibling `skills/` next to the executable (for compiled binaries)
+ * 3. Package's own `skills/` directory (relative to this module)
+ *
+ * @returns Absolute path to the skills directory
+ * @throws Error if skills directory cannot be found
+ */
+export declare function getSkillsDir(): string;
+/**
+ * Clear the cached skills directory path.
+ * Useful for testing or when the directory may have changed.
+ */
+export declare function clearSkillsDirCache(): void;
+/**
+ * Absolute path to the curated **active** skills directory. Skills here are
+ * loaded into the runtime alongside bundled and managed skills.
+ */
+export declare function getCuratedActiveDir(): string;
+/**
+ * Absolute path to the curated **proposed** skills directory. Skills here are
+ * NEVER loaded into the runtime — they are staged for human review via the
+ * Settings → Learned Skills UI.
+ */
+export declare function getProposedSkillsDir(): string;
+/**
+ * Promote a proposed skill to active by moving its directory atomically.
+ * Returns the destination path. Throws if the source does not exist or the
+ * destination already exists.
+ */
+export declare function promoteSkill(name: string): string;
+//# sourceMappingURL=resolver.d.ts.map

package/packages/skills/src/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../../../skills/src/resolver.ts"],"names":[],"mappings":"AA+CA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6CrC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAoBD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjD"}

package/packages/skills/src/resolver.js

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Cached skills directory path
+ */
+let cachedSkillsDir;
+/**
+ * Check if a directory looks like a skills directory
+ * (contains subdirectories with SKILL.md files or .md files directly)
+ *
+ * @param dir - Directory to check
+ * @returns True if directory appears to contain skills
+ */
+function looksLikeSkillsDir(dir) {
+    if (!existsSync(dir)) {
+        return false;
+    }
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith(".")) {
+            continue;
+        }
+        const fullPath = join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+            return true;
+        }
+        if (entry.isDirectory()) {
+            if (existsSync(join(fullPath, "SKILL.md"))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Get the absolute path to the bundled skills directory.
+ *
+ * Resolution order:
+ * 1. ELIZAOS_BUNDLED_SKILLS_DIR environment variable
+ * 2. Sibling `skills/` next to the executable (for compiled binaries)
+ * 3. Package's own `skills/` directory (relative to this module)
+ *
+ * @returns Absolute path to the skills directory
+ * @throws Error if skills directory cannot be found
+ */
+export function getSkillsDir() {
+    // Return cached value if available
+    if (cachedSkillsDir !== undefined) {
+        return cachedSkillsDir;
+    }
+    // Check environment variable override
+    const override = process.env.ELIZAOS_BUNDLED_SKILLS_DIR?.trim();
+    if (override && existsSync(override)) {
+        cachedSkillsDir = override;
+        return cachedSkillsDir;
+    }
+    // For compiled binaries: check sibling skills/ next to executable
+    const execDir = dirname(process.execPath);
+    const siblingSkills = join(execDir, "skills");
+    if (looksLikeSkillsDir(siblingSkills)) {
+        cachedSkillsDir = siblingSkills;
+        return cachedSkillsDir;
+    }
+    // Resolve relative to this module (packages/skills/dist/resolver.js -> packages/skills/skills)
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    // In development: packages/skills/src/resolver.ts -> packages/skills/skills
+    // In production: packages/skills/dist/resolver.js -> packages/skills/skills
+    const packageRoot = dirname(__dirname); // Go up from src/ or dist/
+    const packageSkills = join(packageRoot, "skills");
+    if (looksLikeSkillsDir(packageSkills)) {
+        cachedSkillsDir = packageSkills;
+        return cachedSkillsDir;
+    }
+    // Also check one more level up in case we're in a nested dist structure
+    const parentPackageSkills = join(dirname(packageRoot), "skills");
+    if (looksLikeSkillsDir(parentPackageSkills)) {
+        cachedSkillsDir = parentPackageSkills;
+        return cachedSkillsDir;
+    }
+    throw new Error("Could not find bundled skills directory. Set ELIZAOS_BUNDLED_SKILLS_DIR environment variable or ensure skills/ directory exists in package.");
+}
+/**
+ * Clear the cached skills directory path.
+ * Useful for testing or when the directory may have changed.
+ */
+export function clearSkillsDirCache() {
+    cachedSkillsDir = undefined;
+}
+/**
+ * Default base directory for the curated learning loop. Lives alongside the
+ * Milady state dir (`~/.milady/`) and holds two sibling namespaces:
+ *
+ *   curated/active/    — auto-promoted or human-promoted skills (loaded)
+ *   curated/proposed/  — staged drafts awaiting human review (NOT loaded)
+ *
+ * Honors `MILADY_STATE_DIR` and `ELIZA_STATE_DIR` (in that order); falls back
+ * to `~/.milady`.
+ */
+function resolveCuratedBaseDir() {
+    const stateDir = process.env.MILADY_STATE_DIR?.trim() ||
+        process.env.ELIZA_STATE_DIR?.trim() ||
+        join(homedir(), ".milady");
+    return join(stateDir, "skills", "curated");
+}
+/**
+ * Absolute path to the curated **active** skills directory. Skills here are
+ * loaded into the runtime alongside bundled and managed skills.
+ */
+export function getCuratedActiveDir() {
+    return join(resolveCuratedBaseDir(), "active");
+}
+/**
+ * Absolute path to the curated **proposed** skills directory. Skills here are
+ * NEVER loaded into the runtime — they are staged for human review via the
+ * Settings → Learned Skills UI.
+ */
+export function getProposedSkillsDir() {
+    return join(resolveCuratedBaseDir(), "proposed");
+}
+/**
+ * Promote a proposed skill to active by moving its directory atomically.
+ * Returns the destination path. Throws if the source does not exist or the
+ * destination already exists.
+ */
+export function promoteSkill(name) {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        throw new Error(`Invalid skill name "${name}" — must be lowercase a-z, 0-9, hyphens only`);
+    }
+    const proposedDir = join(getProposedSkillsDir(), name);
+    if (!existsSync(proposedDir) || !statSync(proposedDir).isDirectory()) {
+        throw new Error(`Proposed skill "${name}" not found at ${proposedDir}`);
+    }
+    const activeRoot = getCuratedActiveDir();
+    if (!existsSync(activeRoot)) {
+        mkdirSync(activeRoot, { recursive: true });
+    }
+    const activeDir = join(activeRoot, name);
+    if (existsSync(activeDir)) {
+        throw new Error(`Active skill "${name}" already exists at ${activeDir}`);
+    }
+    renameSync(proposedDir, activeDir);
+    return activeDir;
+}