@agentforge/skills 0.16.74 → 0.16.76

package/dist/index.cjs

@@ -16,6 +16,9 @@ var TrustPolicyReason = /* @__PURE__ */ ((TrustPolicyReason2) => {
   TrustPolicyReason2["NOT_SCRIPT"] = "not-script";
   TrustPolicyReason2["WORKSPACE_TRUST"] = "workspace-trust";
   TrustPolicyReason2["TRUSTED_ROOT"] = "trusted-root";
+  TrustPolicyReason2["WORKSPACE_SKILL_ACTIVATION"] = "workspace-skill-activation";
+  TrustPolicyReason2["TRUSTED_SKILL_ACTIVATION"] = "trusted-skill-activation";
+  TrustPolicyReason2["UNTRUSTED_SKILL_ACTIVATION_DENIED"] = "untrusted-skill-activation-denied";
   TrustPolicyReason2["UNTRUSTED_SCRIPT_DENIED"] = "untrusted-script-denied";
   TrustPolicyReason2["UNTRUSTED_SCRIPT_ALLOWED"] = "untrusted-script-allowed-override";
   TrustPolicyReason2["UNKNOWN_TRUST_LEVEL"] = "unknown-trust-level";
@@ -239,44 +242,6 @@ function buildMissingSkillMessage(registry, name) {
   };
 }
 
-// src/activation-activate-tool.ts
-function createActivateSkillTool(registry) {
-  return new core.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(core.ToolCategory.SKILLS).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
-    const skill = registry.get(name);
-    if (!skill) {
-      const { availableCount, errorMessage } = buildMissingSkillMessage(registry, name);
-      activationLogger.warn("Skill activation failed \u2014 not found", { name, availableCount });
-      return errorMessage;
-    }
-    const skillMdPath = path.resolve(skill.skillPath, "SKILL.md");
-    try {
-      const content = fs.readFileSync(skillMdPath, "utf-8");
-      const body = extractBody(content);
-      activationLogger.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 message = error instanceof Error ? error.message : String(error);
-      activationLogger.error("Skill activation failed \u2014 read error", {
-        name,
-        skillPath: skill.skillPath,
-        error: message
-      });
-      return `Failed to read skill "${name}" instructions: ${message}`;
-    }
-  }).build();
-}
-
 // src/trust.ts
 var SCRIPT_PATH_PREFIX = "scripts/";
 var SCRIPT_PATH_EXACT = "scripts";
@@ -337,6 +302,92 @@ function evaluateTrustPolicy(resourcePath, trustLevel, allowUntrustedScripts = f
       };
   }
 }
+function evaluateSkillActivationPolicy(trustLevel) {
+  switch (trustLevel) {
+    case "workspace":
+      return {
+        allowed: true,
+        reason: "workspace-skill-activation" /* WORKSPACE_SKILL_ACTIVATION */,
+        message: "Skill activation allowed \u2014 skill root has workspace trust"
+      };
+    case "trusted":
+      return {
+        allowed: true,
+        reason: "trusted-skill-activation" /* TRUSTED_SKILL_ACTIVATION */,
+        message: "Skill activation allowed \u2014 skill root is explicitly trusted"
+      };
+    case "untrusted":
+      return {
+        allowed: false,
+        reason: "untrusted-skill-activation-denied" /* UNTRUSTED_SKILL_ACTIVATION_DENIED */,
+        message: `Skill activation blocked \u2014 skill root is untrusted. Untrusted skills remain discoverable, but their full SKILL.md bodies are blocked by default. Promote the skill root to 'trusted' or 'workspace' trust level after review to allow activation.`
+      };
+    default:
+      return {
+        allowed: false,
+        reason: "unknown-trust-level" /* UNKNOWN_TRUST_LEVEL */,
+        message: `Skill activation blocked \u2014 trust level "${trustLevel}" is unknown and is treated as untrusted for security.`
+      };
+  }
+}
+
+// src/activation-activate-tool.ts
+function createActivateSkillTool(registry) {
+  return new core.ToolBuilder().name("activate-skill").description(
+    "Activate an Agent Skill by name, loading its full instructions for trusted roots. Returns the complete SKILL.md body content for workspace or explicitly trusted skills. Use this when you see a relevant skill in <available_skills> or <untrusted_skills>; activation is blocked for untrusted roots until they are promoted."
+  ).category(core.ToolCategory.SKILLS).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const { availableCount, errorMessage } = buildMissingSkillMessage(registry, name);
+      activationLogger.warn("Skill activation failed \u2014 not found", { name, availableCount });
+      return errorMessage;
+    }
+    const policyDecision = evaluateSkillActivationPolicy(skill.trustLevel);
+    if (!policyDecision.allowed) {
+      activationLogger.warn("Skill activation blocked \u2014 trust policy", {
+        name,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+        name: skill.metadata.name,
+        resourcePath: "SKILL.md",
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      return policyDecision.message;
+    }
+    const skillMdPath = path.resolve(skill.skillPath, "SKILL.md");
+    try {
+      const content = fs.readFileSync(skillMdPath, "utf-8");
+      const body = extractBody(content);
+      activationLogger.info("Skill activated", {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length,
+        trustLevel: skill.trustLevel,
+        activationReason: policyDecision.reason
+      });
+      registry.emitEvent("skill:activated" /* SKILL_ACTIVATED */, {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length,
+        trustLevel: skill.trustLevel
+      });
+      return body;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      activationLogger.error("Skill activation failed \u2014 read error", {
+        name,
+        skillPath: skill.skillPath,
+        error: message
+      });
+      return `Failed to read skill "${name}" instructions: ${message}`;
+    }
+  }).build();
+}
 function resolveResourcePath(skillPath, resourcePath) {
   if (path.isAbsolute(resourcePath)) {
     return { success: false, error: "Absolute resource paths are not allowed" };
@@ -366,7 +417,7 @@ function resolveResourcePath(skillPath, resourcePath) {
 // src/activation-resource-tool.ts
 function createReadSkillResourceTool(registry) {
   return new core.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."
+    "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. SKILL.md is only readable from workspace or trusted roots."
   ).category(core.ToolCategory.SKILLS).tags(["skill", "resource", "agent-skills"]).schema(readSkillResourceSchema).implement(async ({ name, path: resourcePath }) => {
     const skill = registry.get(name);
     if (!skill) {
@@ -383,6 +434,34 @@ function createReadSkillResourceTool(registry) {
       });
       return pathResult.error;
     }
+    const skillInstructionsPath = path.resolve(skill.skillPath, "SKILL.md");
+    let isSkillInstructions = pathResult.resolvedPath.toLowerCase() === skillInstructionsPath.toLowerCase();
+    if (!isSkillInstructions) {
+      try {
+        isSkillInstructions = fs.realpathSync(pathResult.resolvedPath).toLowerCase() === fs.realpathSync(skillInstructionsPath).toLowerCase();
+      } catch {
+      }
+    }
+    if (isSkillInstructions) {
+      const activationDecision = evaluateSkillActivationPolicy(skill.trustLevel);
+      if (!activationDecision.allowed) {
+        activationLogger.warn("Skill resource load blocked \u2014 skill instructions trust policy", {
+          name,
+          resourcePath,
+          trustLevel: skill.trustLevel,
+          reason: activationDecision.reason,
+          message: activationDecision.message
+        });
+        registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+          name: skill.metadata.name,
+          resourcePath: "SKILL.md",
+          trustLevel: skill.trustLevel,
+          reason: activationDecision.reason,
+          message: activationDecision.message
+        });
+        return activationDecision.message;
+      }
+    }
     const policyDecision = evaluateTrustPolicy(
       resourcePath,
       skill.trustLevel,
@@ -569,10 +648,19 @@ function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
     const requested = new Set(options.skills);
     skills = skills.filter((skill) => requested.has(skill.metadata.name));
   }
+  let trustedSkills = skills.filter(
+    (skill) => skill.trustLevel === "workspace" || skill.trustLevel === "trusted"
+  );
+  let untrustedSkills = skills.filter(
+    (skill) => skill.trustLevel !== "workspace" && skill.trustLevel !== "trusted"
+  );
   if (config.maxDiscoveredSkills !== void 0 && config.maxDiscoveredSkills >= 0) {
-    skills = skills.slice(0, config.maxDiscoveredSkills);
+    const trustedLimit = Math.min(config.maxDiscoveredSkills, trustedSkills.length);
+    trustedSkills = trustedSkills.slice(0, trustedLimit);
+    untrustedSkills = untrustedSkills.slice(0, config.maxDiscoveredSkills - trustedLimit);
+    skills = [...trustedSkills, ...untrustedSkills];
   }
-  if (skills.length === 0) {
+  if (trustedSkills.length === 0 && untrustedSkills.length === 0) {
     logger4.debug("Skill prompt generation produced empty result", {
       totalDiscovered,
       filterApplied: !!(options?.skills && options.skills.length > 0),
@@ -580,12 +668,21 @@ function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
     });
     return "";
   }
-  const xml = `<available_skills>
-${skills.map(renderSkillEntry).join("\n")}
-</available_skills>`;
+  const sections = [];
+  if (trustedSkills.length > 0) {
+    sections.push(`<available_skills>
+${trustedSkills.map(renderTrustedSkillEntry).join("\n")}
+</available_skills>`);
+  }
+  if (untrustedSkills.length > 0) {
+    sections.push(renderUntrustedSkillsSection(untrustedSkills));
+  }
+  const xml = sections.join("\n");
   const estimatedTokens = Math.ceil(xml.length / 4);
   logger4.info("Skill prompt generated", {
     skillCount: skills.length,
+    trustedSkillCount: trustedSkills.length,
+    untrustedSkillCount: untrustedSkills.length,
     totalDiscovered,
     filterApplied: !!(options?.skills && options.skills.length > 0),
     ...config.maxDiscoveredSkills !== void 0 ? { maxCap: config.maxDiscoveredSkills } : {},
@@ -594,12 +691,32 @@ ${skills.map(renderSkillEntry).join("\n")}
   });
   return xml;
 }
-function renderSkillEntry(skill) {
+function renderTrustedSkillEntry(skill) {
+  return [
+    "  <skill>",
+    `    <name>${escapeXml(skill.metadata.name)}</name>`,
+    `    <description>${escapeXml(skill.metadata.description)}</description>`,
+    `    <location>${escapeXml(skill.skillPath)}</location>`,
+    `    <trust>${escapeXml(skill.trustLevel)}</trust>`,
+    "  </skill>"
+  ].join("\n");
+}
+function renderUntrustedSkillsSection(skills) {
+  return [
+    "<untrusted_skills>",
+    "  <trust_notice>Untrusted skills are discoverable, but their full SKILL.md bodies stay blocked until the root is promoted to trusted or workspace status.</trust_notice>",
+    ...skills.map(renderUntrustedSkillEntry),
+    "</untrusted_skills>"
+  ].join("\n");
+}
+function renderUntrustedSkillEntry(skill) {
   return [
     "  <skill>",
     `    <name>${escapeXml(skill.metadata.name)}</name>`,
     `    <description>${escapeXml(skill.metadata.description)}</description>`,
     `    <location>${escapeXml(skill.skillPath)}</location>`,
+    `    <trust>${escapeXml(skill.trustLevel)}</trust>`,
+    "    <activation_policy>requires-trusted-root</activation_policy>",
     "  </skill>"
   ].join("\n");
 }
@@ -696,6 +813,7 @@ exports.TrustPolicyReason = TrustPolicyReason;
 exports.createActivateSkillTool = createActivateSkillTool;
 exports.createReadSkillResourceTool = createReadSkillResourceTool;
 exports.createSkillActivationTools = createSkillActivationTools;
+exports.evaluateSkillActivationPolicy = evaluateSkillActivationPolicy;
 exports.evaluateTrustPolicy = evaluateTrustPolicy;
 exports.expandHome = expandHome;
 exports.isScriptResource = isScriptResource;