fourmis-agents-sdk 0.3.0 → 0.4.0

package/dist/skills/index.js

@@ -0,0 +1,326 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/skills/frontmatter.ts
+import { parse } from "yaml";
+function normalizeNewlines(value) {
+  return value.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`);
+}
+function extractFrontmatter(content) {
+  const normalized = normalizeNewlines(content);
+  if (!normalized.startsWith("---")) {
+    return { yamlString: null, body: normalized };
+  }
+  const endIndex = normalized.indexOf(`
+---`, 3);
+  if (endIndex === -1) {
+    return { yamlString: null, body: normalized };
+  }
+  return {
+    yamlString: normalized.slice(4, endIndex),
+    body: normalized.slice(endIndex + 4).trim()
+  };
+}
+function parseFrontmatter(content) {
+  const { yamlString, body } = extractFrontmatter(content);
+  if (!yamlString) {
+    return { frontmatter: {}, body };
+  }
+  const parsed = parse(yamlString);
+  return { frontmatter: parsed ?? {}, body };
+}
+function stripFrontmatter(content) {
+  return parseFrontmatter(content).body;
+}
+
+// src/skills/skills.ts
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+var MAX_NAME_LENGTH = 64;
+var MAX_DESCRIPTION_LENGTH = 1024;
+var MAX_COMPATIBILITY_LENGTH = 500;
+var CONFIG_DIR_NAME = ".claude";
+function shouldIgnore(name) {
+  return name.startsWith(".") || name === "node_modules";
+}
+function validateName(name, parentDirName) {
+  const errors = [];
+  if (name !== parentDirName) {
+    errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+  }
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    errors.push(`name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)`);
+  }
+  if (name.startsWith("-") || name.endsWith("-")) {
+    errors.push(`name must not start or end with a hyphen`);
+  }
+  if (name.includes("--")) {
+    errors.push(`name must not contain consecutive hyphens`);
+  }
+  return errors;
+}
+function validateDescription(description) {
+  const errors = [];
+  if (!description || description.trim() === "") {
+    errors.push("description is required");
+  } else if (description.length > MAX_DESCRIPTION_LENGTH) {
+    errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+  }
+  return errors;
+}
+function validateCompatibility(compatibility) {
+  if (!compatibility)
+    return [];
+  if (compatibility.length > MAX_COMPATIBILITY_LENGTH) {
+    return [`compatibility exceeds ${MAX_COMPATIBILITY_LENGTH} characters (${compatibility.length})`];
+  }
+  return [];
+}
+function loadSkillsFromDir(options) {
+  return loadSkillsFromDirInternal(options.dir, options.source, true);
+}
+function loadSkillsFromDirInternal(dir, source, includeRootFiles) {
+  const skills = [];
+  const diagnostics = [];
+  if (!existsSync(dir)) {
+    return { skills, diagnostics };
+  }
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (shouldIgnore(entry.name)) {
+        continue;
+      }
+      const fullPath = join(dir, entry.name);
+      let isDirectory = entry.isDirectory();
+      let isFile = entry.isFile();
+      if (entry.isSymbolicLink()) {
+        try {
+          const stats = statSync(fullPath);
+          isDirectory = stats.isDirectory();
+          isFile = stats.isFile();
+        } catch {
+          continue;
+        }
+      }
+      if (isDirectory) {
+        const subResult = loadSkillsFromDirInternal(fullPath, source, false);
+        skills.push(...subResult.skills);
+        diagnostics.push(...subResult.diagnostics);
+        continue;
+      }
+      if (!isFile)
+        continue;
+      const isRootMd = includeRootFiles && entry.name.endsWith(".md");
+      const isSkillMd = !includeRootFiles && entry.name === "SKILL.md";
+      if (!isRootMd && !isSkillMd)
+        continue;
+      const result = loadSkillFromFile(fullPath, source);
+      if (result.skill) {
+        skills.push(result.skill);
+      }
+      diagnostics.push(...result.diagnostics);
+    }
+  } catch {}
+  return { skills, diagnostics };
+}
+function loadSkillFromFile(filePath, source) {
+  const diagnostics = [];
+  try {
+    const rawContent = readFileSync(filePath, "utf-8");
+    const { frontmatter } = parseFrontmatter(rawContent);
+    const skillDir = dirname(filePath);
+    const parentDirName = basename(skillDir);
+    const descErrors = validateDescription(frontmatter.description);
+    for (const error of descErrors) {
+      diagnostics.push({ type: "warning", message: error, path: filePath });
+    }
+    const name = frontmatter.name || parentDirName;
+    const nameErrors = validateName(name, parentDirName);
+    for (const error of nameErrors) {
+      diagnostics.push({ type: "warning", message: error, path: filePath });
+    }
+    const compatErrors = validateCompatibility(frontmatter.compatibility);
+    for (const error of compatErrors) {
+      diagnostics.push({ type: "warning", message: error, path: filePath });
+    }
+    if (!frontmatter.description || frontmatter.description.trim() === "") {
+      return { skill: null, diagnostics };
+    }
+    const allowedToolsRaw = frontmatter["allowed-tools"];
+    const allowedTools = allowedToolsRaw ? allowedToolsRaw.split(/\s+/).filter(Boolean) : undefined;
+    return {
+      skill: {
+        name,
+        description: frontmatter.description,
+        filePath,
+        baseDir: skillDir,
+        source,
+        disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+        license: frontmatter.license,
+        compatibility: frontmatter.compatibility,
+        metadata: frontmatter.metadata,
+        allowedTools
+      },
+      diagnostics
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "failed to parse skill file";
+    diagnostics.push({ type: "warning", message, path: filePath });
+    return { skill: null, diagnostics };
+  }
+}
+function normalizePath(input) {
+  const trimmed = input.trim();
+  if (trimmed === "~")
+    return homedir();
+  if (trimmed.startsWith("~/"))
+    return join(homedir(), trimmed.slice(2));
+  if (trimmed.startsWith("~"))
+    return join(homedir(), trimmed.slice(1));
+  return trimmed;
+}
+function resolveSkillPath(p, cwd) {
+  const normalized = normalizePath(p);
+  return isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
+}
+function loadSkills(options = {}) {
+  const { cwd = process.cwd(), skillPaths = [], includeDefaults = true } = options;
+  const skillMap = new Map;
+  const realPathSet = new Set;
+  const allDiagnostics = [];
+  const collisionDiagnostics = [];
+  function addSkills(result) {
+    allDiagnostics.push(...result.diagnostics);
+    for (const skill of result.skills) {
+      let realPath;
+      try {
+        realPath = realpathSync(skill.filePath);
+      } catch {
+        realPath = skill.filePath;
+      }
+      if (realPathSet.has(realPath))
+        continue;
+      const existing = skillMap.get(skill.name);
+      if (existing) {
+        collisionDiagnostics.push({
+          type: "collision",
+          message: `name "${skill.name}" collision`,
+          path: skill.filePath,
+          collision: {
+            resourceType: "skill",
+            name: skill.name,
+            winnerPath: existing.filePath,
+            loserPath: skill.filePath
+          }
+        });
+      } else {
+        skillMap.set(skill.name, skill);
+        realPathSet.add(realPath);
+      }
+    }
+  }
+  if (includeDefaults) {
+    const userSkillsDir = join(homedir(), CONFIG_DIR_NAME, "skills");
+    const projectSkillsDir = resolve(cwd, CONFIG_DIR_NAME, "skills");
+    addSkills(loadSkillsFromDirInternal(userSkillsDir, "user", true));
+    addSkills(loadSkillsFromDirInternal(projectSkillsDir, "project", true));
+  }
+  for (const rawPath of skillPaths) {
+    const resolvedPath = resolveSkillPath(rawPath, cwd);
+    if (!existsSync(resolvedPath)) {
+      allDiagnostics.push({ type: "warning", message: "skill path does not exist", path: resolvedPath });
+      continue;
+    }
+    try {
+      const stats = statSync(resolvedPath);
+      if (stats.isDirectory()) {
+        addSkills(loadSkillsFromDirInternal(resolvedPath, "path", true));
+      } else if (stats.isFile() && resolvedPath.endsWith(".md")) {
+        const result = loadSkillFromFile(resolvedPath, "path");
+        if (result.skill) {
+          addSkills({ skills: [result.skill], diagnostics: result.diagnostics });
+        } else {
+          allDiagnostics.push(...result.diagnostics);
+        }
+      } else {
+        allDiagnostics.push({ type: "warning", message: "skill path is not a markdown file", path: resolvedPath });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "failed to read skill path";
+      allDiagnostics.push({ type: "warning", message, path: resolvedPath });
+    }
+  }
+  return {
+    skills: Array.from(skillMap.values()),
+    diagnostics: [...allDiagnostics, ...collisionDiagnostics]
+  };
+}
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function formatSkillsForPrompt(skills) {
+  const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
+  if (visibleSkills.length === 0) {
+    return "";
+  }
+  const lines = [
+    "The following skills provide specialized instructions for specific tasks.",
+    "Use the read tool to load a skill's file when the task matches its description.",
+    "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+    "",
+    "<available_skills>"
+  ];
+  for (const skill of visibleSkills) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+    if (skill.allowedTools?.length) {
+      lines.push(`    <allowed-tools>${escapeXml(skill.allowedTools.join(" "))}</allowed-tools>`);
+    }
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join(`
+`);
+}
+export {
+  stripFrontmatter,
+  parseFrontmatter,
+  loadSkillsFromDir,
+  loadSkills,
+  formatSkillsForPrompt
+};

package/dist/skills/skills.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Skill loader — discovers, validates, and formats SKILL.md files.
+ *
+ * Mirrors the Claude SDK (pi-mono) implementation:
+ * - Loads from ~/.claude/skills/ (user), .claude/skills/ (project), and explicit paths
+ * - SKILL.md frontmatter: name, description, disable-model-invocation
+ * - Name validation: lowercase a-z, 0-9, hyphens, max 64 chars
+ * - XML-formatted prompt injection for available skills
+ */
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    "disable-model-invocation"?: boolean;
+    /** License name or reference to a bundled license file. (Agent Skills spec) */
+    license?: string;
+    /** Environment requirements — max 500 chars. (Agent Skills spec) */
+    compatibility?: string;
+    /** Arbitrary key-value metadata. (Agent Skills spec) */
+    metadata?: Record<string, string>;
+    /** Space-delimited list of pre-approved tools. Experimental. (Agent Skills spec) */
+    "allowed-tools"?: string;
+    [key: string]: unknown;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+    disableModelInvocation: boolean;
+    /** License (Agent Skills spec) */
+    license?: string;
+    /** Environment compatibility note (Agent Skills spec) */
+    compatibility?: string;
+    /** Arbitrary metadata (Agent Skills spec) */
+    metadata?: Record<string, string>;
+    /** Pre-approved tools list (Agent Skills spec, experimental) */
+    allowedTools?: string[];
+}
+export interface SkillDiagnostic {
+    type: "warning" | "collision";
+    message: string;
+    path: string;
+    collision?: {
+        resourceType: "skill";
+        name: string;
+        winnerPath: string;
+        loserPath: string;
+    };
+}
+export interface LoadSkillsResult {
+    skills: Skill[];
+    diagnostics: SkillDiagnostic[];
+}
+export interface LoadSkillsFromDirOptions {
+    /** Directory to scan for skills */
+    dir: string;
+    /** Source identifier for these skills */
+    source: string;
+}
+export interface LoadSkillsOptions {
+    /** Working directory for project-local skills. Default: process.cwd() */
+    cwd?: string;
+    /** Explicit skill paths (files or directories) */
+    skillPaths?: string[];
+    /** Include default skills directories (~/.claude/skills, .claude/skills). Default: true */
+    includeDefaults?: boolean;
+}
+/**
+ * Load skills from a directory.
+ *
+ * Discovery rules (matches Claude SDK):
+ * - Root-level: any .md file directly in the directory
+ * - Subdirectories: only SKILL.md files (recursive)
+ */
+export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult;
+/**
+ * Load skills from all configured locations.
+ *
+ * Default locations (matches Claude SDK):
+ * - ~/.claude/skills/ — user-global skills
+ * - .claude/skills/   — project-local skills
+ *
+ * Plus any explicit `skillPaths` (files or directories).
+ */
+export declare function loadSkills(options?: LoadSkillsOptions): LoadSkillsResult;
+/**
+ * Format skills for inclusion in a system prompt.
+ *
+ * Uses XML format per Agent Skills standard (matches Claude SDK).
+ * Skills with disableModelInvocation=true are excluded.
+ */
+export declare function formatSkillsForPrompt(skills: Skill[]): string;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/skills/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiBH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,OAAO,CAAC;IAChC,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QACV,YAAY,EAAE,OAAO,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA0DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,gBAAgB,CAErF;AAgJD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkF5E;AAaD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CA6B7D"}