@clinebot/core 0.0.21 → 0.0.23

package/src/agents/agent-config-loader.test.ts

@@ -0,0 +1,236 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Tool, ToolContext } from "@clinebot/agents";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	createAgentConfigDefinition,
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	readAgentConfigsFromDisk,
+	resolveAgentConfigSearchPaths,
+	resolveAgentsConfigDirPath,
+	resolveAgentTools,
+	resolveDocumentsAgentConfigDirectoryPath,
+	toPartialAgentConfig,
+} from "./agent-config-loader";
+
+function createMockTool(name: string): Tool {
+	return {
+		name,
+		description: `${name} tool`,
+		inputSchema: {
+			type: "object",
+			properties: {},
+		},
+		execute: async (_input: unknown, _context: ToolContext) => null,
+	};
+}
+
+describe("agent config YAML loader", () => {
+	const envSnapshot = {
+		CLINE_DATA_DIR: process.env.CLINE_DATA_DIR,
+	};
+	afterEach(() => {
+		process.env.CLINE_DATA_DIR = envSnapshot.CLINE_DATA_DIR;
+	});
+
+	it("resolves default agents settings directory from CLINE_DATA_DIR", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		expect(resolveAgentsConfigDirPath()).toBe(
+			join("/tmp/cline-data", "settings", AGENT_CONFIG_DIRECTORY_NAME),
+		);
+	});
+
+	it("includes documents and settings search paths", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		expect(resolveAgentConfigSearchPaths()).toEqual([
+			resolveDocumentsAgentConfigDirectoryPath(),
+			join("/tmp/cline-data", "settings", AGENT_CONFIG_DIRECTORY_NAME),
+		]);
+	});
+
+	it("builds a reusable unified watcher definition with expected defaults", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		const definition = createAgentConfigDefinition();
+		expect(definition.type).toBe("agent");
+		expect(definition.directories).toEqual([
+			resolveDocumentsAgentConfigDirectoryPath(),
+			join("/tmp/cline-data", "settings", AGENT_CONFIG_DIRECTORY_NAME),
+		]);
+		expect(definition.includeFile?.("agent.yaml", "/tmp/agent.yaml")).toBe(
+			true,
+		);
+		expect(definition.includeFile?.("agent.md", "/tmp/agent.md")).toBe(false);
+	});
+
+	it("parses yaml frontmatter and prompt body", () => {
+		const content = `---
+name: Researcher
+description: Focus on repository analysis
+modelId: claude-sonnet-4-6
+tools:
+  - read_files
+  - search_codebase
+skills:
+  - context-gathering
+---
+You are a focused codebase researcher.`;
+
+		const parsed = parseAgentConfigFromYaml(content);
+
+		expect(parsed).toEqual({
+			name: "Researcher",
+			description: "Focus on repository analysis",
+			modelId: "claude-sonnet-4-6",
+			tools: ["read_files", "search_codebase"],
+			skills: ["context-gathering"],
+			systemPrompt: "You are a focused codebase researcher.",
+		});
+	});
+
+	it("supports comma-separated tool and skill values", () => {
+		const parsed = parseAgentConfigFromYaml(`---
+name: Reviewer
+description: Reviews diffs
+tools: read_files,search_codebase,read_files
+skills: quality, quality,architecture
+---
+Review every patch for regressions.`);
+
+		expect(parsed.tools).toEqual(["read_files", "search_codebase"]);
+		expect(parsed.skills).toEqual(["quality", "architecture"]);
+	});
+
+	it("throws when frontmatter is missing", () => {
+		expect(() => parseAgentConfigFromYaml("No frontmatter")).toThrow(
+			"Missing YAML frontmatter block in agent config file.",
+		);
+	});
+
+	it("throws for unknown tools", () => {
+		expect(() =>
+			parseAgentConfigFromYaml(`---
+name: UnknownTool
+description: test
+tools: invalid_tool
+---
+prompt`),
+		).toThrow("Unknown tool 'invalid_tool'.");
+	});
+
+	it("resolves configured tool names from available tools", () => {
+		const readFiles = createMockTool("read_files");
+		const searchCodebase = createMockTool("search_codebase");
+
+		expect(
+			resolveAgentTools(
+				["read_files", "search_codebase"],
+				[searchCodebase, readFiles],
+			),
+		).toEqual([readFiles, searchCodebase]);
+	});
+
+	it("converts parsed config to partial AgentConfig", () => {
+		const readFiles = createMockTool("read_files");
+		const config = parseAgentConfigFromYaml(`---
+name: Reader
+description: Reads files
+modelId: claude-sonnet-4-6
+tools: read_files
+skills: commit, review
+---
+Be precise.`);
+
+		const partial = toPartialAgentConfig(config, {
+			availableTools: [readFiles],
+		});
+
+		expect(partial.modelId).toBe("claude-sonnet-4-6");
+		expect(partial.systemPrompt).toBe("Be precise.");
+		expect(partial.tools).toEqual([readFiles]);
+		expect(partial.skills).toEqual(["commit", "review"]);
+	});
+
+	it("throws when tool overrides are configured without available tools", () => {
+		expect(() =>
+			parsePartialAgentConfigFromYaml(`---
+name: Reader
+description: Reads files
+tools: read_files
+---
+Be precise.`),
+		).toThrow(
+			"Configured tools cannot be converted into AgentConfig.tools without availableTools.",
+		);
+	});
+
+	it("reads agent configs from ~/.cline/data/settings/agents-compatible directory", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-agent-config-loader-"));
+		const agentsDir = join(tempRoot, "settings", AGENT_CONFIG_DIRECTORY_NAME);
+		await mkdir(agentsDir, { recursive: true });
+		try {
+			await writeFile(
+				join(agentsDir, "reviewer.yaml"),
+				`---
+name: Reviewer
+description: Reviews patches
+tools: read_files
+---
+Review code for regressions.`,
+			);
+			await writeFile(
+				join(agentsDir, "invalid.yaml"),
+				`---
+name:
+---
+`,
+			);
+
+			const loaded = await readAgentConfigsFromDisk(agentsDir);
+			expect([...loaded.keys()]).toEqual(["reviewer"]);
+			expect(loaded.get("reviewer")?.systemPrompt).toBe(
+				"Review code for regressions.",
+			);
+		} finally {
+			await rm(tempRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("reads from both documents and settings directories", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-agent-config-loader-"));
+		const documentsDir = join(tempRoot, "Documents", "Cline", "Agents");
+		const settingsDir = join(tempRoot, "settings", AGENT_CONFIG_DIRECTORY_NAME);
+		await mkdir(documentsDir, { recursive: true });
+		await mkdir(settingsDir, { recursive: true });
+		try {
+			await writeFile(
+				join(documentsDir, "legacy.yaml"),
+				`---
+name: LegacyAgent
+description: legacy
+---
+legacy prompt`,
+			);
+			await writeFile(
+				join(settingsDir, "new.yaml"),
+				`---
+name: NewAgent
+description: new
+---
+new prompt`,
+			);
+
+			const loaded = await readAgentConfigsFromDisk([
+				documentsDir,
+				settingsDir,
+			]);
+			expect([...loaded.keys()].sort()).toEqual(["legacyagent", "newagent"]);
+			expect(loaded.get("legacyagent")?.systemPrompt).toBe("legacy prompt");
+			expect(loaded.get("newagent")?.systemPrompt).toBe("new prompt");
+		} finally {
+			await rm(tempRoot, { recursive: true, force: true });
+		}
+	});
+});

package/src/agents/agent-config-loader.ts

@@ -0,0 +1,108 @@
+import {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	resolveAgentConfigSearchPaths as resolveAgentConfigSearchPathsFromShared,
+	resolveAgentsConfigDirPath as resolveAgentsConfigDirPathFromShared,
+	resolveDocumentsAgentConfigDirectoryPath,
+} from "@clinebot/shared/storage";
+import {
+	type AgentYamlConfig,
+	isAgentConfigYamlFile,
+	normalizeAgentConfigName,
+	parseAgentConfigFromYaml,
+} from "./agent-config-parser";
+import {
+	type UnifiedConfigDefinition,
+	UnifiedConfigFileWatcher,
+	type UnifiedConfigWatcherEvent,
+} from "./unified-config-file-watcher";
+
+export type {
+	AgentYamlConfig,
+	BuildAgentConfigOverridesOptions,
+	ParseYamlFrontmatterResult,
+	PartialAgentConfigOverrides,
+} from "./agent-config-parser";
+export {
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	resolveAgentTools,
+	toPartialAgentConfig,
+} from "./agent-config-parser";
+
+export type AgentConfigWatcher = UnifiedConfigFileWatcher<
+	"agent",
+	AgentYamlConfig
+>;
+export type AgentConfigWatcherEvent = UnifiedConfigWatcherEvent<
+	"agent",
+	AgentYamlConfig
+>;
+
+export {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsAgentConfigDirectoryPath,
+};
+
+export function resolveAgentsConfigDirPath(): string {
+	return resolveAgentsConfigDirPathFromShared();
+}
+
+export function resolveAgentConfigSearchPaths(): string[] {
+	// Documents path first, then settings path so settings location takes precedence.
+	return resolveAgentConfigSearchPathsFromShared();
+}
+
+export interface CreateAgentConfigWatcherOptions {
+	directoryPathOrPaths?: string | ReadonlyArray<string>;
+	debounceMs?: number;
+	emitParseErrors?: boolean;
+}
+
+function toDirectoryPaths(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): string[] {
+	if (Array.isArray(directoryPathOrPaths)) {
+		return [...directoryPathOrPaths];
+	}
+	if (typeof directoryPathOrPaths === "string") {
+		return [directoryPathOrPaths];
+	}
+	return resolveAgentConfigSearchPaths();
+}
+
+export function createAgentConfigDefinition(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): UnifiedConfigDefinition<"agent", AgentYamlConfig> {
+	return {
+		type: "agent",
+		directories: toDirectoryPaths(directoryPathOrPaths),
+		includeFile: (fileName) => isAgentConfigYamlFile(fileName),
+		parseFile: (context) => parseAgentConfigFromYaml(context.content),
+		resolveId: (config) => normalizeAgentConfigName(config.name),
+	};
+}
+
+export function createAgentConfigWatcher(
+	options?: CreateAgentConfigWatcherOptions,
+): AgentConfigWatcher {
+	return new UnifiedConfigFileWatcher(
+		[createAgentConfigDefinition(options?.directoryPathOrPaths)],
+		{
+			debounceMs: options?.debounceMs,
+			emitParseErrors: options?.emitParseErrors,
+		},
+	);
+}
+
+export async function readAgentConfigsFromDisk(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): Promise<Map<string, AgentYamlConfig>> {
+	const watcher = new UnifiedConfigFileWatcher([
+		createAgentConfigDefinition(directoryPathOrPaths),
+	]);
+	await watcher.refreshAll();
+	const snapshot = watcher.getSnapshot("agent");
+	return new Map(
+		[...snapshot.entries()].map(([id, record]) => [id, record.item]),
+	);
+}

package/src/agents/agent-config-parser.ts

@@ -0,0 +1,198 @@
+import type { AgentConfig, Tool } from "@clinebot/agents";
+import YAML from "yaml";
+import { z } from "zod";
+import { ALL_DEFAULT_TOOL_NAMES, type DefaultToolName } from "../tools";
+
+const AgentConfigFrontmatterSchema = z.object({
+	name: z.string().trim().min(1),
+	description: z.string().trim().min(1),
+	modelId: z.string().trim().min(1).optional(),
+	tools: z.union([z.string(), z.array(z.string())]).optional(),
+	skills: z.union([z.string(), z.array(z.string())]).optional(),
+});
+
+const allowedToolNames = new Set<string>(ALL_DEFAULT_TOOL_NAMES);
+
+export interface AgentYamlConfig {
+	name: string;
+	description: string;
+	modelId?: string;
+	tools: DefaultToolName[];
+	skills?: string[];
+	systemPrompt: string;
+}
+
+export interface ParseYamlFrontmatterResult {
+	data: Record<string, unknown>;
+	body: string;
+	hadFrontmatter: boolean;
+	parseError?: string;
+}
+
+export interface BuildAgentConfigOverridesOptions {
+	availableTools?: ReadonlyArray<Tool>;
+}
+
+export interface PartialAgentConfigOverrides
+	extends Partial<Pick<AgentConfig, "modelId" | "systemPrompt" | "tools">> {
+	skills?: string[];
+}
+
+export function isAgentConfigYamlFile(fileName: string): boolean {
+	return /\.(yaml|yml)$/i.test(fileName);
+}
+
+export function normalizeAgentConfigName(name: string): string {
+	return name.trim().toLowerCase();
+}
+
+function parseYamlFrontmatter(markdown: string): ParseYamlFrontmatterResult {
+	const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+	const match = markdown.match(frontmatterRegex);
+	if (!match) {
+		return { data: {}, body: markdown, hadFrontmatter: false };
+	}
+
+	const [, yamlContent, body] = match;
+	try {
+		const parsed = YAML.parse(yamlContent);
+		const data =
+			parsed && typeof parsed === "object" && !Array.isArray(parsed)
+				? (parsed as Record<string, unknown>)
+				: {};
+		return { data, body, hadFrontmatter: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			data: {},
+			body: markdown,
+			hadFrontmatter: true,
+			parseError: message,
+		};
+	}
+}
+
+function normalizeToolName(toolName: string): DefaultToolName {
+	const trimmed = toolName.trim();
+	if (!trimmed) {
+		throw new Error("Tool name cannot be empty.");
+	}
+	if (!allowedToolNames.has(trimmed)) {
+		throw new Error(
+			`Unknown tool '${trimmed}'. Expected one of: ${ALL_DEFAULT_TOOL_NAMES.join(", ")}.`,
+		);
+	}
+	return trimmed as DefaultToolName;
+}
+
+function parseToolNames(
+	tools: string | string[] | undefined,
+): DefaultToolName[] {
+	if (!tools) {
+		return [];
+	}
+	const rawTools = Array.isArray(tools) ? tools : tools.split(",");
+	return Array.from(new Set(rawTools.map(normalizeToolName)));
+}
+
+function normalizeSkillName(skillName: string): string {
+	const trimmed = skillName.trim();
+	if (!trimmed) {
+		throw new Error("Skill name cannot be empty.");
+	}
+	return trimmed;
+}
+
+function parseSkills(
+	skills: string | string[] | undefined,
+): string[] | undefined {
+	if (skills === undefined) {
+		return undefined;
+	}
+	const rawSkills = Array.isArray(skills) ? skills : skills.split(",");
+	return Array.from(new Set(rawSkills.map(normalizeSkillName)));
+}
+
+export function parseAgentConfigFromYaml(content: string): AgentYamlConfig {
+	const { data, body, hadFrontmatter, parseError } =
+		parseYamlFrontmatter(content);
+	if (parseError) {
+		throw new Error(`Failed to parse YAML frontmatter: ${parseError}`);
+	}
+	if (!hadFrontmatter) {
+		throw new Error("Missing YAML frontmatter block in agent config file.");
+	}
+
+	const parsedFrontmatter = AgentConfigFrontmatterSchema.parse(data);
+	const systemPrompt = body.trim();
+	if (!systemPrompt) {
+		throw new Error("Missing system prompt body in agent config file.");
+	}
+
+	return {
+		name: parsedFrontmatter.name,
+		description: parsedFrontmatter.description,
+		modelId: parsedFrontmatter.modelId,
+		tools: parseToolNames(parsedFrontmatter.tools),
+		skills: parseSkills(parsedFrontmatter.skills),
+		systemPrompt,
+	};
+}
+
+export function resolveAgentTools(
+	toolNames: ReadonlyArray<DefaultToolName>,
+	availableTools: ReadonlyArray<Tool>,
+): Tool[] {
+	if (toolNames.length === 0) {
+		return [];
+	}
+
+	const toolIndex = new Map<string, Tool>(
+		availableTools.map((tool) => [tool.name, tool]),
+	);
+	return toolNames.map((toolName) => {
+		const resolved = toolIndex.get(toolName);
+		if (!resolved) {
+			throw new Error(
+				`Configured tool '${toolName}' is unavailable. Available tools: ${availableTools.map((tool) => tool.name).join(", ")}.`,
+			);
+		}
+		return resolved;
+	});
+}
+
+export function toPartialAgentConfig(
+	config: AgentYamlConfig,
+	options?: BuildAgentConfigOverridesOptions,
+): PartialAgentConfigOverrides {
+	const partial: PartialAgentConfigOverrides = {
+		systemPrompt: config.systemPrompt,
+	};
+
+	if (config.modelId) {
+		partial.modelId = config.modelId;
+	}
+
+	if (config.tools.length > 0) {
+		if (!options?.availableTools) {
+			throw new Error(
+				"Configured tools cannot be converted into AgentConfig.tools without availableTools.",
+			);
+		}
+		partial.tools = resolveAgentTools(config.tools, options.availableTools);
+	}
+
+	if (config.skills !== undefined) {
+		partial.skills = [...config.skills];
+	}
+
+	return partial;
+}
+
+export function parsePartialAgentConfigFromYaml(
+	content: string,
+	options?: BuildAgentConfigOverridesOptions,
+): PartialAgentConfigOverrides {
+	const parsed = parseAgentConfigFromYaml(content);
+	return toPartialAgentConfig(parsed, options);
+}

package/src/agents/hooks-config-loader.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	HookConfigFileName,
+	toHookConfigFileName,
+} from "./hooks-config-loader";
+
+describe("hooks config loader", () => {
+	afterEach(() => {
+		delete process.env.CLINE_DATA_DIR;
+	});
+
+	it("recognizes PowerShell hook files", () => {
+		expect(toHookConfigFileName("PreToolUse.ps1")).toBe(
+			HookConfigFileName.PreToolUse,
+		);
+		expect(toHookConfigFileName("TaskError.ps1")).toBe(
+			HookConfigFileName.TaskError,
+		);
+	});
+});

package/src/agents/hooks-config-loader.ts

@@ -0,0 +1,118 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import type { HookEventName } from "@clinebot/agents";
+import {
+	HOOKS_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsHooksDirectoryPath,
+	resolveHooksConfigSearchPaths as resolveHooksConfigSearchPathsFromShared,
+} from "@clinebot/shared/storage";
+
+export { HOOKS_CONFIG_DIRECTORY_NAME, resolveDocumentsHooksDirectoryPath };
+
+export function resolveHooksConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolveHooksConfigSearchPathsFromShared(workspacePath);
+}
+
+export enum HookConfigFileName {
+	TaskStart = "TaskStart",
+	TaskResume = "TaskResume",
+	TaskCancel = "TaskCancel",
+	TaskComplete = "TaskComplete",
+	TaskError = "TaskError",
+	PreToolUse = "PreToolUse",
+	PostToolUse = "PostToolUse",
+	UserPromptSubmit = "UserPromptSubmit",
+	PreCompact = "PreCompact",
+	SessionShutdown = "SessionShutdown",
+}
+
+export const HOOK_CONFIG_FILE_EVENT_MAP: Readonly<
+	Record<HookConfigFileName, HookEventName | undefined>
+> = {
+	[HookConfigFileName.TaskStart]: "agent_start",
+	[HookConfigFileName.TaskResume]: "agent_resume",
+	[HookConfigFileName.TaskCancel]: "agent_abort",
+	[HookConfigFileName.TaskComplete]: "agent_end",
+	[HookConfigFileName.TaskError]: "agent_error",
+	[HookConfigFileName.PreToolUse]: "tool_call",
+	[HookConfigFileName.PostToolUse]: "tool_result",
+	[HookConfigFileName.UserPromptSubmit]: "prompt_submit",
+	[HookConfigFileName.PreCompact]: undefined,
+	[HookConfigFileName.SessionShutdown]: "session_shutdown",
+};
+
+const HOOK_CONFIG_FILE_LOOKUP = new Map<string, HookConfigFileName>(
+	Object.values(HookConfigFileName).map((name) => [name.toLowerCase(), name]),
+);
+
+const SUPPORTED_HOOK_FILE_EXTENSIONS = new Set([
+	"",
+	".sh",
+	".bash",
+	".zsh",
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+	".py",
+	".ps1",
+]);
+
+export function toHookConfigFileName(
+	fileName: string,
+): HookConfigFileName | undefined {
+	const extension = extname(fileName).toLowerCase();
+	if (!SUPPORTED_HOOK_FILE_EXTENSIONS.has(extension)) {
+		return undefined;
+	}
+	const key = basename(fileName, extension).trim().toLowerCase();
+	return HOOK_CONFIG_FILE_LOOKUP.get(key);
+}
+
+export interface HookConfigFileEntry {
+	fileName: HookConfigFileName;
+	hookEventName?: HookEventName;
+	path: string;
+}
+
+export function listHookConfigFiles(
+	workspacePath?: string,
+): HookConfigFileEntry[] {
+	const entries: HookConfigFileEntry[] = [];
+	const seen = new Set<string>();
+	const directories = resolveHooksConfigSearchPaths(workspacePath).filter(
+		(directory) => existsSync(directory),
+	);
+
+	for (const directory of directories) {
+		try {
+			for (const entry of readdirSync(directory, { withFileTypes: true })) {
+				if (!entry.isFile()) {
+					continue;
+				}
+				const fileName = toHookConfigFileName(entry.name);
+				if (!fileName) {
+					continue;
+				}
+				const path = join(directory, entry.name);
+				if (seen.has(path)) {
+					continue;
+				}
+				seen.add(path);
+				entries.push({
+					fileName,
+					hookEventName: HOOK_CONFIG_FILE_EVENT_MAP[fileName],
+					path,
+				});
+			}
+		} catch {
+			// Best-effort listing across config roots.
+		}
+	}
+
+	return entries.sort((a, b) => a.path.localeCompare(b.path));
+}