@agentforge/skills 0.17.1 → 0.18.0

package/dist/index.js

@@ -217,23 +217,12 @@ function scanAllSkillRoots(skillRoots) {
 function extractBody(content) {
   return matter(content).content.trim();
 }
-var activateSkillSchema = z.object({
-  name: z.string().describe('The name of the skill to activate (e.g., "code-review")')
-});
-var readSkillResourceSchema = z.object({
-  name: z.string().describe("The name of the skill that owns the resource"),
-  path: z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
-});
 var activationLogger = createLogger("agentforge:skills:activation", {
   level: LogLevel.INFO
 });
-function buildMissingSkillMessage(registry, name) {
-  const availableNames = registry.getNames();
+function formatMissingSkillMessage(name, availableNames) {
   const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
-  return {
-    availableCount: availableNames.length,
-    errorMessage: `Skill "${name}" not found.${suggestion}`
-  };
+  return `Skill "${name}" not found.${suggestion}`;
 }
 
 // src/trust.ts
@@ -325,114 +314,96 @@ function evaluateSkillActivationPolicy(trustLevel) {
   }
 }
 
-// src/activation-activate-tool.ts
-function createActivateSkillTool(registry) {
-  return new 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(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 = resolve(skill.skillPath, "SKILL.md");
-    try {
-      const content = 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) {
+// src/agent-skill-access.ts
+var PATH_TRAVERSAL_MESSAGE = "Path traversal is not allowed \u2014 resource paths must stay within the skill directory";
+var SYMLINK_ESCAPE_MESSAGE = "Symlink target escapes the skill directory \u2014 access denied";
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function formatResourceReadError(error, resolvedPath) {
+  const message = formatError(error);
+  const detailIndex = message.indexOf(", ");
+  const prefix = detailIndex === -1 ? message : message.slice(0, detailIndex);
+  return `${prefix}, open '${resolvedPath}'`;
+}
+function resolveCanonicalResourcePath(skillPath, resourcePath) {
   if (isAbsolute(resourcePath)) {
-    return { success: false, error: "Absolute resource paths are not allowed" };
+    return { kind: "access-denied", message: "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" };
+  if (resourcePath.split(/[/\\]/).some((segment) => segment === "..")) {
+    return { kind: "access-denied", message: PATH_TRAVERSAL_MESSAGE };
   }
-  const resolvedPath = resolve(skillPath, resourcePath);
   const resolvedSkillPath = resolve(skillPath);
-  const rel = relative(resolvedSkillPath, resolvedPath);
-  if (rel.startsWith("..") || resolve(resolvedSkillPath, rel) !== resolvedPath) {
-    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  const resolvedPath = resolve(resolvedSkillPath, resourcePath);
+  const lexicalRelativePath = relative(resolvedSkillPath, resolvedPath);
+  if (lexicalRelativePath.startsWith("..") || isAbsolute(lexicalRelativePath) || resolve(resolvedSkillPath, lexicalRelativePath) !== resolvedPath) {
+    return { kind: "access-denied", message: PATH_TRAVERSAL_MESSAGE };
   }
+  let canonicalSkillPath;
   try {
-    const realSkillRoot = realpathSync(resolvedSkillPath);
-    const realTarget = realpathSync(resolvedPath);
-    const realRel = relative(realSkillRoot, realTarget);
-    if (realRel.startsWith("..") || isAbsolute(realRel)) {
-      return { success: false, error: "Symlink target escapes the skill directory \u2014 access denied" };
+    canonicalSkillPath = realpathSync(resolvedSkillPath);
+  } catch (error) {
+    return { kind: "read-failure", error: formatResourceReadError(error, resolvedPath) };
+  }
+  let canonicalPath;
+  try {
+    canonicalPath = realpathSync(resolvedPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {
+        kind: "resource-not-found",
+        resolvedPath,
+        error: formatResourceReadError(error, resolvedPath)
+      };
     }
-  } catch {
+    return {
+      kind: "target-read-failure",
+      resolvedPath,
+      error: formatResourceReadError(error, resolvedPath)
+    };
   }
-  return { success: true, resolvedPath };
+  const canonicalRelativePath = relative(canonicalSkillPath, canonicalPath);
+  if (canonicalRelativePath.startsWith("..") || isAbsolute(canonicalRelativePath)) {
+    return { kind: "access-denied", message: SYMLINK_ESCAPE_MESSAGE };
+  }
+  return { kind: "success", resolvedPath, canonicalPath, canonicalRelativePath };
 }
-
-// src/activation-resource-tool.ts
-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. SKILL.md is only readable from workspace or trusted roots."
-  ).category(ToolCategory.SKILLS).tags(["skill", "resource", "agent-skills"]).schema(readSkillResourceSchema).implement(async ({ name, path: resourcePath }) => {
-    const skill = registry.get(name);
+var AgentSkillAccess = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  async readResource(name, resourcePath) {
+    const skill = this.registry.get(name);
     if (!skill) {
-      const { errorMessage } = buildMissingSkillMessage(registry, name);
-      activationLogger.warn("Skill resource load failed \u2014 skill not found", { name, resourcePath });
-      return errorMessage;
+      const availableNames = this.registry.getNames();
+      activationLogger.warn("Skill resource load failed \u2014 skill not found", {
+        name,
+        resourcePath
+      });
+      return { kind: "skill-not-found", name, availableNames };
     }
-    const pathResult = resolveResourcePath(skill.skillPath, resourcePath);
-    if (!pathResult.success) {
+    const pathResult = resolveCanonicalResourcePath(skill.skillPath, resourcePath);
+    if (pathResult.kind === "access-denied") {
       activationLogger.warn("Skill resource load blocked \u2014 path traversal", {
+        name,
+        resourcePath,
+        error: pathResult.message
+      });
+      return pathResult;
+    }
+    if (pathResult.kind === "read-failure") {
+      activationLogger.warn("Skill resource load failed \u2014 file not found or unreadable", {
         name,
         resourcePath,
         error: pathResult.error
       });
-      return pathResult.error;
+      return { ...pathResult, name, resourcePath };
     }
     const skillInstructionsPath = resolve(skill.skillPath, "SKILL.md");
     let isSkillInstructions = pathResult.resolvedPath.toLowerCase() === skillInstructionsPath.toLowerCase();
-    if (!isSkillInstructions) {
+    if (!isSkillInstructions && pathResult.kind === "success") {
       try {
-        isSkillInstructions = realpathSync(pathResult.resolvedPath).toLowerCase() === realpathSync(skillInstructionsPath).toLowerCase();
+        isSkillInstructions = pathResult.canonicalPath.toLowerCase() === realpathSync(skillInstructionsPath).toLowerCase();
       } catch {
       }
     }
@@ -446,20 +417,24 @@ function createReadSkillResourceTool(registry) {
           reason: activationDecision.reason,
           message: activationDecision.message
         });
-        registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+        this.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;
+        return {
+          kind: "access-denied",
+          reason: activationDecision.reason,
+          message: activationDecision.message
+        };
       }
     }
     const policyDecision = evaluateTrustPolicy(
-      resourcePath,
+      pathResult.kind === "success" ? pathResult.canonicalRelativePath : resourcePath,
       skill.trustLevel,
-      registry.getAllowUntrustedScripts()
+      this.registry.getAllowUntrustedScripts()
     );
     if (!policyDecision.allowed) {
       activationLogger.warn("Skill resource load blocked \u2014 trust policy", {
@@ -469,14 +444,18 @@ function createReadSkillResourceTool(registry) {
         reason: policyDecision.reason,
         message: policyDecision.message
       });
-      registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+      this.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;
+      return {
+        kind: "access-denied",
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      };
     }
     if (policyDecision.reason !== "not-script" /* NOT_SCRIPT */) {
       activationLogger.info("Skill resource trust policy \u2014 allowed", {
@@ -485,28 +464,29 @@ function createReadSkillResourceTool(registry) {
         trustLevel: skill.trustLevel,
         reason: policyDecision.reason
       });
-      registry.emitEvent("trust:policy-allowed" /* TRUST_POLICY_ALLOWED */, {
+      this.registry.emitEvent("trust:policy-allowed" /* TRUST_POLICY_ALLOWED */, {
         name: skill.metadata.name,
         resourcePath,
         trustLevel: skill.trustLevel,
         reason: policyDecision.reason
       });
     }
-    try {
-      const content = readFileSync(pathResult.resolvedPath, "utf-8");
-      activationLogger.info("Skill resource loaded", {
-        name: skill.metadata.name,
+    if (pathResult.kind === "resource-not-found" || pathResult.kind === "target-read-failure") {
+      activationLogger.warn("Skill resource load failed \u2014 file not found or unreadable", {
+        name,
         resourcePath,
-        resolvedPath: pathResult.resolvedPath,
-        contentLength: content.length
+        error: pathResult.error
       });
-      registry.emitEvent("skill:resource-loaded" /* SKILL_RESOURCE_LOADED */, {
-        name: skill.metadata.name,
+      return {
+        kind: pathResult.kind === "resource-not-found" ? "resource-not-found" : "read-failure",
+        name,
         resourcePath,
-        resolvedPath: pathResult.resolvedPath,
-        contentLength: content.length
-      });
-      return content;
+        error: pathResult.error
+      };
+    }
+    let content;
+    try {
+      content = readFileSync(pathResult.canonicalPath, "utf-8");
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       activationLogger.warn("Skill resource load failed \u2014 file not found or unreadable", {
@@ -514,10 +494,156 @@ function createReadSkillResourceTool(registry) {
         resourcePath,
         error: message
       });
-      return `Failed to read resource "${resourcePath}" from skill "${name}": ${message}`;
+      if (error.code === "ENOENT") {
+        return { kind: "resource-not-found", name, resourcePath, error: message };
+      }
+      return { kind: "read-failure", name, resourcePath, error: message };
+    }
+    activationLogger.info("Skill resource loaded", {
+      name: skill.metadata.name,
+      resourcePath,
+      resolvedPath: pathResult.resolvedPath,
+      contentLength: content.length
+    });
+    this.registry.emitEvent("skill:resource-loaded" /* SKILL_RESOURCE_LOADED */, {
+      name: skill.metadata.name,
+      resourcePath,
+      resolvedPath: pathResult.resolvedPath,
+      contentLength: content.length
+    });
+    return { kind: "success", content };
+  }
+  async activate(name) {
+    const skill = this.registry.get(name);
+    if (!skill) {
+      const availableNames = this.registry.getNames();
+      activationLogger.warn("Skill activation failed \u2014 not found", {
+        name,
+        availableCount: availableNames.length
+      });
+      return { kind: "skill-not-found", name, availableNames };
+    }
+    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
+      });
+      this.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 {
+        kind: "access-denied",
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      };
+    }
+    let body;
+    try {
+      const content = readFileSync(resolve(skill.skillPath, "SKILL.md"), "utf-8");
+      body = extractBody(content);
+    } 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 { kind: "read-failure", name, error: message };
+    }
+    activationLogger.info("Skill activated", {
+      name: skill.metadata.name,
+      skillPath: skill.skillPath,
+      bodyLength: body.length,
+      trustLevel: skill.trustLevel,
+      activationReason: policyDecision.reason
+    });
+    this.registry.emitEvent("skill:activated" /* SKILL_ACTIVATED */, {
+      name: skill.metadata.name,
+      skillPath: skill.skillPath,
+      bodyLength: body.length,
+      trustLevel: skill.trustLevel
+    });
+    return { kind: "success", body };
+  }
+};
+var activateSkillSchema = z.object({
+  name: z.string().describe('The name of the skill to activate (e.g., "code-review")')
+});
+var readSkillResourceSchema = z.object({
+  name: z.string().describe("The name of the skill that owns the resource"),
+  path: z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
+});
+
+// src/activation-activate-tool.ts
+function createActivateSkillTool(registry) {
+  const access = new AgentSkillAccess(registry);
+  return new 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(ToolCategory.SKILLS).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
+    const result = await access.activate(name);
+    switch (result.kind) {
+      case "success":
+        return result.body;
+      case "skill-not-found":
+        return formatMissingSkillMessage(result.name, result.availableNames);
+      case "access-denied":
+        return result.message;
+      case "read-failure":
+        return `Failed to read skill "${result.name}" instructions: ${result.error}`;
+    }
+  }).build();
+}
+function createReadSkillResourceTool(registry) {
+  const access = new AgentSkillAccess(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. SKILL.md is only readable from workspace or trusted roots."
+  ).category(ToolCategory.SKILLS).tags(["skill", "resource", "agent-skills"]).schema(readSkillResourceSchema).implement(async ({ name, path: resourcePath }) => {
+    const result = await access.readResource(name, resourcePath);
+    switch (result.kind) {
+      case "success":
+        return result.content;
+      case "skill-not-found":
+        return formatMissingSkillMessage(result.name, result.availableNames);
+      case "access-denied":
+        return result.message;
+      case "resource-not-found":
+      case "read-failure":
+        return `Failed to read resource "${result.resourcePath}" from skill "${result.name}": ${result.error}`;
     }
   }).build();
 }
+function resolveResourcePath(skillPath, resourcePath) {
+  if (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 = resolve(skillPath, resourcePath);
+  const resolvedSkillPath = resolve(skillPath);
+  const rel = relative(resolvedSkillPath, resolvedPath);
+  if (rel.startsWith("..") || 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 = realpathSync(resolvedSkillPath);
+    const realTarget = realpathSync(resolvedPath);
+    const realRel = relative(realSkillRoot, realTarget);
+    if (realRel.startsWith("..") || isAbsolute(realRel)) {
+      return { success: false, error: "Symlink target escapes the skill directory \u2014 access denied" };
+    }
+  } catch {
+  }
+  return { success: true, resolvedPath };
+}
 
 // src/activation.ts
 function createSkillActivationTools(registry) {