@cuylabs/agent-core 0.4.0 → 0.5.0

package/dist/chunk-LRHOS4ZN.js

@@ -0,0 +1,584 @@
+// src/skill/discovery/constants.ts
+var DEFAULT_EXTERNAL_DIRS = [".agents", ".claude"];
+var DEFAULT_MAX_SCAN_DEPTH = 4;
+var MAX_SKILLS_PER_ROOT = 500;
+var SCOPE_PRIORITY = {
+  project: 0,
+  user: 1,
+  global: 2,
+  builtin: 3
+};
+
+// src/skill/loader/constants.ts
+var SKILL_FILENAME = "SKILL.md";
+var DEFAULT_SKILL_MAX_SIZE = 102400;
+var RESOURCE_DIRS = {
+  scripts: "script",
+  references: "reference",
+  assets: "asset",
+  examples: "example"
+};
+
+// src/skill/loader/frontmatter.ts
+function parseFrontmatter(raw) {
+  const trimmed = raw.trimStart();
+  if (!trimmed.startsWith("---")) {
+    return { data: {}, body: raw };
+  }
+  const endIndex = trimmed.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { data: {}, body: raw };
+  }
+  const yamlBlock = trimmed.slice(4, endIndex).trim();
+  const body = trimmed.slice(endIndex + 4).trim();
+  const data = {};
+  const lines = yamlBlock.split("\n");
+  let currentKey = null;
+  let continuationValue = "";
+  for (const line of lines) {
+    if (line.trimStart().startsWith("#") || line.trim() === "") continue;
+    const kvMatch = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+    if (kvMatch) {
+      if (currentKey && continuationValue) {
+        data[currentKey] = parseFrontmatterValue(continuationValue.trim());
+        continuationValue = "";
+      }
+      const key = kvMatch[1];
+      const rawValue = kvMatch[2].trim();
+      if (rawValue.startsWith("[") && rawValue.endsWith("]")) {
+        data[key] = rawValue.slice(1, -1).split(",").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+        currentKey = null;
+      } else if (rawValue === "" || rawValue === "|" || rawValue === ">") {
+        currentKey = key;
+        continuationValue = "";
+      } else {
+        data[key] = parseFrontmatterValue(rawValue);
+        currentKey = null;
+      }
+    } else if (currentKey) {
+      continuationValue += (continuationValue ? "\n" : "") + line.trim();
+    } else if (line.trimStart().startsWith("- ")) {
+      const keys = Object.keys(data);
+      const lastKey = keys.length > 0 ? keys[keys.length - 1] : null;
+      if (!lastKey) continue;
+      const existing = data[lastKey];
+      const item = line.trimStart().slice(2).trim();
+      if (Array.isArray(existing)) {
+        existing.push(item);
+      } else {
+        data[lastKey] = [item];
+      }
+    }
+  }
+  if (currentKey && continuationValue) {
+    data[currentKey] = parseFrontmatterValue(continuationValue.trim());
+  }
+  return { data, body };
+}
+function parseFrontmatterValue(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"') || raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1);
+  }
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  if (raw === "null" || raw === "~") return null;
+  return raw;
+}
+
+// src/skill/loader/metadata.ts
+import { readFile, stat } from "fs/promises";
+import { join } from "path";
+async function loadSkillMetadata(filePath, scope, source, maxSize) {
+  try {
+    const info = await stat(filePath);
+    if (!info.isFile() || info.size > maxSize) return null;
+    const raw = await readFile(filePath, "utf-8");
+    const { data } = parseFrontmatter(raw);
+    const name = typeof data.name === "string" ? data.name.trim() : null;
+    const description = typeof data.description === "string" ? data.description.trim() : null;
+    if (!name || !description) return null;
+    return {
+      name,
+      description,
+      version: typeof data.version === "string" ? data.version : void 0,
+      scope,
+      source,
+      filePath,
+      baseDir: join(filePath, ".."),
+      tags: Array.isArray(data.tags) ? data.tags.map(String) : void 0,
+      dependencies: Array.isArray(data.dependencies) ? data.dependencies.map(String) : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/skill/loader/resources.ts
+import { readFile as readFile2, readdir, stat as stat2 } from "fs/promises";
+import { extname, join as join2, relative } from "path";
+async function loadSkillContent(metadata) {
+  const raw = await readFile2(metadata.filePath, "utf-8");
+  const { body } = parseFrontmatter(raw);
+  const resources = await scanSkillResources(metadata.baseDir);
+  return {
+    ...metadata,
+    body,
+    resources
+  };
+}
+async function loadResourceContent(resource) {
+  return readFile2(resource.absolutePath, "utf-8");
+}
+async function scanSkillResources(baseDir) {
+  const resources = [];
+  for (const [dirName, resourceType] of Object.entries(RESOURCE_DIRS)) {
+    const dirPath = join2(baseDir, dirName);
+    try {
+      const info = await stat2(dirPath);
+      if (!info.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    await collectFiles(dirPath, baseDir, resourceType, resources);
+  }
+  return resources;
+}
+async function collectFiles(dirPath, baseDir, type, resources, maxDepth = 3, currentDepth = 0) {
+  if (currentDepth >= maxDepth) return;
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const fullPath = join2(dirPath, entry.name);
+      if (entry.isFile()) {
+        resources.push({
+          relativePath: relative(baseDir, fullPath),
+          type,
+          absolutePath: fullPath
+        });
+      } else if (entry.isDirectory()) {
+        await collectFiles(fullPath, baseDir, type, resources, maxDepth, currentDepth + 1);
+      }
+    }
+  } catch {
+  }
+}
+function inferResourceType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if ([".sh", ".bash", ".py", ".rb", ".js", ".ts"].includes(ext)) {
+    return "script";
+  }
+  if ([".md", ".txt", ".rst", ".adoc"].includes(ext)) {
+    return "reference";
+  }
+  if ([".json", ".yaml", ".yml", ".toml", ".xml", ".html", ".css"].includes(ext)) {
+    return "asset";
+  }
+  return "reference";
+}
+
+// src/skill/discovery/discover.ts
+import { homedir } from "os";
+import { join as join5, resolve as resolve2 } from "path";
+
+// src/skill/discovery/dedupe.ts
+function deduplicateSkills(skills) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    const existing = byName.get(skill.name);
+    if (!existing) {
+      byName.set(skill.name, skill);
+      continue;
+    }
+    const existingPriority = SCOPE_PRIORITY[existing.scope];
+    const newPriority = SCOPE_PRIORITY[skill.scope];
+    if (newPriority <= existingPriority) {
+      byName.set(skill.name, skill);
+    }
+  }
+  return Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// src/skill/discovery/fs.ts
+import { access, stat as stat3 } from "fs/promises";
+import { dirname, join as join3, resolve, sep } from "path";
+async function dirExists(path) {
+  try {
+    const info = await stat3(path);
+    return info.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function findGitRoot(startDir) {
+  let dir = resolve(startDir);
+  const root = sep === "/" ? "/" : dir.slice(0, 3);
+  while (dir !== root) {
+    try {
+      await access(join3(dir, ".git"));
+      return dir;
+    } catch {
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return void 0;
+}
+function dirsBetween(from, to) {
+  const fromResolved = resolve(from);
+  const toResolved = resolve(to);
+  if (!toResolved.startsWith(fromResolved)) return [fromResolved];
+  const dirs = [];
+  let current = toResolved;
+  while (current.startsWith(fromResolved)) {
+    dirs.push(current);
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  dirs.reverse();
+  return dirs;
+}
+
+// src/skill/discovery/scan.ts
+import { readdir as readdir2 } from "fs/promises";
+import { join as join4 } from "path";
+async function scanRoot(root, maxDepth, maxFileSize = DEFAULT_SKILL_MAX_SIZE) {
+  const skills = [];
+  const errors = [];
+  let dirsScanned = 0;
+  const queue = [[root.path, 0]];
+  while (queue.length > 0 && skills.length < MAX_SKILLS_PER_ROOT) {
+    const [dirPath, depth] = queue.shift();
+    if (depth > maxDepth) continue;
+    dirsScanned++;
+    try {
+      const entries = await readdir2(dirPath, { withFileTypes: true });
+      const hasSkillFile = entries.some((entry) => entry.isFile() && entry.name === SKILL_FILENAME);
+      if (hasSkillFile) {
+        const filePath = join4(dirPath, SKILL_FILENAME);
+        const metadata = await loadSkillMetadata(
+          filePath,
+          root.scope,
+          root.source,
+          maxFileSize
+        );
+        if (metadata) {
+          skills.push(metadata);
+        } else {
+          errors.push({
+            path: filePath,
+            reason: "Invalid or incomplete frontmatter (name and description required)"
+          });
+        }
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") {
+          continue;
+        }
+        queue.push([join4(dirPath, entry.name), depth + 1]);
+      }
+    } catch (error) {
+      errors.push({
+        path: dirPath,
+        reason: `Cannot read directory: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  return { skills, errors, dirsScanned };
+}
+
+// src/skill/discovery/discover.ts
+async function discoverSkills(cwd, config) {
+  const startTime = Date.now();
+  const resolvedCwd = resolve2(cwd);
+  const errors = [];
+  let dirsScanned = 0;
+  const externalDirs = config?.externalDirs ?? DEFAULT_EXTERNAL_DIRS;
+  const maxDepth = config?.maxScanDepth ?? DEFAULT_MAX_SCAN_DEPTH;
+  const maxFileSize = config?.maxFileSize ?? DEFAULT_SKILL_MAX_SIZE;
+  const roots = [];
+  if (config?.roots) {
+    for (const root of config.roots) {
+      const absRoot = resolve2(resolvedCwd, root);
+      roots.push({ path: absRoot, scope: "global", source: { type: "local", root: absRoot } });
+    }
+  }
+  const home = homedir();
+  for (const dir of externalDirs) {
+    const skillsDir = join5(home, dir, "skills");
+    if (await dirExists(skillsDir)) {
+      roots.push({
+        path: skillsDir,
+        scope: "user",
+        source: { type: "local", root: join5(home, dir) }
+      });
+    }
+  }
+  const gitRoot = await findGitRoot(resolvedCwd);
+  const projectDirs = gitRoot ? dirsBetween(gitRoot, resolvedCwd) : [resolvedCwd];
+  for (const dir of projectDirs) {
+    for (const extDir of externalDirs) {
+      const skillsDir = join5(dir, extDir, "skills");
+      if (await dirExists(skillsDir)) {
+        roots.push({
+          path: skillsDir,
+          scope: "project",
+          source: { type: "local", root: join5(dir, extDir) }
+        });
+      }
+    }
+  }
+  const allSkills = [];
+  for (const root of roots) {
+    const result = await scanRoot(root, maxDepth, maxFileSize);
+    allSkills.push(...result.skills);
+    errors.push(...result.errors);
+    dirsScanned += result.dirsScanned;
+  }
+  return {
+    skills: deduplicateSkills(allSkills),
+    errors,
+    dirsScanned,
+    durationMs: Date.now() - startTime
+  };
+}
+
+// src/skill/registry.ts
+var SkillRegistry = class {
+  /** All discovered skill metadata indexed by name */
+  skills;
+  /** Cached full content for skills that have been loaded */
+  contentCache;
+  /** Discovery metadata */
+  discoveryResult;
+  constructor(discoveryResult) {
+    this.discoveryResult = discoveryResult;
+    this.skills = /* @__PURE__ */ new Map();
+    this.contentCache = /* @__PURE__ */ new Map();
+    for (const skill of discoveryResult.skills) {
+      this.skills.set(skill.name, skill);
+    }
+  }
+  // ==========================================================================
+  // Lookup
+  // ==========================================================================
+  /** Get a skill's metadata by name. Returns undefined if not found. */
+  get(name) {
+    return this.skills.get(name);
+  }
+  /** Check if a skill exists by name. */
+  has(name) {
+    return this.skills.has(name);
+  }
+  /** Get all skill metadata entries. */
+  list() {
+    return Array.from(this.skills.values());
+  }
+  /** Number of registered skills. */
+  get size() {
+    return this.skills.size;
+  }
+  /** Skill names as an array. */
+  get names() {
+    return Array.from(this.skills.keys());
+  }
+  // ==========================================================================
+  // Content Loading (L2 + L3)
+  // ==========================================================================
+  /**
+   * Load a skill's full content (L2: body + resource listing).
+   *
+   * Results are cached — subsequent calls return the cached content
+   * without re-reading the filesystem.
+   *
+   * @param name Skill name
+   * @returns Full skill content, or null if the skill doesn't exist
+   */
+  async loadContent(name) {
+    const cached = this.contentCache.get(name);
+    if (cached) return cached;
+    const metadata = this.skills.get(name);
+    if (!metadata) return null;
+    const content = await loadSkillContent(metadata);
+    this.contentCache.set(name, content);
+    return content;
+  }
+  /**
+   * Load a specific bundled resource from a skill (L3).
+   *
+   * The skill's content must be loaded first (via `loadContent`)
+   * so the resource listing is available.
+   *
+   * @param skillName  Skill name
+   * @param relativePath  Relative path to the resource within the skill dir
+   * @returns Resource file content as UTF-8 string
+   * @throws If the skill or resource doesn't exist
+   */
+  async loadResource(skillName, relativePath) {
+    const content = await this.loadContent(skillName);
+    if (!content) {
+      throw new Error(`Skill not found: "${skillName}"`);
+    }
+    const resource = content.resources.find(
+      (r) => r.relativePath === relativePath
+    );
+    if (!resource) {
+      const available = content.resources.map((r) => r.relativePath).join(", ");
+      throw new Error(
+        `Resource "${relativePath}" not found in skill "${skillName}". Available: ${available || "(none)"}`
+      );
+    }
+    return loadResourceContent(resource);
+  }
+  /**
+   * Get the list of resources for a loaded skill.
+   *
+   * @param name Skill name
+   * @returns Resource list, or empty array if skill isn't loaded yet
+   */
+  getResources(name) {
+    return this.contentCache.get(name)?.resources ?? [];
+  }
+  // ==========================================================================
+  // Prompt Summary (L1 — always in system prompt)
+  // ==========================================================================
+  /**
+   * Format a summary of all available skills for injection into the system prompt.
+   *
+   * This is the L1 layer — the agent sees names and descriptions of all
+   * available skills, enabling it to decide which to activate via tool calls.
+   *
+   * The output format uses XML tags (consistent with the instruction format
+   * in `formatInstructions`) for clear delineation in the prompt.
+   *
+   * Returns empty string if no skills are available.
+   *
+   * @example Output:
+   * ```xml
+   * <available-skills>
+   *
+   * You have access to the following skills. To activate a skill and load its
+   * full instructions, call the `skill` tool with the skill's name.
+   *
+   * <skill name="testing" scope="project">
+   * Write comprehensive test suites with vitest, covering unit, integration,
+   * and snapshot testing patterns.
+   * </skill>
+   *
+   * <skill name="frontend-design" scope="user">
+   * Create distinctive, production-grade frontend interfaces with high design quality.
+   * </skill>
+   *
+   * </available-skills>
+   * ```
+   */
+  formatSummary() {
+    if (this.skills.size === 0) return "";
+    const lines = [];
+    lines.push("<available-skills>");
+    lines.push("");
+    lines.push(
+      "You have access to the following skills. To activate a skill and load its full instructions, call the `skill` tool with the skill's name. Only load a skill when the current task matches its description."
+    );
+    for (const skill of this.skills.values()) {
+      lines.push("");
+      lines.push(`<skill name="${skill.name}" scope="${skill.scope}">`);
+      lines.push(skill.description);
+      if (skill.dependencies && skill.dependencies.length > 0) {
+        lines.push(`Depends on: ${skill.dependencies.join(", ")}`);
+      }
+      lines.push("</skill>");
+    }
+    lines.push("");
+    lines.push("</available-skills>");
+    return lines.join("\n");
+  }
+  /**
+   * Format the full content of a loaded skill for a tool response.
+   *
+   * Wraps the skill body in XML with metadata, and lists bundled resources
+   * so the agent knows what's available at L3.
+   *
+   * @param content Previously loaded skill content
+   * @returns Formatted string for tool response
+   */
+  formatContent(content) {
+    const lines = [];
+    lines.push(`<skill-content name="${content.name}">`);
+    lines.push("");
+    lines.push(content.body);
+    if (content.resources.length > 0) {
+      lines.push("");
+      lines.push("<bundled-resources>");
+      lines.push(
+        "This skill includes the following bundled files. To read one, call the `skill_resource` tool with the skill name and relative path."
+      );
+      lines.push("");
+      const byType = /* @__PURE__ */ new Map();
+      for (const r of content.resources) {
+        const list = byType.get(r.type) ?? [];
+        list.push(r);
+        byType.set(r.type, list);
+      }
+      for (const [type, resources] of byType) {
+        lines.push(`  ${type}s:`);
+        for (const r of resources) {
+          lines.push(`    - ${r.relativePath}`);
+        }
+      }
+      lines.push("</bundled-resources>");
+    }
+    if (content.dependencies && content.dependencies.length > 0) {
+      lines.push("");
+      lines.push(
+        `<dependencies>This skill works best when combined with: ${content.dependencies.join(", ")}</dependencies>`
+      );
+    }
+    lines.push("");
+    lines.push("</skill-content>");
+    return lines.join("\n");
+  }
+  // ==========================================================================
+  // Cache Management
+  // ==========================================================================
+  /** Clear the content cache, forcing reloads on next access. */
+  clearContentCache() {
+    this.contentCache.clear();
+  }
+  /** Check if a skill's content has been loaded and cached. */
+  isContentLoaded(name) {
+    return this.contentCache.has(name);
+  }
+};
+async function createSkillRegistry(cwd, config) {
+  const result = await discoverSkills(cwd, config);
+  return new SkillRegistry(result);
+}
+function emptySkillRegistry() {
+  return new SkillRegistry({
+    skills: [],
+    errors: [],
+    dirsScanned: 0,
+    durationMs: 0
+  });
+}
+
+export {
+  DEFAULT_EXTERNAL_DIRS,
+  DEFAULT_MAX_SCAN_DEPTH,
+  SKILL_FILENAME,
+  DEFAULT_SKILL_MAX_SIZE,
+  parseFrontmatter,
+  loadSkillMetadata,
+  loadSkillContent,
+  loadResourceContent,
+  inferResourceType,
+  discoverSkills,
+  SkillRegistry,
+  createSkillRegistry,
+  emptySkillRegistry
+};