veryfront 0.1.47 → 0.1.49

package/esm/src/skill/executor.js

@@ -0,0 +1,187 @@
+/**
+ * Skill Script Executor
+ *
+ * Executes skill scripts using cross-runtime subprocess execution.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+import { getEnv, runCommand } from "../platform/compat/process.js";
+import { isDeno } from "../platform/compat/runtime.js";
+import { extname } from "../platform/compat/path/index.js";
+import { readTextFile } from "../platform/compat/fs.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+const DEFAULT_SCRIPT_TIMEOUT_MS = 60_000;
+const MAX_SCRIPT_TIMEOUT_MS = 300_000;
+const TIMEOUT_EXIT_CODE = 124;
+const ENV_KEY_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TIMEOUT_SENTINEL = Symbol("skill-script-timeout");
+function resolveTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return DEFAULT_SCRIPT_TIMEOUT_MS;
+    }
+    return Math.min(Math.floor(timeoutMs), MAX_SCRIPT_TIMEOUT_MS);
+}
+async function withTimeout(promise, timeoutMs) {
+    let timeoutId;
+    const timeoutPromise = new Promise((resolve) => {
+        timeoutId = dntShim.setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+function timeoutResult(timeoutMs) {
+    return {
+        stdout: "",
+        stderr: `Script execution timed out after ${timeoutMs}ms`,
+        exitCode: TIMEOUT_EXIT_CODE,
+    };
+}
+function shellEscapeArg(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function buildShellCommand(parts) {
+    return parts.map(shellEscapeArg).join(" ");
+}
+function formatEnvAssignments(env) {
+    if (!env)
+        return [];
+    return Object.entries(env).map(([key, value]) => {
+        if (!ENV_KEY_REGEX.test(key)) {
+            throw toError(createError({
+                type: "agent",
+                message: `Invalid environment variable name: "${key}"`,
+            }));
+        }
+        return `${key}=${value}`;
+    });
+}
+function createSandboxScriptPath(scriptPath) {
+    const ext = extname(scriptPath) || ".sh";
+    const suffix = Math.random().toString(36).slice(2, 10);
+    return `/tmp/veryfront-skill-script-${Date.now()}-${suffix}${ext}`;
+}
+/**
+ * Detect the runtime command for a script based on file extension.
+ */
+export function detectRuntime(scriptPath) {
+    const ext = extname(scriptPath).toLowerCase();
+    switch (ext) {
+        case ".py":
+            return { command: "python3", args: [scriptPath] };
+        case ".sh":
+            return { command: "bash", args: [scriptPath] };
+        case ".js":
+            return { command: "node", args: [scriptPath] };
+        case ".ts":
+            if (isDeno) {
+                return {
+                    command: "deno",
+                    args: ["run", "--allow-read", "--allow-env", "--allow-net", "--allow-write", scriptPath],
+                };
+            }
+            return { command: "npx", args: ["tsx", scriptPath] };
+        default:
+            return { command: scriptPath, args: [] };
+    }
+}
+/**
+ * Local script executor using runCommand() from the compat layer.
+ */
+export class LocalScriptExecutor {
+    async execute(input) {
+        const timeoutMs = resolveTimeoutMs(input.timeoutMs);
+        const { command, args: runtimeArgs } = detectRuntime(input.scriptPath);
+        const allArgs = [...runtimeArgs, ...(input.args ?? [])];
+        // Remove the script path from args if it's already the command
+        const finalArgs = command === input.scriptPath ? (input.args ?? []) : allArgs;
+        const result = await runCommand(command, {
+            args: finalArgs,
+            cwd: input.cwd,
+            env: input.env,
+            capture: true,
+            timeoutMs,
+        });
+        return {
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            exitCode: result.code,
+        };
+    }
+}
+/**
+ * Cloud script executor using sandbox.
+ * Requires SANDBOX_AUTH_TOKEN environment variable.
+ */
+export class CloudScriptExecutor {
+    async execute(input) {
+        const timeoutMs = resolveTimeoutMs(input.timeoutMs);
+        // NOTE: In SSR contexts, getEnv() reads through the project-env overlay
+        // (AsyncLocalStorage-backed). If the token is set at host level only,
+        // the overlay may not surface it. Ensure SANDBOX_AUTH_TOKEN is available
+        // in the request-scoped environment when running under SSR.
+        const authToken = getEnv("SANDBOX_AUTH_TOKEN");
+        if (!authToken) {
+            throw toError(createError({
+                type: "agent",
+                message: "Cloud script execution requires SANDBOX_AUTH_TOKEN environment variable",
+            }));
+        }
+        // Lazy import to avoid bundling sandbox in non-cloud environments
+        const { Sandbox } = await import("../sandbox/index.js");
+        const sandbox = await Sandbox.create({ authToken });
+        try {
+            const sandboxScriptPath = createSandboxScriptPath(input.scriptPath);
+            const scriptContent = input.scriptContent ?? await readTextFile(input.scriptPath);
+            await sandbox.writeFiles([{ path: sandboxScriptPath, content: scriptContent }]);
+            await sandbox.executeCommand(buildShellCommand(["chmod", "+x", sandboxScriptPath]));
+            const { command, args: runtimeArgs } = detectRuntime(sandboxScriptPath);
+            const allArgs = [...runtimeArgs, ...(input.args ?? [])];
+            const finalArgs = command === sandboxScriptPath ? (input.args ?? []) : allArgs;
+            const envAssignments = formatEnvAssignments(input.env);
+            const commandParts = envAssignments.length > 0
+                ? ["env", ...envAssignments, command, ...finalArgs]
+                : [command, ...finalArgs];
+            const cmdString = buildShellCommand(commandParts);
+            const commandPromise = sandbox.executeCommand(cmdString);
+            const result = await withTimeout(commandPromise, timeoutMs);
+            if (result === TIMEOUT_SENTINEL) {
+                // Kill any running processes before returning — withTimeout only
+                // races the timer, it doesn't terminate the sandbox command.
+                try {
+                    await sandbox.executeCommand("kill -9 -1 2>/dev/null || true");
+                }
+                catch {
+                    // Best-effort kill; sandbox.close() in finally will clean up.
+                }
+                return timeoutResult(timeoutMs);
+            }
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode,
+            };
+        }
+        finally {
+            try {
+                await sandbox.close();
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+    }
+}
+/**
+ * Get the appropriate script executor.
+ * Checks SANDBOX_AUTH_TOKEN on every call so request-scoped env overlays
+ * (e.g. project-env AsyncLocalStorage) are respected.
+ */
+export function getSkillScriptExecutor() {
+    return getEnv("SANDBOX_AUTH_TOKEN") ? new CloudScriptExecutor() : new LocalScriptExecutor();
+}

package/esm/src/skill/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+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";
+export { getAllSkills, getSkill, registerSkill, skillRegistry } from "./registry.js";
+export { parseSkillFrontmatter, validateSkillMetadata } from "./parser.js";
+export { listSkillSubdir, validateSkillPath } from "./path-safety.js";
+export { createExecuteSkillScriptTool, createLoadSkillReferenceTool, createLoadSkillTool, } from "./tools.js";
+export { getSkillScriptExecutor } from "./executor.js";
+export { buildSkillManifestPrompt } from "./prompt-augmentation.js";
+export { filterToolsForSkill, isToolAllowedBySkill, validateAllowedToolPatterns, } from "./allowed-tools.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/skill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/skill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EACV,kBAAkB,EAClB,KAAK,EACL,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGrF,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG3E,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGtE,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC"}

package/esm/src/skill/index.js

@@ -0,0 +1,24 @@
+/**
+ * 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
+ */
+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/esm/src/skill/parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { 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 declare function parseSkillFrontmatter(content: string): Promise<ParsedSkillContent>;
+/**
+ * Validate and normalize parsed frontmatter into SkillMetadata.
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param directoryName - Directory name used as fallback for skill name
+ */
+export declare function validateSkillMetadata(frontmatter: Record<string, unknown>, directoryName: string): SkillMetadata;
+//# sourceMappingURL=parser.d.ts.map

package/esm/src/skill/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/src/skill/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYxF;AA+BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,aAAa,EAAE,MAAM,GACpB,aAAa,CAiDf"}

package/esm/src/skill/parser.js

@@ -0,0 +1,162 @@
+/**
+ * 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, } from "./types.js";
+/**
+ * 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) {
+    // Try primary parser: gray-matter shim
+    try {
+        const { extract } = await import("../platform/compat/std/front-matter-yaml.js");
+        const result = extract(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) {
+    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 = {};
+    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, directoryName) {
+    // 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, skillName) {
+    if (value === undefined || value === null)
+        return undefined;
+    let patterns;
+    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) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return undefined;
+    const result = {};
+    for (const [k, v] of entries) {
+        result[k] = String(v);
+    }
+    return result;
+}

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

@@ -0,0 +1,22 @@
+import type { FileSystemAdapter } from "../platform/adapters/base.js";
+/**
+ * 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 declare function validateSkillPath(skillRoot: string, requestedPath: string, allowedSubdirs: string[], fsAdapter?: FileSystemAdapter): Promise<string>;
+/**
+ * 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 declare function listSkillSubdir(skillRoot: string, subdir: string, fsAdapter?: FileSystemAdapter): Promise<string[]>;
+//# sourceMappingURL=path-safety.d.ts.map

package/esm/src/skill/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../../src/src/skill/path-safety.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAiFtE;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA2DjB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB"}

package/esm/src/skill/path-safety.js

@@ -0,0 +1,156 @@
+/**
+ * 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 } 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";
+function isInsideDir(baseDir, targetPath) {
+    const rel = relative(baseDir, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+async function pathExists(path, fsAdapter) {
+    return fsAdapter ? await fsAdapter.exists(path) : await exists(path);
+}
+async function assertIsFile(path, fsAdapter) {
+    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) {
+    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) {
+    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, parentDir, segment) {
+    for await (const entry of fsAdapter.readDir(parentDir)) {
+        if (entry.name !== segment)
+            continue;
+        return entry.isSymlink;
+    }
+    return false;
+}
+async function hasSymlinkInPath(skillRoot, canonicalPath, fsAdapter) {
+    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, requestedPath, allowedSubdirs, fsAdapter) {
+    const result = 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, subdir, fsAdapter) {
+    const dirPath = join(skillRoot, subdir);
+    const dirExists = fsAdapter ? await fsAdapter.exists(dirPath) : await exists(dirPath);
+    if (!dirExists) {
+        return [];
+    }
+    const files = [];
+    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/esm/src/skill/prompt-augmentation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function buildSkillManifestPrompt(skills: Map<string, Skill>): string;
+//# sourceMappingURL=prompt-augmentation.d.ts.map

package/esm/src/skill/prompt-augmentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-augmentation.d.ts","sourceRoot":"","sources":["../../../src/src/skill/prompt-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,CA4B3E"}

package/esm/src/skill/prompt-augmentation.js

@@ -0,0 +1,36 @@
+/**
+ * Skill Prompt Augmentation
+ *
+ * Builds the skill manifest section that gets appended to agent system prompts.
+ *
+ * @module
+ */
+/**
+ * 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) {
+    if (skills.size === 0)
+        return "";
+    const lines = [
+        "## 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");
+}