veryfront 0.1.47 → 0.1.49

package/src/src/skill/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Agent Skills
+ *
+ * Public API for the agent skills system.
+ * Skills are project-level capabilities defined as SKILL.md files
+ * following the agentskills.io specification.
+ *
+ * @module
+ */
+
+// Types
+export type {
+  ActiveSkillContext,
+  Skill,
+  SkillContent,
+  SkillMetadata,
+  SkillScriptExecutor,
+  SkillScriptExecutorInput,
+  SkillScriptResult,
+} from "./types.js";
+
+export {
+  SKILL_ALLOWED_TOOL_PATTERN_REGEX,
+  SKILL_ASSETS_DIR,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+  SKILL_MD_FILENAME,
+  SKILL_NAME_REGEX,
+  SKILL_REFERENCES_DIR,
+  SKILL_SCRIPTS_DIR,
+  SKILL_TOOL_IDS,
+} from "./types.js";
+
+// Registry
+export { getAllSkills, getSkill, registerSkill, skillRegistry } from "./registry.js";
+
+// Parser
+export { parseSkillFrontmatter, validateSkillMetadata } from "./parser.js";
+
+// Path Safety
+export { listSkillSubdir, validateSkillPath } from "./path-safety.js";
+
+// Tools
+export {
+  createExecuteSkillScriptTool,
+  createLoadSkillReferenceTool,
+  createLoadSkillTool,
+} from "./tools.js";
+
+// Executor
+export { getSkillScriptExecutor } from "./executor.js";
+
+// Prompt
+export { buildSkillManifestPrompt } from "./prompt-augmentation.js";
+
+// Allowed-Tools
+export {
+  filterToolsForSkill,
+  isToolAllowedBySkill,
+  validateAllowedToolPatterns,
+} from "./allowed-tools.js";

package/src/src/skill/parser.ts

@@ -0,0 +1,214 @@
+/**
+ * Skill frontmatter parser
+ *
+ * Parses SKILL.md files with YAML frontmatter.
+ * Primary parser: gray-matter shim (#std/front-matter/yaml.ts)
+ * Fallback: regex + line-by-line parser
+ *
+ * @module
+ */
+
+import { createError, toError } from "../errors/veryfront-error.js";
+import {
+  SKILL_ALLOWED_TOOL_PATTERN_REGEX,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+  SKILL_NAME_REGEX,
+  type SkillMetadata,
+} from "./types.js";
+
+/** Result of parsing a SKILL.md file */
+export interface ParsedSkillContent {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * Parse SKILL.md content into frontmatter + body.
+ *
+ * Uses gray-matter shim as primary parser with a regex fallback
+ * for environments where gray-matter is not available.
+ */
+export async function parseSkillFrontmatter(content: string): Promise<ParsedSkillContent> {
+  // Try primary parser: gray-matter shim
+  try {
+    const { extract } = await import("../platform/compat/std/front-matter-yaml.js");
+    const result = extract<Record<string, unknown>>(content);
+    return { frontmatter: result.attrs, body: result.body };
+  } catch {
+    // Fall through to fallback
+  }
+
+  // Fallback: regex-based parser
+  return parseFrontmatterFallback(content);
+}
+
+/**
+ * Regex-based fallback parser for YAML frontmatter.
+ * Handles simple key: value pairs (no nested YAML).
+ */
+function parseFrontmatterFallback(content: string): ParsedSkillContent {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const rawFrontmatter = match[1]!;
+  const body = match[2]!;
+  const frontmatter: Record<string, unknown> = {};
+
+  for (const line of rawFrontmatter.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    const value = trimmed.slice(colonIndex + 1).trim();
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Validate and normalize parsed frontmatter into SkillMetadata.
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param directoryName - Directory name used as fallback for skill name
+ */
+export function validateSkillMetadata(
+  frontmatter: Record<string, unknown>,
+  directoryName: string,
+): SkillMetadata {
+  // Name: from frontmatter or directory name
+  const rawName = typeof frontmatter.name === "string" ? frontmatter.name.trim() : directoryName;
+
+  if (!SKILL_NAME_REGEX.test(rawName)) {
+    throw toError(
+      createError({
+        type: "agent",
+        message:
+          `Invalid skill name "${rawName}": must be lowercase alphanumeric with hyphens, 1-64 characters`,
+      }),
+    );
+  }
+
+  // Description: required
+  const rawDescription = frontmatter.description;
+  if (!rawDescription || typeof rawDescription !== "string" || !rawDescription.trim()) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `Skill "${rawName}" is missing a required "description" field`,
+      }),
+    );
+  }
+
+  const description = rawDescription.trim().slice(0, SKILL_DESCRIPTION_MAX_LENGTH);
+
+  // Allowed-tools: parse from space-delimited string or array
+  const allowedTools = parseAllowedTools(frontmatter["allowed-tools"], rawName);
+
+  // License: optional string passthrough
+  const license = typeof frontmatter.license === "string" ? frontmatter.license.trim() : undefined;
+
+  // Compatibility: optional string passthrough
+  const compatibility = typeof frontmatter.compatibility === "string"
+    ? frontmatter.compatibility.trim()
+    : undefined;
+
+  // Metadata: convert nested object values to strings
+  const metadata = parseMetadata(frontmatter.metadata);
+
+  return {
+    name: rawName,
+    description,
+    ...(allowedTools && { allowedTools }),
+    ...(license && { license }),
+    ...(compatibility && { compatibility }),
+    ...(metadata && { metadata }),
+  };
+}
+
+/**
+ * Parse `allowed-tools` from frontmatter.
+ * Accepts a space-delimited string or an array of strings.
+ * Validates each pattern against SKILL_ALLOWED_TOOL_PATTERN_REGEX.
+ */
+function parseAllowedTools(
+  value: unknown,
+  skillName: string,
+): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  let patterns: string[];
+
+  if (typeof value === "string") {
+    patterns = value.split(/\s+/).filter(Boolean);
+  } else if (Array.isArray(value)) {
+    patterns = [];
+    for (const rawPattern of value) {
+      if (typeof rawPattern !== "string") {
+        throw toError(
+          createError({
+            type: "agent",
+            message:
+              `Skill "${skillName}" has invalid allowed-tools value: expected all entries to be strings`,
+          }),
+        );
+      }
+      const pattern = rawPattern.trim();
+      if (!pattern) {
+        throw toError(
+          createError({
+            type: "agent",
+            message: `Skill "${skillName}" has invalid allowed-tools pattern: empty value`,
+          }),
+        );
+      }
+      patterns.push(pattern);
+    }
+  } else {
+    throw toError(
+      createError({
+        type: "agent",
+        message:
+          `Skill "${skillName}" has invalid allowed-tools value: expected a string or array of strings, got ${typeof value}`,
+      }),
+    );
+  }
+
+  if (patterns.length === 0) return undefined;
+
+  // Validate each pattern (fail closed)
+  for (const pattern of patterns) {
+    if (!SKILL_ALLOWED_TOOL_PATTERN_REGEX.test(pattern)) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: `Skill "${skillName}" has invalid allowed-tools pattern "${pattern}". ` +
+            `Only exact tool IDs (e.g. "Read") and prefix wildcards (e.g. "api:*") are supported.`,
+        }),
+      );
+    }
+  }
+
+  return patterns;
+}
+
+/** Convert metadata object values to strings */
+function parseMetadata(
+  value: unknown,
+): Record<string, string> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length === 0) return undefined;
+
+  const result: Record<string, string> = {};
+  for (const [k, v] of entries) {
+    result[k] = String(v);
+  }
+  return result;
+}

package/src/src/skill/path-safety.ts

@@ -0,0 +1,203 @@
+/**
+ * Skill path safety
+ *
+ * Validates file paths within skill directories to prevent traversal attacks.
+ * Uses centralized validatePath() from #veryfront/security.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { validatePath, type ValidationResult } from "../security/index.js";
+import { isAbsolute, join, relative, resolve } from "../platform/compat/path/index.js";
+import { exists, readDir, stat } from "../platform/compat/fs.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+import type { FileSystemAdapter } from "../platform/adapters/base.js";
+
+function isInsideDir(baseDir: string, targetPath: string): boolean {
+  const rel = relative(baseDir, targetPath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+async function pathExists(path: string, fsAdapter?: FileSystemAdapter): Promise<boolean> {
+  return fsAdapter ? await fsAdapter.exists(path) : await exists(path);
+}
+
+async function assertIsFile(path: string, fsAdapter?: FileSystemAdapter): Promise<void> {
+  const info = fsAdapter ? await fsAdapter.stat(path) : await stat(path);
+  if (!info.isFile) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `Skill path must point to a file: "${path}"`,
+      }),
+    );
+  }
+}
+
+async function resolveLocalRealPath(path: string): Promise<string> {
+  if (typeof dntShim.Deno !== "undefined") {
+    return await dntShim.Deno.realPath(path);
+  }
+  const fs = await import("node:fs/promises");
+  return await fs.realpath(path);
+}
+
+async function isLocalSymlink(path: string): Promise<boolean> {
+  try {
+    if (typeof dntShim.Deno !== "undefined") {
+      const info = await dntShim.Deno.lstat(path);
+      return info.isSymlink;
+    }
+    const fs = await import("node:fs/promises");
+    const info = await fs.lstat(path);
+    return info.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+async function isAdapterSymlink(
+  fsAdapter: FileSystemAdapter,
+  parentDir: string,
+  segment: string,
+): Promise<boolean> {
+  for await (const entry of fsAdapter.readDir(parentDir)) {
+    if (entry.name !== segment) continue;
+    return entry.isSymlink;
+  }
+  return false;
+}
+
+async function hasSymlinkInPath(
+  skillRoot: string,
+  canonicalPath: string,
+  fsAdapter?: FileSystemAdapter,
+): Promise<boolean> {
+  const resolvedRoot = resolve(skillRoot);
+  const resolvedTarget = resolve(canonicalPath);
+  const rel = relative(resolvedRoot, resolvedTarget).replaceAll("\\", "/");
+
+  if (!rel) return false;
+  if (rel.startsWith("..") || isAbsolute(rel)) return true;
+
+  let current = resolvedRoot;
+  for (const segment of rel.split("/").filter(Boolean)) {
+    if (fsAdapter) {
+      if (await isAdapterSymlink(fsAdapter, current, segment)) return true;
+    } else if (await isLocalSymlink(join(current, segment))) {
+      return true;
+    }
+    current = join(current, segment);
+  }
+  return false;
+}
+
+/**
+ * Validate that a requested path is safe within a skill's root directory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param requestedPath - Relative path requested (e.g. "references/CLAUSES.md")
+ * @param allowedSubdirs - Allowed top-level subdirectories (e.g. ["references", "assets"])
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns The validated canonical path
+ * @throws If the path is invalid, escapes the skill root, or the file doesn't exist
+ */
+export async function validateSkillPath(
+  skillRoot: string,
+  requestedPath: string,
+  allowedSubdirs: string[],
+  fsAdapter?: FileSystemAdapter,
+): Promise<string> {
+  const result: ValidationResult = await validatePath(requestedPath, {
+    baseDir: skillRoot,
+    allowedDirs: allowedSubdirs,
+    level: "strict",
+    allowAbsolute: false,
+  });
+
+  if (!result.valid) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `Skill path validation failed for "${requestedPath}": ${
+          result.error ?? "access denied"
+        }`,
+      }),
+    );
+  }
+
+  const canonicalPath = result.canonicalPath!;
+
+  // Verify the path exists and points to a file.
+  if (!(await pathExists(canonicalPath, fsAdapter))) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `File not found: "${requestedPath}" in skill directory`,
+      }),
+    );
+  }
+  await assertIsFile(canonicalPath, fsAdapter);
+
+  // Enforce strict no-symlink policy for skill files.
+  if (await hasSymlinkInPath(skillRoot, canonicalPath, fsAdapter)) {
+    throw toError(
+      createError({
+        type: "agent",
+        message: `Skill path contains a symlink and is not allowed: "${requestedPath}"`,
+      }),
+    );
+  }
+
+  // Defense-in-depth: local realpath check to block symlink escapes.
+  if (!fsAdapter) {
+    const [realRoot, realTarget] = await Promise.all([
+      resolveLocalRealPath(skillRoot),
+      resolveLocalRealPath(canonicalPath),
+    ]);
+    if (!isInsideDir(realRoot, realTarget)) {
+      throw toError(
+        createError({
+          type: "agent",
+          message: `Skill path escapes root directory via symlink: "${requestedPath}"`,
+        }),
+      );
+    }
+  }
+
+  return canonicalPath;
+}
+
+/**
+ * List files in a skill subdirectory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param subdir - Subdirectory name (e.g. "references", "scripts")
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns Array of relative paths like "references/filename.md"
+ */
+export async function listSkillSubdir(
+  skillRoot: string,
+  subdir: string,
+  fsAdapter?: FileSystemAdapter,
+): Promise<string[]> {
+  const dirPath = join(skillRoot, subdir);
+
+  const dirExists = fsAdapter ? await fsAdapter.exists(dirPath) : await exists(dirPath);
+  if (!dirExists) {
+    return [];
+  }
+
+  const files: string[] = [];
+  const entries = fsAdapter ? fsAdapter.readDir(dirPath) : readDir(dirPath);
+
+  for await (const entry of entries) {
+    if (entry.isFile) {
+      files.push(`${subdir}/${entry.name}`);
+    }
+  }
+
+  return files;
+}

package/src/src/skill/prompt-augmentation.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill Prompt Augmentation
+ *
+ * Builds the skill manifest section that gets appended to agent system prompts.
+ *
+ * @module
+ */
+
+import type { Skill } from "./types.js";
+
+/**
+ * Build the skill manifest prompt section for an agent's system prompt.
+ *
+ * Lists all available skills with their descriptions and instructions
+ * on how to use the skill tools (load-skill, load-skill-reference, execute-skill-script).
+ *
+ * @param skills - Map of resolved skills for the agent
+ * @returns Prompt section string, or empty string if no skills
+ */
+export function buildSkillManifestPrompt(skills: Map<string, Skill>): string {
+  if (skills.size === 0) return "";
+
+  const lines: string[] = [
+    "## Available Skills",
+    "",
+    "You have access to skills via tool calling. IMPORTANT: You MUST call the load-skill tool (not write it as text) to activate a skill before performing skill-related tasks.",
+    "",
+  ];
+
+  for (const [id, skill] of skills) {
+    lines.push(`- **${id}**: ${skill.metadata.description}`);
+  }
+
+  lines.push("");
+  lines.push("### Skill Tools (call these as tools, never write them as text)");
+  lines.push("");
+  lines.push(
+    "- load-skill: Call with { skillId } to load a skill's full instructions and available references/scripts",
+  );
+  lines.push(
+    "- load-skill-reference: Call with { skillId, reference } to read a reference file from the skill",
+  );
+  lines.push(
+    "- execute-skill-script: Call with { skillId, script, args?, env?, timeoutMs? } to execute a script",
+  );
+
+  return lines.join("\n");
+}

package/src/src/skill/registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Skill Registry
+ *
+ * Project-scoped registry for discovered skills.
+ * Follows the same pattern as src/tool/registry.ts.
+ *
+ * @module
+ */
+
+import type { Skill } from "./types.js";
+import { ProjectScopedRegistryManager } from "../ai/registry-manager.js";
+import { ScopedRegistryFacade } from "../ai/registry-facade.js";
+
+const skillManager = new ProjectScopedRegistryManager<Skill>("skill");
+
+class SkillRegistryClass extends ScopedRegistryFacade<Skill> {
+  /**
+   * Resolve skills for an agent configuration.
+   *
+   * @param skillsConfig - `true` for all skills, or array of specific skill IDs
+   * @returns Map of resolved skills (missing IDs are silently skipped)
+   */
+  resolveForAgent(skillsConfig: true | string[]): Map<string, Skill> {
+    if (skillsConfig === true) {
+      return this.getAll();
+    }
+
+    const result = new Map<string, Skill>();
+    for (const id of skillsConfig) {
+      const skill = this.get(id);
+      if (skill) {
+        result.set(id, skill);
+      }
+    }
+    return result;
+  }
+}
+
+export const skillRegistry = new SkillRegistryClass(skillManager);
+
+export function registerSkill(id: string, skill: Skill): void {
+  skillRegistry.register(id, skill);
+}
+
+export function getSkill(id: string): Skill | undefined {
+  return skillRegistry.get(id);
+}
+
+export function getAllSkills(): Map<string, Skill> {
+  return skillRegistry.getAll();
+}