@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/agent/src/core/skills.ts

@@ -1,338 +1,23 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "fs";
-import ignore from "ignore";
-import { basename, dirname, join, relative, resolve, sep } from "path";
-import { CONFIG_DIR_NAME, getAgentDir } from "../config.ts";
-import { parseFrontmatter } from "../utils/frontmatter.ts";
-import { canonicalizePath, resolvePath } from "../utils/paths.ts";
-import type { ResourceDiagnostic } from "./diagnostics.ts";
-import { createSyntheticSourceInfo, type SourceInfo } from "./source-info.ts";
-
-/** Max name length per spec */
-const MAX_NAME_LENGTH = 64;
-
-/** Max description length per spec */
-const MAX_DESCRIPTION_LENGTH = 1024;
-
-const IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"];
-
-type IgnoreMatcher = ReturnType<typeof ignore>;
-
-function toPosixPath(p: string): string {
-	return p.split(sep).join("/");
-}
-
-function prefixIgnorePattern(line: string, prefix: string): string | null {
-	const trimmed = line.trim();
-	if (!trimmed) return null;
-	if (trimmed.startsWith("#") && !trimmed.startsWith("\\#")) return null;
-
-	let pattern = line;
-	let negated = false;
-
-	if (pattern.startsWith("!")) {
-		negated = true;
-		pattern = pattern.slice(1);
-	} else if (pattern.startsWith("\\!")) {
-		pattern = pattern.slice(1);
-	}
-
-	if (pattern.startsWith("/")) {
-		pattern = pattern.slice(1);
-	}
-
-	const prefixed = prefix ? `${prefix}${pattern}` : pattern;
-	return negated ? `!${prefixed}` : prefixed;
-}
-
-function addIgnoreRules(ig: IgnoreMatcher, dir: string, rootDir: string): void {
-	const relativeDir = relative(rootDir, dir);
-	const prefix = relativeDir ? `${toPosixPath(relativeDir)}/` : "";
-
-	for (const filename of IGNORE_FILE_NAMES) {
-		const ignorePath = join(dir, filename);
-		if (!existsSync(ignorePath)) continue;
-		try {
-			const content = readFileSync(ignorePath, "utf-8");
-			const patterns = content
-				.split(/\r?\n/)
-				.map((line) => prefixIgnorePattern(line, prefix))
-				.filter((line): line is string => Boolean(line));
-			if (patterns.length > 0) {
-				ig.add(patterns);
-			}
-		} catch {}
-	}
-}
-
-export interface SkillFrontmatter {
-	name?: string;
-	description?: string;
-	"disable-model-invocation"?: boolean;
-	[key: string]: unknown;
-}
-
+/** A skill the host has read and checked; the agent runtime reads no skill files itself. */
 export interface Skill {
 	name: string;
 	description: string;
+	/** Where the host reads the SKILL.md. */
 	filePath: string;
 	baseDir: string;
-	sourceInfo: SourceInfo;
+	/** How the model's tools reach the SKILL.md; its folder holds the skill's other files. */
+	location: string;
 	disableModelInvocation: boolean;
 }
 
-export interface LoadSkillsResult {
-	skills: Skill[];
-	diagnostics: ResourceDiagnostic[];
-}
-
-/**
- * Validate skill name per Agent Skills spec.
- * Returns array of validation error messages (empty if valid).
- */
-function validateName(name: string): string[] {
-	const errors: string[] = [];
-
-	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;
-}
-
-/**
- * Validate description per Agent Skills spec.
- */
-function validateDescription(description: string | undefined): string[] {
-	const errors: string[] = [];
-
-	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;
-}
-
-export interface LoadSkillsFromDirOptions {
-	/** Directory to scan for skills */
-	dir: string;
-	/** Source identifier for these skills */
-	source: string;
-}
-
-function createSkillSourceInfo(filePath: string, baseDir: string, source: string): SourceInfo {
-	switch (source) {
-		case "user":
-			return createSyntheticSourceInfo(filePath, {
-				source: "local",
-				scope: "user",
-				baseDir,
-			});
-		case "project":
-			return createSyntheticSourceInfo(filePath, {
-				source: "local",
-				scope: "project",
-				baseDir,
-			});
-		case "path":
-			return createSyntheticSourceInfo(filePath, {
-				source: "local",
-				baseDir,
-			});
-		default:
-			return createSyntheticSourceInfo(filePath, { source, baseDir });
-	}
-}
-
-/**
- * Load skills from a directory.
- *
- * Discovery rules:
- * - if a directory contains SKILL.md, treat it as a skill root and do not recurse further
- * - otherwise, load direct .md children in the root
- * - recurse into subdirectories to find SKILL.md
- */
-export function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult {
-	const { dir, source } = options;
-	return loadSkillsFromDirInternal(dir, source, true);
-}
-
-function loadSkillsFromDirInternal(
-	dir: string,
-	source: string,
-	includeRootFiles: boolean,
-	ignoreMatcher?: IgnoreMatcher,
-	rootDir?: string,
-): LoadSkillsResult {
-	const skills: Skill[] = [];
-	const diagnostics: ResourceDiagnostic[] = [];
-
-	if (!existsSync(dir)) {
-		return { skills, diagnostics };
-	}
-
-	const root = rootDir ?? dir;
-	const ig = ignoreMatcher ?? ignore();
-	addIgnoreRules(ig, dir, root);
-
-	try {
-		const entries = readdirSync(dir, { withFileTypes: true });
-
-		for (const entry of entries) {
-			if (entry.name !== "SKILL.md") {
-				continue;
-			}
-
-			const fullPath = join(dir, entry.name);
-
-			let isFile = entry.isFile();
-			if (entry.isSymbolicLink()) {
-				try {
-					isFile = statSync(fullPath).isFile();
-				} catch {
-					continue;
-				}
-			}
-
-			const relPath = toPosixPath(relative(root, fullPath));
-			if (!isFile || ig.ignores(relPath)) {
-				continue;
-			}
-
-			const result = loadSkillFromFile(fullPath, source);
-			if (result.skill) {
-				skills.push(result.skill);
-			}
-			diagnostics.push(...result.diagnostics);
-			return { skills, diagnostics };
-		}
-
-		for (const entry of entries) {
-			if (entry.name.startsWith(".")) {
-				continue;
-			}
-
-			// Skip node_modules to avoid scanning dependencies
-			if (entry.name === "node_modules") {
-				continue;
-			}
-
-			const fullPath = join(dir, entry.name);
-
-			// For symlinks, check if they point to a directory and follow them
-			let isDirectory = entry.isDirectory();
-			let isFile = entry.isFile();
-			if (entry.isSymbolicLink()) {
-				try {
-					const stats = statSync(fullPath);
-					isDirectory = stats.isDirectory();
-					isFile = stats.isFile();
-				} catch {
-					// Broken symlink, skip it
-					continue;
-				}
-			}
-
-			const relPath = toPosixPath(relative(root, fullPath));
-			const ignorePath = isDirectory ? `${relPath}/` : relPath;
-			if (ig.ignores(ignorePath)) {
-				continue;
-			}
-
-			if (isDirectory) {
-				const subResult = loadSkillsFromDirInternal(fullPath, source, false, ig, root);
-				skills.push(...subResult.skills);
-				diagnostics.push(...subResult.diagnostics);
-				continue;
-			}
-
-			if (!isFile || !includeRootFiles || !entry.name.endsWith(".md")) {
-				continue;
-			}
-
-			const result = loadSkillFromFile(fullPath, source);
-			if (result.skill) {
-				skills.push(result.skill);
-			}
-			diagnostics.push(...result.diagnostics);
-		}
-	} catch {}
-
-	return { skills, diagnostics };
-}
-
-function loadSkillFromFile(
-	filePath: string,
-	source: string,
-): { skill: Skill | null; diagnostics: ResourceDiagnostic[] } {
-	const diagnostics: ResourceDiagnostic[] = [];
-
-	try {
-		const rawContent = readFileSync(filePath, "utf-8");
-		const { frontmatter } = parseFrontmatter<SkillFrontmatter>(rawContent);
-		const skillDir = dirname(filePath);
-		const parentDirName = basename(skillDir);
-
-		// Validate description
-		const descErrors = validateDescription(frontmatter.description);
-		for (const error of descErrors) {
-			diagnostics.push({ type: "warning", message: error, path: filePath });
-		}
-
-		// Use name from frontmatter, or fall back to parent directory name
-		const name = frontmatter.name || parentDirName;
-
-		// Validate name
-		const nameErrors = validateName(name);
-		for (const error of nameErrors) {
-			diagnostics.push({ type: "warning", message: error, path: filePath });
-		}
-
-		// Still load the skill even with warnings (unless description is completely missing)
-		if (!frontmatter.description || frontmatter.description.trim() === "") {
-			return { skill: null, diagnostics };
-		}
-
-		return {
-			skill: {
-				name,
-				description: frontmatter.description,
-				filePath,
-				baseDir: skillDir,
-				sourceInfo: createSkillSourceInfo(filePath, skillDir, source),
-				disableModelInvocation: frontmatter["disable-model-invocation"] === true,
-			},
-			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 };
-	}
-}
-
 /**
  * Format skills for inclusion in a system prompt.
  * Uses XML format per Agent Skills standard.
  * See: https://agentskills.io/integrate-skills
  *
- * Skills with disableModelInvocation=true are excluded from the prompt
- * (they can only be invoked explicitly via /skill:name commands).
+ * Skills with disableModelInvocation=true are excluded from the prompt.
  */
-export function formatSkillsForPrompt(skills: Skill[]): string {
+export function formatSkillsForPrompt(skills: readonly Skill[]): string {
 	const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
 
 	if (visibleSkills.length === 0) {
@@ -342,7 +27,7 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
 	const lines = [
 		"\n\nThe 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.",
+		"When a skill file references a relative path, resolve it against the skill's folder (its location without SKILL.md) and use that path with the tools. Skill folders are read-only.",
 		"",
 		"<available_skills>",
 	];
@@ -351,7 +36,7 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
 		lines.push("  <skill>");
 		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
 		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
-		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+		lines.push(`    <location>${escapeXml(skill.location)}</location>`);
 		lines.push("  </skill>");
 	}
 
@@ -368,120 +53,3 @@ function escapeXml(str: string): string {
 		.replace(/"/g, "&quot;")
 		.replace(/'/g, "&apos;");
 }
-
-export interface LoadSkillsOptions {
-	/** Working directory for project-local skills. */
-	cwd: string;
-	/** Agent config directory for global skills. */
-	agentDir: string;
-	/** Explicit skill paths (files or directories) */
-	skillPaths: string[];
-	/** Include default skills directories. */
-	includeDefaults: boolean;
-}
-
-/**
- * Load skills from all configured locations.
- * Returns skills and any validation diagnostics.
- */
-export function loadSkills(options: LoadSkillsOptions): LoadSkillsResult {
-	const { agentDir, skillPaths, includeDefaults } = options;
-
-	// Resolve agentDir - if not provided, use default from config
-	const resolvedCwd = resolvePath(options.cwd);
-	const resolvedAgentDir = resolvePath(agentDir ?? getAgentDir());
-
-	const skillMap = new Map<string, Skill>();
-	const realPathSet = new Set<string>();
-	const allDiagnostics: ResourceDiagnostic[] = [];
-	const collisionDiagnostics: ResourceDiagnostic[] = [];
-
-	function addSkills(result: LoadSkillsResult) {
-		allDiagnostics.push(...result.diagnostics);
-		for (const skill of result.skills) {
-			// Resolve symlinks to detect duplicate files
-			const realPath = canonicalizePath(skill.filePath);
-
-			// Skip silently if we've already loaded this exact file (via symlink)
-			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) {
-		addSkills(loadSkillsFromDirInternal(join(resolvedAgentDir, "skills"), "user", true));
-		addSkills(loadSkillsFromDirInternal(resolve(resolvedCwd, CONFIG_DIR_NAME, "skills"), "project", true));
-	}
-
-	const userSkillsDir = join(resolvedAgentDir, "skills");
-	const projectSkillsDir = resolve(resolvedCwd, CONFIG_DIR_NAME, "skills");
-
-	const isUnderPath = (target: string, root: string): boolean => {
-		const normalizedRoot = resolve(root);
-		if (target === normalizedRoot) {
-			return true;
-		}
-		const prefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
-		return target.startsWith(prefix);
-	};
-
-	const getSource = (resolvedPath: string): "user" | "project" | "path" => {
-		if (!includeDefaults) {
-			if (isUnderPath(resolvedPath, userSkillsDir)) return "user";
-			if (isUnderPath(resolvedPath, projectSkillsDir)) return "project";
-		}
-		return "path";
-	};
-
-	for (const rawPath of skillPaths) {
-		const resolvedPath = resolvePath(rawPath, resolvedCwd, { trim: true });
-		if (!existsSync(resolvedPath)) {
-			allDiagnostics.push({ type: "warning", message: "skill path does not exist", path: resolvedPath });
-			continue;
-		}
-
-		try {
-			const stats = statSync(resolvedPath);
-			const source = getSource(resolvedPath);
-			if (stats.isDirectory()) {
-				addSkills(loadSkillsFromDirInternal(resolvedPath, source, true));
-			} else if (stats.isFile() && resolvedPath.endsWith(".md")) {
-				const result = loadSkillFromFile(resolvedPath, source);
-				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],
-	};
-}

package/packages/agent/src/core/source-info.ts

@@ -1,5 +1,3 @@
-import type { PathMetadata } from "./package-manager.ts";
-
 export type SourceScope = "user" | "project" | "temporary";
 export type SourceOrigin = "package" | "top-level";
 
@@ -11,16 +9,6 @@ export interface SourceInfo {
 	baseDir?: string;
 }
 
-export function createSourceInfo(path: string, metadata: PathMetadata): SourceInfo {
-	return {
-		path,
-		source: metadata.source,
-		scope: metadata.scope,
-		origin: metadata.origin,
-		baseDir: metadata.baseDir,
-	};
-}
-
 export function createSyntheticSourceInfo(
 	path: string,
 	options: {

package/packages/agent/src/core/system-prompt.ts

@@ -13,14 +13,10 @@ export interface BuildSystemPromptOptions {
 	toolSnippets?: Record<string, string>;
 	/** Additional guideline bullets appended to the default system prompt guidelines. */
 	promptGuidelines?: string[];
-	/** Text to append to system prompt. */
-	appendSystemPrompt?: string;
-	/** Working directory. */
+	/** Working directory; only the default prompt names it, a custom prompt stays as the caller wrote it. */
 	cwd: string;
-	/** Pre-loaded context files. */
-	contextFiles?: Array<{ path: string; content: string }>;
 	/** Pre-loaded skills. */
-	skills?: Skill[];
+	skills?: readonly Skill[];
 }
 
 /** Build the system prompt with tools, guidelines, and context */
@@ -30,43 +26,22 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions): string {
 		selectedTools,
 		toolSnippets,
 		promptGuidelines,
-		appendSystemPrompt,
 		cwd,
-		contextFiles: providedContextFiles,
 		skills: providedSkills,
 	} = options;
 	const promptCwd = cwd.replace(/\\/g, "/");
 
-	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
-
-	const contextFiles = providedContextFiles ?? [];
 	const skills = providedSkills ?? [];
 
 	if (customPrompt) {
 		let prompt = customPrompt;
 
-		if (appendSection) {
-			prompt += appendSection;
-		}
-
-		// Append project context files
-		if (contextFiles.length > 0) {
-			prompt += "\n\n<project_context>\n\n";
-			prompt += "Project-specific instructions and guidelines:\n\n";
-			for (const { path: filePath, content } of contextFiles) {
-				prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
-			}
-			prompt += "</project_context>\n";
-		}
-
 		// Append skills section (only if read tool is available)
 		const customPromptHasRead = !selectedTools || selectedTools.includes("read");
 		if (customPromptHasRead && skills.length > 0) {
 			prompt += formatSkillsForPrompt(skills);
 		}
 
-		prompt += `\nCurrent working directory: ${promptCwd}`;
-
 		return prompt;
 	}
 
@@ -122,20 +97,6 @@ Guidelines:
 ${guidelines}
 `;
 
-	if (appendSection) {
-		prompt += appendSection;
-	}
-
-	// Append project context files
-	if (contextFiles.length > 0) {
-		prompt += "\n\n<project_context>\n\n";
-		prompt += "Project-specific instructions and guidelines:\n\n";
-		for (const { path: filePath, content } of contextFiles) {
-			prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
-		}
-		prompt += "</project_context>\n";
-	}
-
 	// Append skills section (only if read tool is available)
 	if (hasRead && skills.length > 0) {
 		prompt += formatSkillsForPrompt(skills);