@evalops/maestro 0.10.18 → 0.10.20

package/dist/skills/loader.js

@@ -19,28 +19,46 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { load as loadYaml } from "js-yaml";
 import { PATHS } from "../config/constants.js";
 import { loadConfiguredPackageResources } from "../packages/runtime.js";
 import { createLogger } from "../utils/logger.js";
+import { promptSafeText } from "../utils/prompt-safe-text.js";
 const logger = createLogger("skills:loader");
+const LEGACY_FLAT_RESOURCE_EXCLUDES = new Set([
+    "scripts",
+    "reference",
+    "references",
+    "assets",
+    "toolbox",
+    "mcp.json",
+    "mcp.json.example",
+]);
 /** Maximum lengths per Agent Skills spec */
 const MAX_NAME_LENGTH = 64;
 const MAX_DESCRIPTION_LENGTH = 1024;
 const MAX_COMPATIBILITY_LENGTH = 500;
 /** Allowed frontmatter fields per Agent Skills spec */
-const ALLOWED_FIELDS = new Set([
+export const SKILL_FRONTMATTER_FIELDS = [
     "name",
     "description",
     "license",
     "compatibility",
     "allowed-tools",
+    "argument-hint",
+    "builtin-tools",
+    "model",
+    "mode",
+    "isolatedContext",
     "metadata",
     // Legacy fields (deprecated but supported for backwards compatibility)
     "tags",
     "author",
     "version",
     "triggers",
-]);
+];
+/** Allowed frontmatter fields per Agent Skills spec plus Maestro package hints. */
+const ALLOWED_FIELDS = new Set(SKILL_FRONTMATTER_FIELDS);
 /**
  * Skill loading error.
  */
@@ -52,6 +70,75 @@ export class SkillLoadError extends Error {
         this.name = "SkillLoadError";
     }
 }
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function stringArrayValue(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0 ||
+            value.some((entry) => typeof entry !== "string" || entry.trim() === "")) {
+            return undefined;
+        }
+        const values = value
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+        return values.length > 0 ? values : undefined;
+    }
+    if (typeof value === "string") {
+        const values = value
+            .split(/[,\s]+/)
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+        return values.length > 0 ? values : undefined;
+    }
+    return undefined;
+}
+function validateStringArrayField(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (typeof value === "string") {
+        return stringArrayValue(value)
+            ? null
+            : `${field} must be a non-empty string or list of non-empty strings`;
+    }
+    if (Array.isArray(value)) {
+        return stringArrayValue(value)
+            ? null
+            : `${field} entries must all be non-empty strings`;
+    }
+    return `${field} must be a non-empty string or list of non-empty strings`;
+}
+function booleanValue(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const normalized = value.toLowerCase();
+        if (normalized === "true")
+            return true;
+        if (normalized === "false")
+            return false;
+    }
+    return undefined;
+}
+function metadataRecordValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string" &&
+            typeof entry !== "number" &&
+            typeof entry !== "boolean") {
+            continue;
+        }
+        const normalized = String(entry).trim();
+        if (normalized.length > 0) {
+            metadata[key] = normalized;
+        }
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
 /**
  * Validate skill name per Agent Skills spec.
  */
@@ -119,7 +206,7 @@ function validateFields(frontmatter) {
 /**
  * Find SKILL.md file (case-insensitive per spec).
  */
-function findSkillMd(dir) {
+export function findSkillMd(dir) {
     // Prefer uppercase
     const uppercase = join(dir, "SKILL.md");
     if (existsSync(uppercase)) {
@@ -135,7 +222,7 @@ function findSkillMd(dir) {
 /**
  * Parse YAML frontmatter from markdown content.
  */
-function parseFrontmatter(content) {
+export function parseFrontmatter(content) {
     if (!content.trimStart().startsWith("---")) {
         throw new Error("Missing frontmatter delimiters");
     }
@@ -145,75 +232,11 @@ function parseFrontmatter(content) {
         throw new Error("Frontmatter not properly closed");
     }
     const [, yamlContent, body] = match;
-    // Simple YAML parser for common patterns
-    const frontmatter = {};
-    const lines = yamlContent.split("\n");
-    let currentKey = null;
-    let currentArray = null;
-    let inMetadata = false;
-    let metadataObj = {};
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#"))
-            continue;
-        // Check for array item
-        if (trimmed.startsWith("- ") && currentKey && currentArray) {
-            currentArray.push(trimmed.slice(2).trim());
-            continue;
-        }
-        // Check for metadata nested key
-        if (inMetadata && line.startsWith("  ") && !trimmed.startsWith("-")) {
-            const colonIndex = trimmed.indexOf(":");
-            if (colonIndex > 0) {
-                const key = trimmed.slice(0, colonIndex).trim();
-                const value = trimmed
-                    .slice(colonIndex + 1)
-                    .trim()
-                    .replace(/^["']|["']$/g, "");
-                metadataObj[key] = value;
-                continue;
-            }
-        }
-        // Save previous array if exists
-        if (currentKey && currentArray) {
-            frontmatter[currentKey] = currentArray;
-            currentArray = null;
-        }
-        // End metadata block
-        if (inMetadata && !line.startsWith("  ")) {
-            frontmatter.metadata = metadataObj;
-            inMetadata = false;
-            metadataObj = {};
-        }
-        // Parse key: value
-        const colonIndex = trimmed.indexOf(":");
-        if (colonIndex > 0) {
-            const key = trimmed.slice(0, colonIndex).trim();
-            const value = trimmed.slice(colonIndex + 1).trim();
-            if (key === "metadata" && value === "") {
-                inMetadata = true;
-                currentKey = null;
-            }
-            else if (value === "") {
-                // Start of array
-                currentKey = key;
-                currentArray = [];
-            }
-            else {
-                // Simple value - remove quotes if present
-                frontmatter[key] = value.replace(/^["']|["']$/g, "");
-                currentKey = null;
-            }
-        }
-    }
-    // Save final array if exists
-    if (currentKey && currentArray) {
-        frontmatter[currentKey] = currentArray;
-    }
-    // Save metadata if still in block
-    if (inMetadata && Object.keys(metadataObj).length > 0) {
-        frontmatter.metadata = metadataObj;
+    const parsed = loadYaml(yamlContent ?? "") ?? {};
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Frontmatter must be a YAML object");
     }
+    const frontmatter = parsed;
     return { frontmatter, body: body };
 }
 /**
@@ -269,26 +292,44 @@ function loadSkillFromDirectory(skillDir, sourceType) {
             return new SkillLoadError(descError, skillFile, "INVALID_DESCRIPTION");
         }
         // Validate compatibility if present
-        if (frontmatter.compatibility) {
+        if (frontmatter.compatibility !== undefined) {
             const compatError = validateCompatibility(frontmatter.compatibility);
             if (compatError) {
                 return new SkillLoadError(compatError, skillFile, "INVALID_COMPATIBILITY");
             }
         }
+        for (const field of ["allowed-tools", "builtin-tools"]) {
+            const toolListError = validateStringArrayField(frontmatter[field], field);
+            if (toolListError) {
+                return new SkillLoadError(toolListError, skillFile, "INVALID_TOOL_LIST");
+            }
+        }
         // Discover resource directories
         const resourceDirs = {};
         const scriptsDir = join(skillDir, "scripts");
+        const referenceDir = join(skillDir, "reference");
         const referencesDir = join(skillDir, "references");
         const assetsDir = join(skillDir, "assets");
+        const toolboxDir = join(skillDir, "toolbox");
+        const mcpJsonPath = join(skillDir, "mcp.json");
         if (existsSync(scriptsDir) && statSync(scriptsDir).isDirectory()) {
             resourceDirs.scriptsDir = scriptsDir;
         }
+        if (existsSync(referenceDir) && statSync(referenceDir).isDirectory()) {
+            resourceDirs.referenceDir = referenceDir;
+        }
         if (existsSync(referencesDir) && statSync(referencesDir).isDirectory()) {
             resourceDirs.referencesDir = referencesDir;
         }
         if (existsSync(assetsDir) && statSync(assetsDir).isDirectory()) {
             resourceDirs.assetsDir = assetsDir;
         }
+        if (existsSync(toolboxDir) && statSync(toolboxDir).isDirectory()) {
+            resourceDirs.toolboxDir = toolboxDir;
+        }
+        if (existsSync(mcpJsonPath) && statSync(mcpJsonPath).isFile()) {
+            resourceDirs.mcpJsonPath = mcpJsonPath;
+        }
         // Discover bundled resources (legacy flat structure)
         const resources = [];
         try {
@@ -296,8 +337,9 @@ function loadSkillFromDirectory(skillDir, sourceType) {
             for (const file of files) {
                 if (file.toLowerCase() === "skill.md")
                     continue;
-                if (["scripts", "references", "assets"].includes(file))
+                if (LEGACY_FLAT_RESOURCE_EXCLUDES.has(file.toLowerCase())) {
                     continue;
+                }
                 const filePath = join(skillDir, file);
                 const stat = statSync(filePath);
                 if (stat.isFile()) {
@@ -318,10 +360,15 @@ function loadSkillFromDirectory(skillDir, sourceType) {
         const skill = {
             name,
             description,
-            license: frontmatter.license,
-            compatibility: frontmatter.compatibility,
-            allowedTools: frontmatter["allowed-tools"],
-            metadata: frontmatter.metadata,
+            license: stringValue(frontmatter.license),
+            compatibility: stringValue(frontmatter.compatibility),
+            allowedTools: stringArrayValue(frontmatter["allowed-tools"]),
+            builtinTools: stringArrayValue(frontmatter["builtin-tools"]),
+            argumentHint: stringValue(frontmatter["argument-hint"]),
+            model: stringValue(frontmatter.model),
+            mode: stringValue(frontmatter.mode),
+            isolatedContext: booleanValue(frontmatter.isolatedContext),
+            metadata: metadataRecordValue(frontmatter.metadata),
             // Legacy fields for backwards compatibility
             tags: Array.isArray(frontmatter.tags)
                 ? frontmatter.tags
@@ -554,6 +601,21 @@ export function skillToDict(skill) {
     if (skill.allowedTools) {
         result["allowed-tools"] = skill.allowedTools;
     }
+    if (skill.builtinTools) {
+        result["builtin-tools"] = skill.builtinTools;
+    }
+    if (skill.argumentHint) {
+        result["argument-hint"] = skill.argumentHint;
+    }
+    if (skill.model) {
+        result.model = skill.model;
+    }
+    if (skill.mode) {
+        result.mode = skill.mode;
+    }
+    if (skill.isolatedContext !== undefined) {
+        result.isolatedContext = skill.isolatedContext;
+    }
     if (skill.metadata && Object.keys(skill.metadata).length > 0) {
         result.metadata = skill.metadata;
     }
@@ -588,9 +650,10 @@ export function skillsToPrompt(skills) {
     }
     const lines = ["<available_skills>"];
     for (const skill of skills) {
+        const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH);
         lines.push("<skill>");
         lines.push(`  <name>${escapeXml(skill.name)}</name>`);
-        lines.push(`  <description>${escapeXml(skill.description)}</description>`);
+        lines.push(`  <description>${escapeXml(description ?? "")}</description>`);
         lines.push(`  <location>${escapeXml(join(skill.sourcePath, "SKILL.md"))}</location>`);
         lines.push("</skill>");
     }
@@ -634,6 +697,29 @@ export function formatSkillForInjection(skill) {
         }
         lines.push("");
     }
+    if (skill.resourceDirs.referenceDir || skill.resourceDirs.referencesDir) {
+        lines.push("## Reference Resources");
+        lines.push("");
+        lines.push("Load detailed references only when needed:");
+        if (skill.resourceDirs.referenceDir) {
+            lines.push(`- \`${skill.resourceDirs.referenceDir}\``);
+        }
+        if (skill.resourceDirs.referencesDir) {
+            lines.push(`- \`${skill.resourceDirs.referencesDir}\``);
+        }
+        lines.push("");
+    }
+    if (skill.resourceDirs.toolboxDir || skill.resourceDirs.mcpJsonPath) {
+        lines.push("## Tool Package");
+        lines.push("");
+        if (skill.resourceDirs.toolboxDir) {
+            lines.push(`- Toolbox executables are bundled under \`${skill.resourceDirs.toolboxDir}\`.`);
+        }
+        if (skill.resourceDirs.mcpJsonPath) {
+            lines.push(`- Bundled MCP config: \`${skill.resourceDirs.mcpJsonPath}\`.`);
+        }
+        lines.push("");
+    }
     lines.push("## Instructions");
     lines.push("");
     lines.push(skill.content);
@@ -655,7 +741,8 @@ export function getSkillsSummary(skills) {
     lines.push("");
     for (const skill of skills) {
         const tags = skill.tags?.length ? ` [${skill.tags.join(", ")}]` : "";
-        lines.push(`- **${skill.name}**${tags}: ${skill.description}`);
+        const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH) ?? "";
+        lines.push(`- **${skill.name}**${tags}: ${description}`);
         if (skill.triggers?.length) {
             lines.push(`  - Triggers: ${skill.triggers.join(", ")}`);
         }
@@ -696,12 +783,8 @@ export function formatSkillMetadataOnly(skill) {
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;")
         .replace(/"/g, "&quot;");
-    // Truncate description to max length per spec, escape XML
-    let description = skill.description;
-    if (description.length > MAX_DESCRIPTION_LENGTH) {
-        description = `${description.slice(0, MAX_DESCRIPTION_LENGTH - 3)}...`;
-    }
-    const escapeDesc = description
+    const description = promptSafeText(skill.description, MAX_DESCRIPTION_LENGTH);
+    const escapeDesc = (description ?? "")
         .replace(/&/g, "&amp;")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;")