@agentforge/skills 0.16.41 → 0.16.43

package/dist/index.cjs

@@ -444,390 +444,241 @@ function extractBody(content) {
   return matter__default.default(content).content.trim();
 }
 var logger3 = core.createLogger("agentforge:skills:registry", { level: core.LogLevel.INFO });
+function discoverSkills(config, skills, rootTrustMap, emit) {
+  skills.clear();
+  rootTrustMap.clear();
+  const scanErrors = [];
+  const normalizedRoots = config.skillRoots.map(normalizeRootConfig);
+  const plainPaths = normalizedRoots.map((root) => root.path);
+  for (const root of normalizedRoots) {
+    const resolvedPath = path.resolve(expandHome(root.path));
+    rootTrustMap.set(resolvedPath, root.trust);
+  }
+  const candidates = scanAllSkillRoots(plainPaths);
+  let successCount = 0;
+  let warningCount = 0;
+  for (const candidate of candidates) {
+    const result = parseSkillContent(candidate.content, candidate.dirName);
+    if (!result.success) {
+      warningCount++;
+      recordScanError(scanErrors, candidate.skillPath, result.error || "Unknown parse error");
+      emit("skill:warning" /* SKILL_WARNING */, {
+        skillPath: candidate.skillPath,
+        rootPath: candidate.rootPath,
+        error: result.error
+      });
+      logger3.warn("Skipping invalid skill", {
+        skillPath: candidate.skillPath,
+        ...result.error ? { error: result.error } : {}
+      });
+      continue;
+    }
+    const skill = {
+      metadata: result.metadata,
+      skillPath: candidate.skillPath,
+      rootPath: candidate.rootPath,
+      trustLevel: rootTrustMap.get(candidate.rootPath) ?? "untrusted"
+    };
+    if (skills.has(skill.metadata.name)) {
+      warningCount++;
+      const existing = skills.get(skill.metadata.name);
+      const warningMessage = `Duplicate skill name "${skill.metadata.name}" from "${candidate.rootPath}" \u2014 keeping version from "${existing.rootPath}" (first root takes precedence)`;
+      recordScanError(scanErrors, candidate.skillPath, warningMessage);
+      emit("skill:warning" /* SKILL_WARNING */, {
+        skillPath: candidate.skillPath,
+        rootPath: candidate.rootPath,
+        duplicateOf: existing.skillPath,
+        error: warningMessage
+      });
+      logger3.warn("Duplicate skill name, keeping first", {
+        name: skill.metadata.name,
+        kept: existing.skillPath,
+        skipped: candidate.skillPath
+      });
+      continue;
+    }
+    skills.set(skill.metadata.name, skill);
+    successCount++;
+    emit("skill:discovered" /* SKILL_DISCOVERED */, skill);
+    logger3.debug("Skill discovered", {
+      name: skill.metadata.name,
+      description: skill.metadata.description.slice(0, 80),
+      skillPath: skill.skillPath
+    });
+  }
+  logger3.info("Skill registry populated", {
+    rootsScanned: config.skillRoots.length,
+    skillsDiscovered: successCount,
+    warnings: warningCount
+  });
+  return scanErrors;
+}
+function recordScanError(scanErrors, path, error) {
+  scanErrors.push({ path, error });
+}
+var logger4 = core.createLogger("agentforge:skills:registry", { level: core.LogLevel.INFO });
+function addRegistryEventHandler(eventHandlers, event, handler) {
+  if (!eventHandlers.has(event)) {
+    eventHandlers.set(event, /* @__PURE__ */ new Set());
+  }
+  eventHandlers.get(event).add(handler);
+}
+function removeRegistryEventHandler(eventHandlers, event, handler) {
+  const handlers = eventHandlers.get(event);
+  if (handlers) {
+    handlers.delete(handler);
+  }
+}
+function emitRegistryEvent(eventHandlers, event, data) {
+  const handlers = eventHandlers.get(event);
+  if (!handlers) {
+    return;
+  }
+  handlers.forEach((handler) => {
+    try {
+      handler(data);
+    } catch (error) {
+      logger4.error("Skill event handler error", {
+        event,
+        error: error instanceof Error ? error.message : String(error),
+        ...error instanceof Error && error.stack ? { stack: error.stack } : {}
+      });
+    }
+  });
+}
+var logger5 = core.createLogger("agentforge:skills:registry", { level: core.LogLevel.INFO });
+function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
+  if (!config.enabled) {
+    logger5.debug("Skill prompt generation skipped (disabled)", {
+      enabled: config.enabled ?? false
+    });
+    return "";
+  }
+  let skills = allSkills;
+  if (options?.skills && options.skills.length > 0) {
+    const requested = new Set(options.skills);
+    skills = skills.filter((skill) => requested.has(skill.metadata.name));
+  }
+  if (config.maxDiscoveredSkills !== void 0 && config.maxDiscoveredSkills >= 0) {
+    skills = skills.slice(0, config.maxDiscoveredSkills);
+  }
+  if (skills.length === 0) {
+    logger5.debug("Skill prompt generation produced empty result", {
+      totalDiscovered,
+      filterApplied: !!(options?.skills && options.skills.length > 0),
+      ...config.maxDiscoveredSkills !== void 0 ? { maxCap: config.maxDiscoveredSkills } : {}
+    });
+    return "";
+  }
+  const xml = `<available_skills>
+${skills.map(renderSkillEntry).join("\n")}
+</available_skills>`;
+  const estimatedTokens = Math.ceil(xml.length / 4);
+  logger5.info("Skill prompt generated", {
+    skillCount: skills.length,
+    totalDiscovered,
+    filterApplied: !!(options?.skills && options.skills.length > 0),
+    ...config.maxDiscoveredSkills !== void 0 ? { maxCap: config.maxDiscoveredSkills } : {},
+    estimatedTokens,
+    xmlLength: xml.length
+  });
+  return xml;
+}
+function renderSkillEntry(skill) {
+  return [
+    "  <skill>",
+    `    <name>${escapeXml(skill.metadata.name)}</name>`,
+    `    <description>${escapeXml(skill.metadata.description)}</description>`,
+    `    <location>${escapeXml(skill.skillPath)}</location>`,
+    "  </skill>"
+  ].join("\n");
+}
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// src/registry-query-api.ts
+function getSkill(skills, name) {
+  return skills.get(name);
+}
+function getAllSkills(skills) {
+  return Array.from(skills.values());
+}
+function hasSkill(skills, name) {
+  return skills.has(name);
+}
+function getSkillCount(skills) {
+  return skills.size;
+}
+function getSkillNames(skills) {
+  return Array.from(skills.keys());
+}
+function getScanErrors(scanErrors) {
+  return scanErrors;
+}
+function getAllowedTools(skills, name) {
+  return skills.get(name)?.metadata.allowedTools;
+}
+
+// src/registry.ts
 var SkillRegistry = class {
   skills = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
   config;
   scanErrors = [];
-  /** Maps resolved root paths → trust levels for skill trust assignment */
   rootTrustMap = /* @__PURE__ */ new Map();
-  /**
-   * Create a SkillRegistry and immediately scan configured roots for skills.
-   *
-   * @param config - Registry configuration with skill root paths
-   *
-   * @example
-   * ```ts
-   * const registry = new SkillRegistry({
-   *   skillRoots: ['.agentskills', '~/.agentskills', './project-skills'],
-   * });
-   * console.log(`Discovered ${registry.size()} skills`);
-   * ```
-   */
   constructor(config) {
     this.config = config;
     this.discover();
   }
-  /**
-   * Scan all configured roots and populate the registry.
-   *
-   * Called automatically during construction. Can be called again
-   * to re-scan (clears existing skills first).
-   */
   discover() {
-    this.skills.clear();
-    this.scanErrors = [];
-    this.rootTrustMap.clear();
-    const normalizedRoots = this.config.skillRoots.map(normalizeRootConfig);
-    const plainPaths = normalizedRoots.map((r) => r.path);
-    for (const root of normalizedRoots) {
-      const resolvedPath = path.resolve(expandHome(root.path));
-      this.rootTrustMap.set(resolvedPath, root.trust);
-    }
-    const candidates = scanAllSkillRoots(plainPaths);
-    let successCount = 0;
-    let warningCount = 0;
-    for (const candidate of candidates) {
-      const result = parseSkillContent(candidate.content, candidate.dirName);
-      if (!result.success) {
-        warningCount++;
-        this.scanErrors.push({
-          path: candidate.skillPath,
-          error: result.error || "Unknown parse error"
-        });
-        this.emit("skill:warning" /* SKILL_WARNING */, {
-          skillPath: candidate.skillPath,
-          rootPath: candidate.rootPath,
-          error: result.error
-        });
-        logger3.warn("Skipping invalid skill", {
-          skillPath: candidate.skillPath,
-          ...result.error ? { error: result.error } : {}
-        });
-        continue;
-      }
-      const skill = {
-        metadata: result.metadata,
-        skillPath: candidate.skillPath,
-        rootPath: candidate.rootPath,
-        trustLevel: this.rootTrustMap.get(candidate.rootPath) ?? "untrusted"
-      };
-      if (this.skills.has(skill.metadata.name)) {
-        const existing = this.skills.get(skill.metadata.name);
-        warningCount++;
-        const warningMsg = `Duplicate skill name "${skill.metadata.name}" from "${candidate.rootPath}" \u2014 keeping version from "${existing.rootPath}" (first root takes precedence)`;
-        this.scanErrors.push({
-          path: candidate.skillPath,
-          error: warningMsg
-        });
-        this.emit("skill:warning" /* SKILL_WARNING */, {
-          skillPath: candidate.skillPath,
-          rootPath: candidate.rootPath,
-          duplicateOf: existing.skillPath,
-          error: warningMsg
-        });
-        logger3.warn("Duplicate skill name, keeping first", {
-          name: skill.metadata.name,
-          kept: existing.skillPath,
-          skipped: candidate.skillPath
-        });
-        continue;
-      }
-      this.skills.set(skill.metadata.name, skill);
-      successCount++;
-      this.emit("skill:discovered" /* SKILL_DISCOVERED */, skill);
-      logger3.debug("Skill discovered", {
-        name: skill.metadata.name,
-        description: skill.metadata.description.slice(0, 80),
-        skillPath: skill.skillPath
-      });
-    }
-    logger3.info("Skill registry populated", {
-      rootsScanned: this.config.skillRoots.length,
-      skillsDiscovered: successCount,
-      warnings: warningCount
+    this.scanErrors = discoverSkills(this.config, this.skills, this.rootTrustMap, (event, data) => {
+      this.emit(event, data);
     });
   }
-  // ─── Query API (parallel to ToolRegistry) ──────────────────────────────
-  /**
-   * Get a skill by name.
-   *
-   * @param name - The skill name
-   * @returns The skill, or undefined if not found
-   *
-   * @example
-   * ```ts
-   * const skill = registry.get('code-review');
-   * if (skill) {
-   *   console.log(skill.metadata.description);
-   * }
-   * ```
-   */
   get(name) {
-    return this.skills.get(name);
-  }
-  /**
-   * Get all discovered skills.
-   *
-   * @returns Array of all skills
-   *
-   * @example
-   * ```ts
-   * const allSkills = registry.getAll();
-   * console.log(`Total skills: ${allSkills.length}`);
-   * ```
-   */
+    return getSkill(this.skills, name);
+  }
   getAll() {
-    return Array.from(this.skills.values());
-  }
-  /**
-   * Check if a skill exists in the registry.
-   *
-   * @param name - The skill name
-   * @returns True if the skill exists
-   *
-   * @example
-   * ```ts
-   * if (registry.has('code-review')) {
-   *   console.log('Skill available!');
-   * }
-   * ```
-   */
+    return getAllSkills(this.skills);
+  }
   has(name) {
-    return this.skills.has(name);
-  }
-  /**
-   * Get the number of discovered skills.
-   *
-   * @returns Number of skills in the registry
-   *
-   * @example
-   * ```ts
-   * console.log(`Registry has ${registry.size()} skills`);
-   * ```
-   */
+    return hasSkill(this.skills, name);
+  }
   size() {
-    return this.skills.size;
+    return getSkillCount(this.skills);
   }
-  /**
-   * Get all skill names.
-   *
-   * @returns Array of skill names
-   */
   getNames() {
-    return Array.from(this.skills.keys());
-  }
-  /**
-   * Get errors/warnings from the last scan.
-   *
-   * Useful for diagnostics and observability.
-   *
-   * @returns Array of scan errors with paths
-   */
+    return getSkillNames(this.skills);
+  }
   getScanErrors() {
-    return this.scanErrors;
-  }
-  /**
-   * Check whether untrusted script access is allowed via config override.
-   *
-   * Used by activation tools to pass the override flag to trust policy checks.
-   *
-   * @returns True if `allowUntrustedScripts` is set in config
-   */
+    return getScanErrors(this.scanErrors);
+  }
   getAllowUntrustedScripts() {
     return this.config.allowUntrustedScripts ?? false;
   }
-  /**
-   * Get the `allowed-tools` list for a skill.
-   *
-   * Returns the `allowedTools` array from the skill's frontmatter metadata,
-   * enabling agents to filter their tool set based on what the skill expects.
-   *
-   * @param name - The skill name
-   * @returns Array of allowed tool names, or undefined if skill not found or field not set
-   *
-   * @example
-   * ```ts
-   * const allowed = registry.getAllowedTools('code-review');
-   * if (allowed) {
-   *   const filteredTools = allTools.filter(t => allowed.includes(t.name));
-   * }
-   * ```
-   */
   getAllowedTools(name) {
-    const skill = this.skills.get(name);
-    return skill?.metadata.allowedTools;
-  }
-  // ─── Prompt Generation ─────────────────────────────────────────────────
-  /**
-   * Generate an `<available_skills>` XML block for system prompt injection.
-   *
-   * Returns an empty string when:
-   * - `config.enabled` is `false` (default) — agents operate with unmodified prompts
-   * - No skills match the filter criteria
-   *
-   * The output composes naturally with `toolRegistry.generatePrompt()` —
-   * simply concatenate both into the system prompt.
-   *
-   * @param options - Optional filtering (subset of skill names)
-   * @returns XML string or empty string
-   *
-   * @example
-   * ```ts
-   * // All skills
-   * const xml = registry.generatePrompt();
-   *
-   * // Subset for a focused agent
-   * const xml = registry.generatePrompt({ skills: ['code-review', 'testing'] });
-   *
-   * // Compose with tool prompt
-   * const systemPrompt = [
-   *   toolRegistry.generatePrompt(),
-   *   skillRegistry.generatePrompt(),
-   * ].filter(Boolean).join('\n\n');
-   * ```
-   */
+    return getAllowedTools(this.skills, name);
+  }
   generatePrompt(options) {
-    if (!this.config.enabled) {
-      logger3.debug("Skill prompt generation skipped (disabled)", {
-        enabled: this.config.enabled ?? false
-      });
-      return "";
-    }
-    let skills = this.getAll();
-    if (options?.skills && options.skills.length > 0) {
-      const requested = new Set(options.skills);
-      skills = skills.filter((s) => requested.has(s.metadata.name));
-    }
-    if (this.config.maxDiscoveredSkills !== void 0 && this.config.maxDiscoveredSkills >= 0) {
-      skills = skills.slice(0, this.config.maxDiscoveredSkills);
-    }
-    if (skills.length === 0) {
-      logger3.debug("Skill prompt generation produced empty result", {
-        totalDiscovered: this.size(),
-        filterApplied: !!(options?.skills && options.skills.length > 0),
-        ...this.config.maxDiscoveredSkills !== void 0 ? { maxCap: this.config.maxDiscoveredSkills } : {}
-      });
-      return "";
-    }
-    const skillEntries = skills.map((skill) => {
-      const lines = [
-        "  <skill>",
-        `    <name>${escapeXml(skill.metadata.name)}</name>`,
-        `    <description>${escapeXml(skill.metadata.description)}</description>`,
-        `    <location>${escapeXml(skill.skillPath)}</location>`,
-        "  </skill>"
-      ];
-      return lines.join("\n");
-    });
-    const xml = `<available_skills>
-${skillEntries.join("\n")}
-</available_skills>`;
-    const estimatedTokens = Math.ceil(xml.length / 4);
-    logger3.info("Skill prompt generated", {
-      skillCount: skills.length,
-      totalDiscovered: this.size(),
-      filterApplied: !!(options?.skills && options.skills.length > 0),
-      ...this.config.maxDiscoveredSkills !== void 0 ? { maxCap: this.config.maxDiscoveredSkills } : {},
-      estimatedTokens,
-      xmlLength: xml.length
-    });
-    return xml;
-  }
-  // ─── Event System ──────────────────────────────────────────────────────
-  /**
-   * Register an event handler.
-   *
-   * @param event - The event to listen for
-   * @param handler - The handler function
-   *
-   * @example
-   * ```ts
-   * registry.on(SkillRegistryEvent.SKILL_DISCOVERED, (skill) => {
-   *   console.log('Found skill:', skill.metadata.name);
-   * });
-   * ```
-   */
+    return generateSkillPrompt(this.config, this.getAll(), this.size(), options);
+  }
   on(event, handler) {
-    if (!this.eventHandlers.has(event)) {
-      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
-    }
-    this.eventHandlers.get(event).add(handler);
-  }
-  /**
-   * Unregister an event handler.
-   *
-   * @param event - The event to stop listening for
-   * @param handler - The handler function to remove
-   */
-  off(event, handler) {
-    const handlers = this.eventHandlers.get(event);
-    if (handlers) {
-      handlers.delete(handler);
-    }
+    addRegistryEventHandler(this.eventHandlers, event, handler);
   }
-  /**
-   * Emit an event to all registered handlers.
-   *
-   * @param event - The event to emit
-   * @param data - The event data
-   * @private
-   */
-  emit(event, data) {
-    const handlers = this.eventHandlers.get(event);
-    if (handlers) {
-      handlers.forEach((handler) => {
-        try {
-          handler(data);
-        } catch (error) {
-          logger3.error("Skill event handler error", {
-            event,
-            error: error instanceof Error ? error.message : String(error),
-            ...error instanceof Error && error.stack ? { stack: error.stack } : {}
-          });
-        }
-      });
-    }
+  off(event, handler) {
+    removeRegistryEventHandler(this.eventHandlers, event, handler);
   }
-  /**
-   * Emit an event (public API for activation tools).
-   *
-   * Used by skill activation tools to emit `skill:activated` and
-   * `skill:resource-loaded` events through the registry's event system.
-   *
-   * @param event - The event to emit
-   * @param data - The event data
-   */
   emitEvent(event, data) {
     this.emit(event, data);
   }
-  // ─── Tool Integration ────────────────────────────────────────────────
-  /**
-   * Create activation tools pre-wired to this registry instance.
-   *
-   * Returns `activate-skill` and `read-skill-resource` tools that
-   * agents can use to load skill instructions and resources on demand.
-   *
-   * @returns Array of [activate-skill, read-skill-resource] tools
-   *
-   * @example
-   * ```ts
-   * const agent = createReActAgent({
-   *   model: llm,
-   *   tools: [
-   *     ...toolRegistry.toLangChainTools(),
-   *     ...skillRegistry.toActivationTools(),
-   *   ],
-   * });
-   * ```
-   */
   toActivationTools() {
     return createSkillActivationTools(this);
   }
+  emit(event, data) {
+    emitRegistryEvent(this.eventHandlers, event, data);
+  }
 };
-function escapeXml(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
-}
 
 exports.SkillRegistry = SkillRegistry;
 exports.SkillRegistryEvent = SkillRegistryEvent;