@agentforge/skills 0.17.1 → 0.18.0

package/README.md

@@ -20,10 +20,30 @@ yarn add @agentforge/skills
 
 ## Overview
 
-`@agentforge/skills` provides the skill discovery, registration, activation, and trust policy engine for AgentForge agents. It implements the [Agent Skills Specification](https://agentskills.io) for composable, modular agent capabilities.
+`@agentforge/skills` provides Agent Skill discovery, registration, access, and trust policy enforcement for AgentForge agents. Within Agent Skill access, Skill activation loads trusted instructions while resource access loads supporting files. It implements the [Agent Skills Specification](https://agentskills.io) for composable, modular agent capabilities.
 
 Full source code and API will be available after ST-07002 (Move Skills Source Files). See the [AgentForge docs](https://tvscoundrel.github.io/agentforge/) for usage guides and tutorials.
 
+## Agent Skill Access
+
+Access Agent Skill instructions and supporting resources through the Tools bound
+to a `SkillRegistry`:
+
+```typescript
+import { SkillRegistry } from '@agentforge/skills';
+
+const registry = new SkillRegistry({
+  enabled: true,
+  skillRoots: [{ path: '.agentskills', trust: 'workspace' }],
+});
+
+const [activateSkill, readSkillResource] = registry.toActivationTools();
+```
+
+`resolveResourcePath` remains exported for compatibility, but it is deprecated
+and planned for removal in the next major release. Use the
+`read-skill-resource` Tool for Agent Skill resource access instead.
+
 ## License
 
 MIT — see [LICENSE](../../LICENSE) for details.

package/dist/index.cjs

@@ -223,23 +223,12 @@ function scanAllSkillRoots(skillRoots) {
 function extractBody(content) {
   return matter__default.default(content).content.trim();
 }
-var activateSkillSchema = zod.z.object({
-  name: zod.z.string().describe('The name of the skill to activate (e.g., "code-review")')
-});
-var readSkillResourceSchema = zod.z.object({
-  name: zod.z.string().describe("The name of the skill that owns the resource"),
-  path: zod.z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
-});
 var activationLogger = core.createLogger("agentforge:skills:activation", {
   level: core.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
@@ -331,114 +320,96 @@ function evaluateSkillActivationPolicy(trustLevel) {
   }
 }
 
-// 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) {
+// 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 (path.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 = path.resolve(skillPath, resourcePath);
   const resolvedSkillPath = path.resolve(skillPath);
-  const rel = path.relative(resolvedSkillPath, resolvedPath);
-  if (rel.startsWith("..") || path.resolve(resolvedSkillPath, rel) !== resolvedPath) {
-    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  const resolvedPath = path.resolve(resolvedSkillPath, resourcePath);
+  const lexicalRelativePath = path.relative(resolvedSkillPath, resolvedPath);
+  if (lexicalRelativePath.startsWith("..") || path.isAbsolute(lexicalRelativePath) || path.resolve(resolvedSkillPath, lexicalRelativePath) !== resolvedPath) {
+    return { kind: "access-denied", message: PATH_TRAVERSAL_MESSAGE };
   }
+  let canonicalSkillPath;
   try {
-    const realSkillRoot = fs.realpathSync(resolvedSkillPath);
-    const realTarget = fs.realpathSync(resolvedPath);
-    const realRel = path.relative(realSkillRoot, realTarget);
-    if (realRel.startsWith("..") || path.isAbsolute(realRel)) {
-      return { success: false, error: "Symlink target escapes the skill directory \u2014 access denied" };
+    canonicalSkillPath = fs.realpathSync(resolvedSkillPath);
+  } catch (error) {
+    return { kind: "read-failure", error: formatResourceReadError(error, resolvedPath) };
+  }
+  let canonicalPath;
+  try {
+    canonicalPath = fs.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 = path.relative(canonicalSkillPath, canonicalPath);
+  if (canonicalRelativePath.startsWith("..") || path.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 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. 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);
+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 = path.resolve(skill.skillPath, "SKILL.md");
     let isSkillInstructions = pathResult.resolvedPath.toLowerCase() === skillInstructionsPath.toLowerCase();
-    if (!isSkillInstructions) {
+    if (!isSkillInstructions && pathResult.kind === "success") {
       try {
-        isSkillInstructions = fs.realpathSync(pathResult.resolvedPath).toLowerCase() === fs.realpathSync(skillInstructionsPath).toLowerCase();
+        isSkillInstructions = pathResult.canonicalPath.toLowerCase() === fs.realpathSync(skillInstructionsPath).toLowerCase();
       } catch {
       }
     }
@@ -452,20 +423,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", {
@@ -475,14 +450,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", {
@@ -491,28 +470,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 = fs.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 = fs.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", {
@@ -520,10 +500,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 = fs.readFileSync(path.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 = zod.z.object({
+  name: zod.z.string().describe('The name of the skill to activate (e.g., "code-review")')
+});
+var readSkillResourceSchema = zod.z.object({
+  name: zod.z.string().describe("The name of the skill that owns the resource"),
+  path: zod.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 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 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 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. 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 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 (path.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 = path.resolve(skillPath, resourcePath);
+  const resolvedSkillPath = path.resolve(skillPath);
+  const rel = path.relative(resolvedSkillPath, resolvedPath);
+  if (rel.startsWith("..") || path.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 = fs.realpathSync(resolvedSkillPath);
+    const realTarget = fs.realpathSync(resolvedPath);
+    const realRel = path.relative(realSkillRoot, realTarget);
+    if (realRel.startsWith("..") || path.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) {