@agentforge/core 0.12.6 → 0.14.0

package/dist/index.cjs

@@ -47,6 +47,8 @@ __export(index_exports, {
   MissingDescriptionError: () => MissingDescriptionError,
   Profiler: () => Profiler,
   RegistryEvent: () => RegistryEvent,
+  SkillRegistry: () => SkillRegistry,
+  SkillRegistryEvent: () => SkillRegistryEvent,
   TimeoutError: () => TimeoutError,
   ToolBuilder: () => ToolBuilder,
   ToolCategory: () => ToolCategory,
@@ -56,6 +58,7 @@ __export(index_exports, {
   ToolNameSchema: () => ToolNameSchema,
   ToolRegistry: () => ToolRegistry,
   ToolRelationsSchema: () => ToolRelationsSchema,
+  TrustPolicyReason: () => TrustPolicyReason,
   batch: () => batch,
   broadcast: () => broadcast,
   cache: () => cache,
@@ -69,6 +72,7 @@ __export(index_exports, {
   composeWithOptions: () => composeWithOptions,
   conditional: () => conditional,
   configureLangSmith: () => configureLangSmith,
+  createActivateSkillTool: () => createActivateSkillTool,
   createAlertManager: () => createAlertManager,
   createApprovalRequiredInterrupt: () => createApprovalRequiredInterrupt,
   createAuditLogger: () => createAuditLogger,
@@ -97,11 +101,13 @@ __export(index_exports, {
   createParallelWorkflow: () => createParallelWorkflow,
   createProfiler: () => createProfiler,
   createProgressTracker: () => createProgressTracker,
+  createReadSkillResourceTool: () => createReadSkillResourceTool,
   createSSEFormatter: () => createSSEFormatter,
   createSequentialWorkflow: () => createSequentialWorkflow,
   createSharedCache: () => createSharedCache,
   createSharedConcurrencyController: () => createSharedConcurrencyController,
   createSharedRateLimiter: () => createSharedRateLimiter,
+  createSkillActivationTools: () => createSkillActivationTools,
   createSqliteCheckpointer: () => createSqliteCheckpointer,
   createStateAnnotation: () => createStateAnnotation,
   createSubgraph: () => createSubgraph,
@@ -112,6 +118,8 @@ __export(index_exports, {
   createToolUnsafe: () => createToolUnsafe,
   createWebSocketHandler: () => createWebSocketHandler,
   development: () => development,
+  evaluateTrustPolicy: () => evaluateTrustPolicy,
+  expandHome: () => expandHome,
   filter: () => filter,
   formatAgentResumedEvent: () => formatAgentResumedEvent,
   formatAgentWaitingEvent: () => formatAgentWaitingEvent,
@@ -131,20 +139,26 @@ __export(index_exports, {
   isCustomInterrupt: () => isCustomInterrupt,
   isHumanRequestInterrupt: () => isHumanRequestInterrupt,
   isMemoryCheckpointer: () => isMemoryCheckpointer,
+  isScriptResource: () => isScriptResource,
   isTracingEnabled: () => isTracingEnabled,
   loadPrompt: () => loadPrompt,
   map: () => map,
   merge: () => merge,
   mergeState: () => mergeState,
+  normalizeRootConfig: () => normalizeRootConfig,
   parallel: () => parallel,
   parseSSEEvent: () => parseSSEEvent,
+  parseSkillContent: () => parseSkillContent,
   presets: () => presets,
   production: () => production,
   reduce: () => reduce,
   renderTemplate: () => renderTemplate,
+  resolveResourcePath: () => resolveResourcePath,
   retry: () => retry,
   safeValidateSchemaDescriptions: () => safeValidateSchemaDescriptions,
   sanitizeValue: () => sanitizeValue,
+  scanAllSkillRoots: () => scanAllSkillRoots,
+  scanSkillRoot: () => scanSkillRoot,
   sendMessage: () => sendMessage,
   sequential: () => sequential,
   sequentialBuilder: () => sequentialBuilder,
@@ -156,6 +170,9 @@ __export(index_exports, {
   toLangChainTools: () => toLangChainTools,
   toolBuilder: () => toolBuilder,
   validateSchemaDescriptions: () => validateSchemaDescriptions,
+  validateSkillDescription: () => validateSkillDescription,
+  validateSkillName: () => validateSkillName,
+  validateSkillNameMatchesDir: () => validateSkillNameMatchesDir,
   validateState: () => validateState,
   validateTool: () => validateTool,
   validateToolMetadata: () => validateToolMetadata,
@@ -182,6 +199,7 @@ var ToolCategory = /* @__PURE__ */ ((ToolCategory2) => {
   ToolCategory2["API"] = "api";
   ToolCategory2["UTILITY"] = "utility";
   ToolCategory2["CUSTOM"] = "custom";
+  ToolCategory2["SKILLS"] = "skills";
   return ToolCategory2;
 })(ToolCategory || {});
 
@@ -1580,7 +1598,7 @@ function createToolExecutor(config = {}) {
         }
         if (attempt < policy.maxAttempts) {
           const delay = calculateBackoff(attempt, policy);
-          await new Promise((resolve) => setTimeout(resolve, delay));
+          await new Promise((resolve3) => setTimeout(resolve3, delay));
         }
       }
     }
@@ -1637,12 +1655,12 @@ function createToolExecutor(config = {}) {
   }
   async function execute(tool, input, options = {}) {
     const priority = options.priority || priorityFn(tool);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       queue.push({
         tool,
         input,
         priority,
-        resolve,
+        resolve: resolve3,
         reject,
         timestamp: Date.now()
       });
@@ -1942,7 +1960,7 @@ function retry(tool, options = {}) {
           lastError = error;
           if (attempt < maxAttempts) {
             const waitTime = backoff === "exponential" ? delay * Math.pow(2, attempt - 1) : delay * attempt;
-            await new Promise((resolve) => setTimeout(resolve, waitTime));
+            await new Promise((resolve3) => setTimeout(resolve3, waitTime));
           }
         }
       }
@@ -2003,7 +2021,7 @@ function createMockTool(config) {
       const startTime = Date.now();
       if (latency) {
         const delay = typeof latency === "number" ? latency : Math.random() * (latency.max - latency.min) + latency.min;
-        await new Promise((resolve) => setTimeout(resolve, delay));
+        await new Promise((resolve3) => setTimeout(resolve3, delay));
       }
       if (errorRate > 0 && Math.random() < errorRate) {
         const error2 = new Error(`Random error from ${name}`);
@@ -2074,8 +2092,8 @@ function createToolSimulator(config) {
     if (!latency) return 0;
     const u1 = Math.random();
     const u2 = Math.random();
-    const z3 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
-    return Math.max(0, latency.mean + z3 * latency.stddev);
+    const z4 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    return Math.max(0, latency.mean + z4 * latency.stddev);
   }
   return {
     execute: async (toolName, input) => {
@@ -2086,7 +2104,7 @@ function createToolSimulator(config) {
       const startTime = Date.now();
       if (latency) {
         const delay = generateLatency();
-        await new Promise((resolve) => setTimeout(resolve, delay));
+        await new Promise((resolve3) => setTimeout(resolve3, delay));
       }
       if (errorRate > 0 && Math.random() < errorRate) {
         const error = new Error(`Simulated error from ${toolName}`);
@@ -2444,7 +2462,7 @@ function calculateDelay(attempt, strategy, initialDelay, maxDelay) {
   return Math.min(delay, maxDelay);
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function withRetry(node, options = {}) {
   const {
@@ -2690,14 +2708,14 @@ var withLogging = (options) => {
     onComplete,
     onError
   } = options;
-  const logger5 = providedLogger || createLogger(name, { level });
+  const logger8 = providedLogger || createLogger(name, { level });
   return (node) => {
     return async (state) => {
       const startTime = Date.now();
       try {
         if (logInput) {
           const data = extractData ? extractData(state) : { state };
-          logger5.info("Node execution started", data);
+          logger8.info("Node execution started", data);
         }
         if (onStart) {
           onStart(state);
@@ -2707,9 +2725,9 @@ var withLogging = (options) => {
         if (logOutput) {
           const data = extractData ? extractData(result) : { result };
           if (logDuration) {
-            logger5.info(`Node execution completed (${duration}ms)`, data);
+            logger8.info(`Node execution completed (${duration}ms)`, data);
           } else {
-            logger5.info("Node execution completed", data);
+            logger8.info("Node execution completed", data);
           }
         }
         if (onComplete) {
@@ -2720,7 +2738,7 @@ var withLogging = (options) => {
         const duration = Date.now() - startTime;
         const err = error instanceof Error ? error : new Error(String(error));
         if (logErrors) {
-          logger5.error(`Node execution failed (${duration}ms)`, {
+          logger8.error(`Node execution failed (${duration}ms)`, {
             error: err.message,
             stack: err.stack
           });
@@ -2756,7 +2774,7 @@ function withLogging2(options) {
 function production(node, options) {
   const {
     nodeName,
-    logger: logger5,
+    logger: logger8,
     enableMetrics = true,
     enableTracing = true,
     enableRetry = true,
@@ -2764,7 +2782,7 @@ function production(node, options) {
     retryOptions = {},
     errorOptions = {}
   } = options;
-  const actualLogger = logger5 || createLogger(nodeName, { level: "info" /* INFO */ });
+  const actualLogger = logger8 || createLogger(nodeName, { level: "info" /* INFO */ });
   const middleware = [];
   middleware.push(
     withLogging2({
@@ -2828,9 +2846,9 @@ function development(node, options) {
   const {
     nodeName,
     verbose = true,
-    logger: logger5
+    logger: logger8
   } = options;
-  const actualLogger = logger5 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
+  const actualLogger = logger8 || createLogger(nodeName, { level: "debug" /* DEBUG */ });
   return withLogging2({
     logger: actualLogger,
     name: nodeName,
@@ -2854,7 +2872,7 @@ function testing(node, options) {
       invocations.push(state);
     }
     if (delay > 0) {
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await new Promise((resolve3) => setTimeout(resolve3, delay));
     }
     if (simulateError) {
       throw simulateError;
@@ -3313,12 +3331,12 @@ var ConcurrencyController = class {
       }
       throw new Error(`Queue is full (max size: ${this.maxQueueSize})`);
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const task = {
         state,
         priority,
         executor,
-        resolve,
+        resolve: resolve3,
         reject,
         timestamp: Date.now()
       };
@@ -3783,7 +3801,7 @@ async function* throttle(stream, options) {
     const now = Date.now();
     const timeSinceLastEmit = now - lastEmit;
     if (timeSinceLastEmit < interval) {
-      await new Promise((resolve) => setTimeout(resolve, interval - timeSinceLastEmit));
+      await new Promise((resolve3) => setTimeout(resolve3, interval - timeSinceLastEmit));
     }
     lastEmit = Date.now();
     yield item;
@@ -4298,17 +4316,17 @@ var ConnectionPool = class {
       this.options.onAcquire?.(connection);
       return connection;
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const timeout2 = poolConfig.acquireTimeout || 3e4;
       const timer = setTimeout(() => {
-        const index = this.pending.findIndex((p) => p.resolve === resolve);
+        const index = this.pending.findIndex((p) => p.resolve === resolve3);
         if (index !== -1) {
           this.pending.splice(index, 1);
           this.stats.pending--;
         }
         reject(new Error("Acquire timeout"));
       }, timeout2);
-      this.pending.push({ resolve, reject, timeout: timer });
+      this.pending.push({ resolve: resolve3, reject, timeout: timer });
       this.stats.pending++;
     });
   }
@@ -4392,7 +4410,7 @@ var ConnectionPool = class {
     this.pending = [];
     this.stats.pending = 0;
     while (this.connections.some((c) => c.inUse)) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await new Promise((resolve3) => setTimeout(resolve3, 100));
     }
   }
   async clear() {
@@ -4719,10 +4737,10 @@ var BatchProcessor = class {
     failedBatches: 0
   };
   add(input) {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       this.pending.push({
         input,
-        resolve,
+        resolve: resolve3,
         reject,
         addedAt: Date.now()
       });
@@ -5482,6 +5500,841 @@ function loadPrompt(promptName, options = {}, promptsDir) {
     );
   }
 }
+
+// src/skills/types.ts
+var TrustPolicyReason = /* @__PURE__ */ ((TrustPolicyReason2) => {
+  TrustPolicyReason2["NOT_SCRIPT"] = "not-script";
+  TrustPolicyReason2["WORKSPACE_TRUST"] = "workspace-trust";
+  TrustPolicyReason2["TRUSTED_ROOT"] = "trusted-root";
+  TrustPolicyReason2["UNTRUSTED_SCRIPT_DENIED"] = "untrusted-script-denied";
+  TrustPolicyReason2["UNTRUSTED_SCRIPT_ALLOWED"] = "untrusted-script-allowed-override";
+  TrustPolicyReason2["UNKNOWN_TRUST_LEVEL"] = "unknown-trust-level";
+  return TrustPolicyReason2;
+})(TrustPolicyReason || {});
+var SkillRegistryEvent = /* @__PURE__ */ ((SkillRegistryEvent2) => {
+  SkillRegistryEvent2["SKILL_DISCOVERED"] = "skill:discovered";
+  SkillRegistryEvent2["SKILL_WARNING"] = "skill:warning";
+  SkillRegistryEvent2["SKILL_ACTIVATED"] = "skill:activated";
+  SkillRegistryEvent2["SKILL_RESOURCE_LOADED"] = "skill:resource-loaded";
+  SkillRegistryEvent2["TRUST_POLICY_DENIED"] = "trust:policy-denied";
+  SkillRegistryEvent2["TRUST_POLICY_ALLOWED"] = "trust:policy-allowed";
+  return SkillRegistryEvent2;
+})(SkillRegistryEvent || {});
+
+// src/skills/parser.ts
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+var SKILL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SKILL_NAME_MAX_LENGTH = 64;
+var SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+function validateSkillName(name) {
+  const errors = [];
+  if (name === void 0 || name === null) {
+    errors.push({ field: "name", message: "name is required" });
+    return errors;
+  }
+  if (typeof name !== "string") {
+    errors.push({ field: "name", message: "name must be a string" });
+    return errors;
+  }
+  if (name.length === 0) {
+    errors.push({ field: "name", message: "name must not be empty" });
+    return errors;
+  }
+  if (name.length > SKILL_NAME_MAX_LENGTH) {
+    errors.push({
+      field: "name",
+      message: `name must be at most ${SKILL_NAME_MAX_LENGTH} characters (got ${name.length})`
+    });
+    return errors;
+  }
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    errors.push({
+      field: "name",
+      message: "name must be lowercase alphanumeric with hyphens, no leading/trailing/consecutive hyphens"
+    });
+  }
+  if (name.includes("--")) {
+    errors.push({
+      field: "name",
+      message: "name must not contain consecutive hyphens"
+    });
+  }
+  return errors;
+}
+function validateSkillDescription(description) {
+  const errors = [];
+  if (description === void 0 || description === null) {
+    errors.push({ field: "description", message: "description is required" });
+    return errors;
+  }
+  if (typeof description !== "string") {
+    errors.push({ field: "description", message: "description must be a string" });
+    return errors;
+  }
+  if (description.trim().length === 0) {
+    errors.push({ field: "description", message: "description must not be empty" });
+    return errors;
+  }
+  if (description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+    errors.push({
+      field: "description",
+      message: `description must be at most ${SKILL_DESCRIPTION_MAX_LENGTH} characters (got ${description.length})`
+    });
+  }
+  return errors;
+}
+function validateSkillNameMatchesDir(name, dirName) {
+  if (name !== dirName) {
+    return [{
+      field: "name",
+      message: `name "${name}" must match parent directory name "${dirName}"`
+    }];
+  }
+  return [];
+}
+function parseSkillContent(content, dirName) {
+  let parsed;
+  try {
+    parsed = (0, import_gray_matter.default)(content);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to parse frontmatter: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const data = parsed.data;
+  const errors = [
+    ...validateSkillName(data.name),
+    ...validateSkillDescription(data.description)
+  ];
+  if (typeof data.name === "string" && data.name.length > 0 && SKILL_NAME_PATTERN.test(data.name)) {
+    errors.push(...validateSkillNameMatchesDir(data.name, dirName));
+  }
+  if (errors.length > 0) {
+    return {
+      success: false,
+      error: errors.map((e) => `${e.field}: ${e.message}`).join("; ")
+    };
+  }
+  const metadata = {
+    name: data.name,
+    description: data.description
+  };
+  if (data.license !== void 0) {
+    metadata.license = String(data.license);
+  }
+  if (Array.isArray(data.compatibility)) {
+    metadata.compatibility = data.compatibility.map(String);
+  }
+  if (data.metadata !== void 0 && typeof data.metadata === "object" && data.metadata !== null) {
+    metadata.metadata = data.metadata;
+  }
+  if (Array.isArray(data["allowed-tools"])) {
+    metadata.allowedTools = data["allowed-tools"].map(String);
+  }
+  return {
+    success: true,
+    metadata,
+    body: parsed.content
+  };
+}
+
+// src/skills/scanner.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var logger5 = createLogger("agentforge:core:skills:scanner", { level: "info" /* INFO */ });
+function expandHome(p) {
+  if (p.startsWith("~/") || p === "~") {
+    return (0, import_node_path.resolve)((0, import_node_os.homedir)(), p.slice(2));
+  }
+  return p;
+}
+function scanSkillRoot(rootPath) {
+  const resolvedRoot = (0, import_node_path.resolve)(expandHome(rootPath));
+  const candidates = [];
+  if (!(0, import_node_fs.existsSync)(resolvedRoot)) {
+    logger5.debug("Skill root does not exist, skipping", { rootPath: resolvedRoot });
+    return candidates;
+  }
+  let entries;
+  try {
+    entries = (0, import_node_fs.readdirSync)(resolvedRoot);
+  } catch (err) {
+    logger5.warn("Failed to read skill root directory", {
+      rootPath: resolvedRoot,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return candidates;
+  }
+  for (const entry of entries) {
+    const entryPath = (0, import_node_path.resolve)(resolvedRoot, entry);
+    let stat;
+    try {
+      stat = (0, import_node_fs.statSync)(entryPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) {
+      continue;
+    }
+    const skillMdPath = (0, import_node_path.resolve)(entryPath, "SKILL.md");
+    if (!(0, import_node_fs.existsSync)(skillMdPath)) {
+      continue;
+    }
+    try {
+      const content = (0, import_node_fs.readFileSync)(skillMdPath, "utf-8");
+      candidates.push({
+        skillPath: entryPath,
+        dirName: (0, import_node_path.basename)(entryPath),
+        content,
+        rootPath: resolvedRoot
+      });
+    } catch (err) {
+      logger5.warn("Failed to read SKILL.md", {
+        path: skillMdPath,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  logger5.debug("Scanned skill root", {
+    rootPath: resolvedRoot,
+    candidatesFound: candidates.length
+  });
+  return candidates;
+}
+function scanAllSkillRoots(skillRoots) {
+  const allCandidates = [];
+  for (const root of skillRoots) {
+    const candidates = scanSkillRoot(root);
+    allCandidates.push(...candidates);
+  }
+  logger5.info("Skill discovery complete", {
+    rootsScanned: skillRoots.length,
+    totalCandidates: allCandidates.length
+  });
+  return allCandidates;
+}
+
+// src/skills/activation.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_gray_matter2 = __toESM(require("gray-matter"), 1);
+var import_zod3 = require("zod");
+
+// src/skills/trust.ts
+var SCRIPT_PATH_PREFIX = "scripts/";
+var SCRIPT_PATH_EXACT = "scripts";
+function normalizeRootConfig(root) {
+  if (typeof root === "string") {
+    return { path: root, trust: "untrusted" };
+  }
+  return root;
+}
+function isScriptResource(resourcePath) {
+  let normalized = resourcePath.trim().replace(/\\/g, "/");
+  normalized = normalized.replace(/\/+/g, "/");
+  while (normalized.startsWith("./")) {
+    normalized = normalized.slice(2);
+  }
+  const lower = normalized.toLowerCase();
+  return lower === SCRIPT_PATH_EXACT || lower.startsWith(SCRIPT_PATH_PREFIX);
+}
+function evaluateTrustPolicy(resourcePath, trustLevel, allowUntrustedScripts = false) {
+  if (!isScriptResource(resourcePath)) {
+    return {
+      allowed: true,
+      reason: "not-script" /* NOT_SCRIPT */,
+      message: "Resource is not a script \u2014 no trust check required"
+    };
+  }
+  switch (trustLevel) {
+    case "workspace":
+      return {
+        allowed: true,
+        reason: "workspace-trust" /* WORKSPACE_TRUST */,
+        message: "Script allowed \u2014 skill root has workspace trust"
+      };
+    case "trusted":
+      return {
+        allowed: true,
+        reason: "trusted-root" /* TRUSTED_ROOT */,
+        message: "Script allowed \u2014 skill root is explicitly trusted"
+      };
+    case "untrusted":
+      if (allowUntrustedScripts) {
+        return {
+          allowed: true,
+          reason: "untrusted-script-allowed-override" /* UNTRUSTED_SCRIPT_ALLOWED */,
+          message: "Script from untrusted root allowed via allowUntrustedScripts override"
+        };
+      }
+      return {
+        allowed: false,
+        reason: "untrusted-script-denied" /* UNTRUSTED_SCRIPT_DENIED */,
+        message: `Script access denied \u2014 skill root is untrusted. Scripts from untrusted roots are blocked by default for security. To allow, set 'allowUntrustedScripts: true' in SkillRegistryConfig or promote the skill root to 'trusted' or 'workspace' trust level.`
+      };
+    default:
+      return {
+        allowed: false,
+        reason: "unknown-trust-level" /* UNKNOWN_TRUST_LEVEL */,
+        message: `Script access denied \u2014 trust level "${trustLevel}" is unknown and is treated as untrusted for security.`
+      };
+  }
+}
+
+// src/skills/activation.ts
+var logger6 = createLogger("agentforge:core:skills:activation", { level: "info" /* INFO */ });
+var activateSkillSchema = import_zod3.z.object({
+  name: import_zod3.z.string().describe('The name of the skill to activate (e.g., "code-review")')
+});
+var readSkillResourceSchema = import_zod3.z.object({
+  name: import_zod3.z.string().describe("The name of the skill that owns the resource"),
+  path: import_zod3.z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
+});
+function resolveResourcePath(skillPath, resourcePath) {
+  if ((0, import_node_path2.isAbsolute)(resourcePath)) {
+    return { success: false, error: "Absolute resource paths are not allowed" };
+  }
+  const segments = resourcePath.split(/[/\\]/);
+  if (segments.some((seg) => seg === "..")) {
+    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  }
+  const resolvedPath = (0, import_node_path2.resolve)(skillPath, resourcePath);
+  const resolvedSkillPath = (0, import_node_path2.resolve)(skillPath);
+  const rel = (0, import_node_path2.relative)(resolvedSkillPath, resolvedPath);
+  if (rel.startsWith("..") || (0, import_node_path2.resolve)(resolvedSkillPath, rel) !== resolvedPath) {
+    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  }
+  try {
+    const realSkillRoot = (0, import_node_fs2.realpathSync)(resolvedSkillPath);
+    const realTarget = (0, import_node_fs2.realpathSync)(resolvedPath);
+    const realRel = (0, import_node_path2.relative)(realSkillRoot, realTarget);
+    if (realRel.startsWith("..") || (0, import_node_path2.isAbsolute)(realRel)) {
+      return { success: false, error: "Symlink target escapes the skill directory \u2014 access denied" };
+    }
+  } catch {
+  }
+  return { success: true, resolvedPath };
+}
+function createActivateSkillTool(registry) {
+  return new ToolBuilder().name("activate-skill").description(
+    "Activate an Agent Skill by name, loading its full instructions. Returns the complete SKILL.md body content for the named skill. Use this when you see a relevant skill in <available_skills> and want to follow its instructions."
+  ).category("skills" /* SKILLS */).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const availableNames = registry.getNames();
+      const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
+      const errorMsg = `Skill "${name}" not found.${suggestion}`;
+      logger6.warn("Skill activation failed \u2014 not found", { name, availableCount: availableNames.length });
+      return errorMsg;
+    }
+    const skillMdPath = (0, import_node_path2.resolve)(skill.skillPath, "SKILL.md");
+    try {
+      const content = (0, import_node_fs2.readFileSync)(skillMdPath, "utf-8");
+      const body = extractBody(content);
+      logger6.info("Skill activated", {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length
+      });
+      registry.emitEvent("skill:activated" /* SKILL_ACTIVATED */, {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length
+      });
+      return body;
+    } catch (error) {
+      const errorMsg = `Failed to read skill "${name}" instructions: ${error instanceof Error ? error.message : String(error)}`;
+      logger6.error("Skill activation failed \u2014 read error", {
+        name,
+        skillPath: skill.skillPath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return errorMsg;
+    }
+  }).build();
+}
+function createReadSkillResourceTool(registry) {
+  return new ToolBuilder().name("read-skill-resource").description(
+    "Read a resource file from an activated Agent Skill. Returns the content of a file within the skill directory (e.g., references/, scripts/, assets/). The path must be relative to the skill root and cannot traverse outside it."
+  ).category("skills" /* SKILLS */).tags(["skill", "resource", "agent-skills"]).schema(readSkillResourceSchema).implement(async ({ name, path: resourcePath }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const availableNames = registry.getNames();
+      const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
+      const errorMsg = `Skill "${name}" not found.${suggestion}`;
+      logger6.warn("Skill resource load failed \u2014 skill not found", { name, resourcePath });
+      return errorMsg;
+    }
+    const pathResult = resolveResourcePath(skill.skillPath, resourcePath);
+    if (!pathResult.success) {
+      logger6.warn("Skill resource load blocked \u2014 path traversal", {
+        name,
+        resourcePath,
+        error: pathResult.error
+      });
+      return pathResult.error;
+    }
+    const policyDecision = evaluateTrustPolicy(
+      resourcePath,
+      skill.trustLevel,
+      registry.getAllowUntrustedScripts()
+    );
+    if (!policyDecision.allowed) {
+      logger6.warn("Skill resource load blocked \u2014 trust policy", {
+        name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      return policyDecision.message;
+    }
+    if (policyDecision.reason !== "not-script" /* NOT_SCRIPT */) {
+      logger6.info("Skill resource trust policy \u2014 allowed", {
+        name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason
+      });
+      registry.emitEvent("trust:policy-allowed" /* TRUST_POLICY_ALLOWED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason
+      });
+    }
+    try {
+      const content = (0, import_node_fs2.readFileSync)(pathResult.resolvedPath, "utf-8");
+      logger6.info("Skill resource loaded", {
+        name: skill.metadata.name,
+        resourcePath,
+        resolvedPath: pathResult.resolvedPath,
+        contentLength: content.length
+      });
+      registry.emitEvent("skill:resource-loaded" /* SKILL_RESOURCE_LOADED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        resolvedPath: pathResult.resolvedPath,
+        contentLength: content.length
+      });
+      return content;
+    } catch (error) {
+      const errorMsg = `Failed to read resource "${resourcePath}" from skill "${name}": ${error instanceof Error ? error.message : String(error)}`;
+      logger6.warn("Skill resource load failed \u2014 file not found or unreadable", {
+        name,
+        resourcePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return errorMsg;
+    }
+  }).build();
+}
+function createSkillActivationTools(registry) {
+  return [
+    createActivateSkillTool(registry),
+    createReadSkillResourceTool(registry)
+  ];
+}
+function extractBody(content) {
+  return (0, import_gray_matter2.default)(content).content.trim();
+}
+
+// src/skills/registry.ts
+var import_node_path3 = require("path");
+var logger7 = createLogger("agentforge:core:skills:registry", { level: "info" /* INFO */ });
+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 = (0, import_node_path3.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
+        });
+        logger7.warn("Skipping invalid skill", {
+          skillPath: candidate.skillPath,
+          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
+        });
+        logger7.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);
+      logger7.debug("Skill discovered", {
+        name: skill.metadata.name,
+        description: skill.metadata.description.slice(0, 80),
+        skillPath: skill.skillPath
+      });
+    }
+    logger7.info("Skill registry populated", {
+      rootsScanned: this.config.skillRoots.length,
+      skillsDiscovered: successCount,
+      warnings: warningCount
+    });
+  }
+  // ─── 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}`);
+   * ```
+   */
+  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!');
+   * }
+   * ```
+   */
+  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`);
+   * ```
+   */
+  size() {
+    return this.skills.size;
+  }
+  /**
+   * 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
+   */
+  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
+   */
+  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');
+   * ```
+   */
+  generatePrompt(options) {
+    if (!this.config.enabled) {
+      logger7.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) {
+      logger7.debug("Skill prompt generation produced empty result", {
+        totalDiscovered: this.size(),
+        filterApplied: !!(options?.skills && options.skills.length > 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);
+    logger7.info("Skill prompt generated", {
+      skillCount: skills.length,
+      totalDiscovered: this.size(),
+      filterApplied: !!(options?.skills && options.skills.length > 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);
+   * });
+   * ```
+   */
+  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);
+    }
+  }
+  /**
+   * 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) {
+          logger7.error("Skill event handler error", {
+            event,
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : void 0
+          });
+        }
+      });
+    }
+  }
+  /**
+   * 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);
+  }
+};
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentError,
@@ -5501,6 +6354,8 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   MissingDescriptionError,
   Profiler,
   RegistryEvent,
+  SkillRegistry,
+  SkillRegistryEvent,
   TimeoutError,
   ToolBuilder,
   ToolCategory,
@@ -5510,6 +6365,7 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   ToolNameSchema,
   ToolRegistry,
   ToolRelationsSchema,
+  TrustPolicyReason,
   batch,
   broadcast,
   cache,
@@ -5523,6 +6379,7 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   composeWithOptions,
   conditional,
   configureLangSmith,
+  createActivateSkillTool,
   createAlertManager,
   createApprovalRequiredInterrupt,
   createAuditLogger,
@@ -5551,11 +6408,13 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   createParallelWorkflow,
   createProfiler,
   createProgressTracker,
+  createReadSkillResourceTool,
   createSSEFormatter,
   createSequentialWorkflow,
   createSharedCache,
   createSharedConcurrencyController,
   createSharedRateLimiter,
+  createSkillActivationTools,
   createSqliteCheckpointer,
   createStateAnnotation,
   createSubgraph,
@@ -5566,6 +6425,8 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   createToolUnsafe,
   createWebSocketHandler,
   development,
+  evaluateTrustPolicy,
+  expandHome,
   filter,
   formatAgentResumedEvent,
   formatAgentWaitingEvent,
@@ -5585,20 +6446,26 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   isCustomInterrupt,
   isHumanRequestInterrupt,
   isMemoryCheckpointer,
+  isScriptResource,
   isTracingEnabled,
   loadPrompt,
   map,
   merge,
   mergeState,
+  normalizeRootConfig,
   parallel,
   parseSSEEvent,
+  parseSkillContent,
   presets,
   production,
   reduce,
   renderTemplate,
+  resolveResourcePath,
   retry,
   safeValidateSchemaDescriptions,
   sanitizeValue,
+  scanAllSkillRoots,
+  scanSkillRoot,
   sendMessage,
   sequential,
   sequentialBuilder,
@@ -5610,6 +6477,9 @@ function loadPrompt(promptName, options = {}, promptsDir) {
   toLangChainTools,
   toolBuilder,
   validateSchemaDescriptions,
+  validateSkillDescription,
+  validateSkillName,
+  validateSkillNameMatchesDir,
   validateState,
   validateTool,
   validateToolMetadata,