@poncho-ai/harness 0.2.0 → 0.3.1

package/src/skill-context.ts

@@ -1,6 +1,7 @@
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, resolve, normalize } from "node:path";
 import YAML from "yaml";
+import { validateMcpPattern, validateScriptPattern } from "./tool-policy.js";
 
 // ---------------------------------------------------------------------------
 // Skill directory scanning — default directories and ecosystem compatibility
@@ -36,8 +37,11 @@ export interface SkillMetadata {
   name: string;
   /** What the skill does and when to use it. */
   description: string;
-  /** Tool hints declared in frontmatter (spec `allowed-tools` or legacy `tools`). */
-  tools: string[];
+  /** Tool intent declared in frontmatter. */
+  tools: {
+    mcp: string[];
+    scripts: string[];
+  };
   /** Absolute path to the skill directory. */
   skillDir: string;
   /** Absolute path to the SKILL.md file. */
@@ -64,7 +68,7 @@ const asRecord = (value: unknown): Record<string, unknown> =>
 
 const parseSkillFrontmatter = (
   content: string,
-): { name: string; description: string; tools: string[] } | undefined => {
+): { name: string; description: string; tools: { mcp: string[]; scripts: string[] } } | undefined => {
   const match = content.match(FRONTMATTER_PATTERN);
   if (!match) {
     return undefined;
@@ -80,6 +84,13 @@ const parseSkillFrontmatter = (
   const description =
     typeof parsed.description === "string" ? parsed.description.trim() : "";
 
+  const toolsValue = asRecord(parsed.tools);
+  const modernMcp = Array.isArray(toolsValue.mcp)
+    ? toolsValue.mcp.filter((tool): tool is string => typeof tool === "string")
+    : [];
+  const modernScripts = Array.isArray(toolsValue.scripts)
+    ? toolsValue.scripts.filter((tool): tool is string => typeof tool === "string")
+    : [];
   const allowedToolsValue = parsed["allowed-tools"];
   const allowedTools =
     typeof allowedToolsValue === "string"
@@ -88,15 +99,25 @@ const parseSkillFrontmatter = (
           .map((tool) => tool.trim())
           .filter((tool) => tool.length > 0)
       : [];
-
   const legacyToolsValue = parsed.tools;
   const legacyTools = Array.isArray(legacyToolsValue)
     ? legacyToolsValue.filter((tool): tool is string => typeof tool === "string")
     : [];
-
-  const tools = allowedTools.length > 0 ? allowedTools : legacyTools;
-
-  return { name, description, tools };
+  const mcpTools = modernMcp.length > 0 ? modernMcp : [...allowedTools, ...legacyTools];
+  for (const [index, pattern] of mcpTools.entries()) {
+    validateMcpPattern(pattern, `SKILL.md tools.mcp[${index}]`);
+  }
+  for (const [index, pattern] of modernScripts.entries()) {
+    validateScriptPattern(pattern, `SKILL.md tools.scripts[${index}]`);
+  }
+  return {
+    name,
+    description,
+    tools: {
+      mcp: mcpTools,
+      scripts: modernScripts,
+    },
+  };
 };
 
 // ---------------------------------------------------------------------------
@@ -155,7 +176,14 @@ export const loadSkillMetadata = async (
           skillPath: manifest,
         });
       }
-    } catch {
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (
+        message.startsWith("Invalid MCP tool pattern") ||
+        message.startsWith("Invalid script pattern")
+      ) {
+        throw new Error(`Invalid SKILL.md frontmatter at ${manifest}: ${message}`);
+      }
       // Ignore unreadable skill manifests.
     }
   }

package/src/skill-tools.ts

@@ -17,6 +17,12 @@ import { loadSkillInstructions, readSkillResource } from "./skill-context.js";
  */
 export const createSkillTools = (
   skills: SkillMetadata[],
+  options?: {
+    onActivateSkill?: (name: string) => Promise<string[]> | string[];
+    onDeactivateSkill?: (name: string) => Promise<string[]> | string[];
+    onListActiveSkills?: () => string[];
+    isScriptAllowed?: (skill: string, scriptPath: string) => boolean;
+  },
 ): ToolDefinition[] => {
   if (skills.length === 0) {
     return [];
@@ -53,8 +59,12 @@ export const createSkillTools = (
         }
         try {
           const instructions = await loadSkillInstructions(skill);
+          const activeSkills = options?.onActivateSkill
+            ? await options.onActivateSkill(name)
+            : [];
           return {
             skill: name,
+            activeSkills,
             instructions: instructions || "(no instructions provided)",
           };
         } catch (err) {
@@ -64,6 +74,50 @@ export const createSkillTools = (
         }
       },
     }),
+    defineTool({
+      name: "deactivate_skill",
+      description:
+        "Deactivate a previously activated skill and update scoped tool availability.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Name of the skill to deactivate",
+          },
+        },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      handler: async (input) => {
+        const name = typeof input.name === "string" ? input.name.trim() : "";
+        if (!name) {
+          return { error: "Skill name is required" };
+        }
+        try {
+          const activeSkills = options?.onDeactivateSkill
+            ? await options.onDeactivateSkill(name)
+            : [];
+          return { skill: name, activeSkills };
+        } catch (err) {
+          return {
+            error: `Failed to deactivate skill "${name}": ${err instanceof Error ? err.message : String(err)}`,
+          };
+        }
+      },
+    }),
+    defineTool({
+      name: "list_active_skills",
+      description: "List currently active skills with scoped MCP tools.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      handler: async () => ({
+        activeSkills: options?.onListActiveSkills ? options.onListActiveSkills() : [],
+      }),
+    }),
     defineTool({
       name: "read_skill_resource",
       description:
@@ -133,7 +187,7 @@ export const createSkillTools = (
           };
         }
         try {
-          const scripts = await listSkillScripts(skill);
+          const scripts = await listSkillScripts(skill, options?.isScriptAllowed);
           return {
             skill: name,
             scripts,
@@ -191,6 +245,18 @@ export const createSkillTools = (
 
         try {
           const scriptPath = resolveSkillScriptPath(skill, script);
+          const relativeScript = `scripts/${scriptPath
+            .slice(resolve(skill.skillDir, "scripts").length + 1)
+            .split(sep)
+            .join("/")}`;
+          if (
+            options?.isScriptAllowed &&
+            !options.isScriptAllowed(name, relativeScript)
+          ) {
+            return {
+              error: `Script "${relativeScript}" for skill "${name}" is not allowed by policy.`,
+            };
+          }
           await access(scriptPath);
           const fn = await loadRunnableScriptFunction(scriptPath);
           const output = await fn(payload, {
@@ -215,7 +281,10 @@ export const createSkillTools = (
 
 const SCRIPT_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]);
 
-const listSkillScripts = async (skill: SkillMetadata): Promise<string[]> => {
+const listSkillScripts = async (
+  skill: SkillMetadata,
+  isScriptAllowed?: (skill: string, scriptPath: string) => boolean,
+): Promise<string[]> => {
   const scriptsRoot = resolve(skill.skillDir, "scripts");
   try {
     await access(scriptsRoot);
@@ -226,6 +295,7 @@ const listSkillScripts = async (skill: SkillMetadata): Promise<string[]> => {
   const scripts = await collectScriptFiles(scriptsRoot);
   return scripts
     .map((fullPath) => `scripts/${fullPath.slice(scriptsRoot.length + 1).split(sep).join("/")}`)
+    .filter((path) => (isScriptAllowed ? isScriptAllowed(skill.name, path) : true))
     .sort();
 };
 

package/src/tool-dispatcher.ts

@@ -26,6 +26,16 @@ export class ToolDispatcher {
     }
   }
 
+  unregister(name: string): void {
+    this.tools.delete(name);
+  }
+
+  unregisterMany(names: Iterable<string>): void {
+    for (const name of names) {
+      this.unregister(name);
+    }
+  }
+
   list(): ToolDefinition[] {
     return [...this.tools.values()];
   }

package/src/tool-policy.ts

@@ -0,0 +1,104 @@
+export type RuntimeEnvironment = "development" | "staging" | "production";
+
+export type ToolPolicyMode = "all" | "allowlist" | "denylist";
+
+export interface ToolPatternPolicy {
+  mode?: ToolPolicyMode;
+  include?: string[];
+  exclude?: string[];
+  byEnvironment?: {
+    development?: Omit<ToolPatternPolicy, "byEnvironment">;
+    staging?: Omit<ToolPatternPolicy, "byEnvironment">;
+    production?: Omit<ToolPatternPolicy, "byEnvironment">;
+  };
+}
+
+const MCP_PATTERN = /^[^/*\s]+\/(\*|[^/*\s]+)$/;
+const SCRIPT_PATTERN = /^[^/*\s]+\/(\*|[^*\s]+)$/;
+
+export const validateMcpPattern = (pattern: string, path: string): void => {
+  if (!MCP_PATTERN.test(pattern)) {
+    throw new Error(
+      `Invalid MCP tool pattern at ${path}: "${pattern}". Expected "server/tool" or "server/*".`,
+    );
+  }
+};
+
+export const validateScriptPattern = (pattern: string, path: string): void => {
+  if (!SCRIPT_PATTERN.test(pattern)) {
+    throw new Error(
+      `Invalid script pattern at ${path}: "${pattern}". Expected "skill/script-path" or "skill/*".`,
+    );
+  }
+};
+
+const splitPattern = (pattern: string): [string, string] => {
+  const slash = pattern.indexOf("/");
+  if (slash < 0) {
+    return [pattern, ""];
+  }
+  return [pattern.slice(0, slash), pattern.slice(slash + 1)];
+};
+
+export const matchesSlashPattern = (value: string, pattern: string): boolean => {
+  const [targetScope, targetName] = splitPattern(value);
+  const [patternScope, patternName] = splitPattern(pattern);
+  if (targetScope !== patternScope) {
+    return false;
+  }
+  if (patternName === "*") {
+    return true;
+  }
+  return targetName === patternName;
+};
+
+export const mergePolicyForEnvironment = (
+  policy: ToolPatternPolicy | undefined,
+  environment: RuntimeEnvironment,
+): Omit<ToolPatternPolicy, "byEnvironment"> => {
+  const base: Omit<ToolPatternPolicy, "byEnvironment"> = {
+    mode: policy?.mode,
+    include: [...(policy?.include ?? [])],
+    exclude: [...(policy?.exclude ?? [])],
+  };
+  const env = policy?.byEnvironment?.[environment];
+  if (!env) {
+    return base;
+  }
+  return {
+    mode: env.mode ?? base.mode,
+    include: env.include ? [...env.include] : base.include,
+    exclude: env.exclude ? [...env.exclude] : base.exclude,
+  };
+};
+
+export const applyToolPolicy = (
+  values: string[],
+  policy: Omit<ToolPatternPolicy, "byEnvironment"> | undefined,
+): { allowed: string[]; filteredOut: string[] } => {
+  const mode = policy?.mode ?? "all";
+  const include = policy?.include ?? [];
+  const exclude = policy?.exclude ?? [];
+  const allowed: string[] = [];
+  const filteredOut: string[] = [];
+
+  for (const value of values) {
+    const inInclude = include.some((pattern) => matchesSlashPattern(value, pattern));
+    const inExclude = exclude.some((pattern) => matchesSlashPattern(value, pattern));
+    let keep = true;
+    if (mode === "allowlist") {
+      keep = inInclude;
+    } else if (mode === "denylist") {
+      keep = !inExclude;
+    }
+    if (mode === "all" && exclude.length > 0) {
+      keep = !inExclude;
+    }
+    if (keep) {
+      allowed.push(value);
+    } else {
+      filteredOut.push(value);
+    }
+  }
+  return { allowed, filteredOut };
+};