veryfront 0.1.48 → 0.1.49

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();
+}

package/src/src/skill/tools.ts

@@ -0,0 +1,197 @@
+/**
+ * Skill Tools
+ *
+ * Three tools exposed to agents for interacting with skills:
+ * - load-skill: Load a skill's full instructions
+ * - load-skill-reference: Read a reference file from a skill
+ * - execute-skill-script: Execute a script from a skill
+ *
+ * @module
+ */
+
+import { z } from "zod";
+import { tool } from "../tool/factory.js";
+import type { Tool } from "../tool/index.js";
+import { readTextFile } from "../platform/compat/fs.js";
+import { join } from "../platform/compat/path/index.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+import { skillRegistry } from "./registry.js";
+import { parseSkillFrontmatter } from "./parser.js";
+import { listSkillSubdir, validateSkillPath } from "./path-safety.js";
+import { getSkillScriptExecutor } from "./executor.js";
+import type { Skill, SkillContent } from "./types.js";
+import {
+  SKILL_ASSETS_DIR,
+  SKILL_MD_FILENAME,
+  SKILL_REFERENCES_DIR,
+  SKILL_SCRIPTS_DIR,
+} from "./types.js";
+
+/**
+ * Read a file from a skill directory.
+ * Uses skill.fsAdapter if available (VFS/cloud), otherwise falls back to compat readTextFile.
+ */
+async function readSkillFile(skill: Skill, path: string): Promise<string> {
+  if (skill.fsAdapter) {
+    return await skill.fsAdapter.readFile(path);
+  }
+  return await readTextFile(path);
+}
+
+/**
+ * Create the load-skill tool.
+ * Loads a skill's full instructions, available references, and scripts.
+ */
+export function createLoadSkillTool(): Tool {
+  return tool({
+    id: "load-skill",
+    description: "Load a skill's full instructions. Returns the skill's markdown instructions, " +
+      "allowed tools policy, and lists of available reference files and scripts.",
+    inputSchema: z.object({
+      skillId: z.string().describe("The ID of the skill to load"),
+    }),
+    execute: async (input): Promise<SkillContent> => {
+      const skill = skillRegistry.get(input.skillId);
+      if (!skill) {
+        const available = skillRegistry.getAllIds().join(", ");
+        throw toError(
+          createError({
+            type: "agent",
+            message: `Skill "${input.skillId}" not found. Available skills: ${available || "none"}`,
+          }),
+        );
+      }
+
+      // Read SKILL.md
+      const skillMdPath = join(skill.rootPath, SKILL_MD_FILENAME);
+      const content = await readSkillFile(skill, skillMdPath);
+
+      // Parse frontmatter to get instructions
+      const parsed = await parseSkillFrontmatter(content);
+
+      // List available references and scripts
+      const references = await listSkillSubdir(
+        skill.rootPath,
+        SKILL_REFERENCES_DIR,
+        skill.fsAdapter,
+      );
+      const scripts = await listSkillSubdir(
+        skill.rootPath,
+        SKILL_SCRIPTS_DIR,
+        skill.fsAdapter,
+      );
+
+      return {
+        instructions: parsed.body,
+        allowedTools: skill.metadata.allowedTools,
+        references,
+        scripts,
+        ...(scripts.length === 0 && references.length === 0
+          ? {
+            note:
+              "This skill has no scripts or reference files. Do NOT call execute-skill-script or load-skill-reference.",
+          }
+          : scripts.length === 0
+          ? { note: "This skill has no scripts. Do NOT call execute-skill-script." }
+          : references.length === 0
+          ? { note: "This skill has no reference files. Do NOT call load-skill-reference." }
+          : {}),
+      };
+    },
+  });
+}
+
+/**
+ * Create the load-skill-reference tool.
+ * Reads a reference file from a skill's references/ or assets/ directory.
+ */
+export function createLoadSkillReferenceTool(): Tool {
+  return tool({
+    id: "load-skill-reference",
+    description: "Read a reference file from a skill. Only files in the skill's " +
+      "references/ and assets/ directories are accessible.",
+    inputSchema: z.object({
+      skillId: z.string().describe("The ID of the skill"),
+      reference: z.string().describe(
+        "Relative path to the reference file (e.g. 'references/CLAUSES.md')",
+      ),
+    }),
+    execute: async (input): Promise<{ content: string; path: string }> => {
+      const skill = skillRegistry.get(input.skillId);
+      if (!skill) {
+        throw toError(
+          createError({
+            type: "agent",
+            message: `Skill "${input.skillId}" not found`,
+          }),
+        );
+      }
+
+      // Validate path safety (only references/ and assets/ allowed)
+      const validatedPath = await validateSkillPath(
+        skill.rootPath,
+        input.reference,
+        [SKILL_REFERENCES_DIR, SKILL_ASSETS_DIR],
+        skill.fsAdapter,
+      );
+
+      const content = await readSkillFile(skill, validatedPath);
+      return { content, path: input.reference };
+    },
+  });
+}
+
+/**
+ * Create the execute-skill-script tool.
+ * Executes a script from a skill's scripts/ directory.
+ */
+export function createExecuteSkillScriptTool(): Tool {
+  return tool({
+    id: "execute-skill-script",
+    description:
+      "Execute a script from a skill's scripts/ directory. Returns stdout, stderr, and exit code.",
+    inputSchema: z.object({
+      skillId: z.string().describe("The ID of the skill"),
+      script: z.string().describe("Relative path to the script (e.g. 'scripts/setup.sh')"),
+      args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
+      env: z.record(z.string()).optional().describe("Environment variables for the script"),
+      timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(300_000)
+        .optional()
+        .describe("Optional execution timeout in milliseconds (max 300000)"),
+    }),
+    execute: async (input) => {
+      const skill = skillRegistry.get(input.skillId);
+      if (!skill) {
+        throw toError(
+          createError({
+            type: "agent",
+            message: `Skill "${input.skillId}" not found`,
+          }),
+        );
+      }
+
+      // Validate path safety (only scripts/ allowed)
+      const validatedPath = await validateSkillPath(
+        skill.rootPath,
+        input.script,
+        [SKILL_SCRIPTS_DIR],
+        skill.fsAdapter,
+      );
+
+      const scriptContent = await readSkillFile(skill, validatedPath);
+      const executor = getSkillScriptExecutor();
+      return await executor.execute({
+        scriptPath: validatedPath,
+        scriptContent,
+        args: input.args,
+        env: input.env,
+        cwd: skill.rootPath,
+        timeoutMs: input.timeoutMs,
+      });
+    },
+  });
+}

package/src/src/skill/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Skill type definitions
+ *
+ * Follows the agentskills.io specification.
+ * Pure type/const file — no runtime dependencies.
+ *
+ * @module
+ */
+
+import type { FileSystemAdapter } from "../platform/adapters/base.js";
+
+// ── Constants ───────────────────────────────────────────────────────────
+
+/** Valid skill name: lowercase alphanumeric + hyphens, 1-64 chars */
+export const SKILL_NAME_REGEX = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Valid allowed-tool pattern: exact ID or prefix wildcard (e.g. "api:*") */
+export const SKILL_ALLOWED_TOOL_PATTERN_REGEX =
+  /^[A-Za-z][A-Za-z0-9._-]*(:[A-Za-z][A-Za-z0-9._-]*)*(:\*)?$/;
+
+/** Maximum description length in characters */
+export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+
+/** Standard SKILL.md filename per agentskills.io spec */
+export const SKILL_MD_FILENAME = "SKILL.md";
+
+/** Tool IDs that belong to the skill system (single source of truth) */
+export const SKILL_TOOL_IDS = new Set([
+  "load-skill",
+  "load-skill-reference",
+  "execute-skill-script",
+]);
+
+/** Conventional subdirectory names */
+export const SKILL_SCRIPTS_DIR = "scripts";
+export const SKILL_REFERENCES_DIR = "references";
+export const SKILL_ASSETS_DIR = "assets";
+
+// ── Interfaces ──────────────────────────────────────────────────────────
+
+/** Parsed frontmatter metadata from SKILL.md */
+export interface SkillMetadata {
+  /** Skill identifier (lowercase, hyphenated) */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Tool access restrictions (space-delimited in YAML, parsed to array) */
+  allowedTools?: string[];
+  /** SPDX license identifier */
+  license?: string;
+  /** Compatibility constraints */
+  compatibility?: string;
+  /** Arbitrary key-value metadata */
+  metadata?: Record<string, string>;
+}
+
+/** Full skill content returned by load-skill tool */
+export interface SkillContent {
+  /** Markdown instructions (body after frontmatter) */
+  instructions: string;
+  /** Tool access restrictions from frontmatter */
+  allowedTools?: string[];
+  /** Available reference file paths */
+  references: string[];
+  /** Available script file paths */
+  scripts: string[];
+}
+
+/** Registered skill instance */
+export interface Skill {
+  /** Unique skill ID (matches directory name) */
+  id: string;
+  /** Parsed frontmatter metadata */
+  metadata: SkillMetadata;
+  /** Absolute path to the skill directory */
+  rootPath: string;
+  /** Optional filesystem adapter for VFS/cloud-backed projects */
+  fsAdapter?: FileSystemAdapter;
+}
+
+/** Result from executing a skill script */
+export interface SkillScriptResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** Input for the script executor */
+export interface SkillScriptExecutorInput {
+  scriptPath: string;
+  scriptContent?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+/** Script executor interface */
+export interface SkillScriptExecutor {
+  execute(input: SkillScriptExecutorInput): Promise<SkillScriptResult>;
+}
+
+/** Active skill context for runtime policy tracking */
+export interface ActiveSkillContext {
+  skillId: string;
+  allowedTools?: string[];
+}