@clinebot/core 0.0.21 → 0.0.23

package/src/agents/index.ts

@@ -0,0 +1,85 @@
+export type {
+	AgentConfigWatcher,
+	AgentConfigWatcherEvent,
+	AgentYamlConfig,
+	BuildAgentConfigOverridesOptions,
+	CreateAgentConfigWatcherOptions,
+	ParseYamlFrontmatterResult,
+	PartialAgentConfigOverrides,
+} from "./agent-config-loader";
+export {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	createAgentConfigDefinition,
+	createAgentConfigWatcher,
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	readAgentConfigsFromDisk,
+	resolveAgentConfigSearchPaths,
+	resolveAgentsConfigDirPath,
+	resolveAgentTools,
+	resolveDocumentsAgentConfigDirectoryPath,
+	toPartialAgentConfig,
+} from "./agent-config-loader";
+export {
+	HOOK_CONFIG_FILE_EVENT_MAP,
+	HOOKS_CONFIG_DIRECTORY_NAME,
+	type HookConfigFileEntry,
+	HookConfigFileName,
+	listHookConfigFiles,
+	resolveDocumentsHooksDirectoryPath,
+	resolveHooksConfigSearchPaths,
+	toHookConfigFileName,
+} from "./hooks-config-loader";
+export type { ResolveAgentPluginPathsOptions } from "./plugin-config-loader";
+export {
+	discoverPluginModulePaths,
+	resolveAgentPluginPaths,
+	resolveAndLoadAgentPlugins,
+	resolvePluginConfigSearchPaths,
+} from "./plugin-config-loader";
+export type { LoadAgentPluginFromPathOptions } from "./plugin-loader";
+export {
+	loadAgentPluginFromPath,
+	loadAgentPluginsFromPaths,
+} from "./plugin-loader";
+export type {
+	UnifiedConfigDefinition,
+	UnifiedConfigFileCandidate,
+	UnifiedConfigFileContext,
+	UnifiedConfigRecord,
+	UnifiedConfigWatcherEvent,
+	UnifiedConfigWatcherOptions,
+} from "./unified-config-file-watcher";
+export { UnifiedConfigFileWatcher } from "./unified-config-file-watcher";
+export type {
+	CreateInstructionWatcherOptions,
+	CreateRulesConfigDefinitionOptions,
+	CreateSkillsConfigDefinitionOptions,
+	CreateUserInstructionConfigWatcherOptions,
+	CreateWorkflowsConfigDefinitionOptions,
+	ParseMarkdownFrontmatterResult,
+	RuleConfig,
+	SkillConfig,
+	UserInstructionConfig,
+	UserInstructionConfigType,
+	UserInstructionConfigWatcher,
+	UserInstructionConfigWatcherEvent,
+	WorkflowConfig,
+} from "./user-instruction-config-loader";
+export {
+	createRulesConfigDefinition,
+	createSkillsConfigDefinition,
+	createUserInstructionConfigWatcher,
+	createWorkflowsConfigDefinition,
+	parseRuleConfigFromMarkdown,
+	parseSkillConfigFromMarkdown,
+	parseWorkflowConfigFromMarkdown,
+	RULES_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsRulesDirectoryPath,
+	resolveDocumentsWorkflowsDirectoryPath,
+	resolveRulesConfigSearchPaths,
+	resolveSkillsConfigSearchPaths,
+	resolveWorkflowsConfigSearchPaths,
+	SKILLS_CONFIG_DIRECTORY_NAME,
+	WORKFLOWS_CONFIG_DIRECTORY_NAME,
+} from "./user-instruction-config-loader";

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

@@ -0,0 +1,140 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setHomeDir } from "@clinebot/shared/storage";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	discoverPluginModulePaths,
+	resolveAgentPluginPaths,
+	resolvePluginConfigSearchPaths,
+} from "./plugin-config-loader";
+
+describe("plugin-config-loader", () => {
+	const envSnapshot = {
+		HOME: process.env.HOME,
+	};
+
+	afterEach(() => {
+		process.env.HOME = envSnapshot.HOME;
+		setHomeDir(envSnapshot.HOME ?? "~");
+	});
+
+	it("discovers plugin modules recursively", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			const nested = join(root, "nested");
+			await mkdir(nested, { recursive: true });
+			await writeFile(join(root, "a.mjs"), "export default {}", "utf8");
+			await writeFile(join(nested, "b.ts"), "export default {}", "utf8");
+			await writeFile(
+				join(root, ".a.mjs.cline-plugin.mjs"),
+				"export default {}",
+				"utf8",
+			);
+			await writeFile(join(root, "ignore.txt"), "noop", "utf8");
+
+			const discovered = discoverPluginModulePaths(root);
+			expect(discovered).toEqual([join(root, "a.mjs"), join(nested, "b.ts")]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("resolves plugin paths from explicit files/directories", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			process.env.HOME = root;
+			setHomeDir(root);
+			const pluginsDir = join(root, "plugins");
+			await mkdir(pluginsDir, { recursive: true });
+			const filePath = join(root, "direct.mjs");
+			const dirPluginPath = join(pluginsDir, "dir-plugin.mjs");
+			await writeFile(filePath, "export default {}", "utf8");
+			await writeFile(dirPluginPath, "export default {}", "utf8");
+
+			const resolved = resolveAgentPluginPaths({
+				pluginPaths: ["./direct.mjs", "./plugins"],
+				workspacePath: join(root, "workspace"),
+				cwd: root,
+			});
+
+			expect(resolved).toEqual([filePath, dirPluginPath]);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("prefers package manifest plugin entries for configured directories", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			const pluginDir = join(root, "plugin-package");
+			const srcDir = join(pluginDir, "src");
+			await mkdir(srcDir, { recursive: true });
+			const declaredEntry = join(srcDir, "index.ts");
+			const ignoredEntry = join(pluginDir, "ignored.mjs");
+			await writeFile(
+				join(pluginDir, "package.json"),
+				JSON.stringify({
+					name: "plugin-package",
+					private: true,
+					cline: {
+						plugins: ["./src/index.ts"],
+					},
+				}),
+				"utf8",
+			);
+			await writeFile(declaredEntry, "export default {}", "utf8");
+			await writeFile(ignoredEntry, "export default {}", "utf8");
+
+			const resolved = resolveAgentPluginPaths({
+				pluginPaths: ["./plugin-package"],
+				cwd: root,
+				workspacePath: join(root, "workspace"),
+			});
+
+			expect(resolved).toContain(declaredEntry);
+			expect(resolved).not.toContain(ignoredEntry);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	it("includes shared search-path plugins", async () => {
+		const home = await mkdtemp(
+			join(tmpdir(), "core-plugin-config-loader-home-"),
+		);
+		const workspace = await mkdtemp(
+			join(tmpdir(), "core-plugin-config-loader-workspace-"),
+		);
+		try {
+			process.env.HOME = home;
+			setHomeDir(home);
+			const workspacePlugins = join(workspace, ".clinerules", "plugins");
+			const userPlugins = join(home, ".cline", "plugins");
+			const documentsPlugins = join(home, "Documents", "Plugins");
+			await mkdir(workspacePlugins, { recursive: true });
+			await mkdir(userPlugins, { recursive: true });
+			await mkdir(documentsPlugins, { recursive: true });
+			const workspacePlugin = join(workspacePlugins, "workspace.mjs");
+			const userPlugin = join(userPlugins, "user.mjs");
+			const documentsPlugin = join(documentsPlugins, "documents.mjs");
+			await writeFile(workspacePlugin, "export default {}", "utf8");
+			await writeFile(userPlugin, "export default {}", "utf8");
+			await writeFile(documentsPlugin, "export default {}", "utf8");
+
+			const searchPaths = resolvePluginConfigSearchPaths(workspace);
+			expect(searchPaths).toHaveLength(3);
+			expect(searchPaths).toContain(workspacePlugins);
+			expect(searchPaths).toContain(userPlugins);
+			expect(searchPaths).toContain(documentsPlugins);
+
+			const resolved = resolveAgentPluginPaths({ workspacePath: workspace });
+			expect(resolved).toContain(workspacePlugin);
+			expect(resolved).toContain(userPlugin);
+			expect(resolved).toContain(documentsPlugin);
+		} finally {
+			await rm(home, { recursive: true, force: true });
+			await rm(workspace, { recursive: true, force: true });
+		}
+	});
+});

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

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import type { AgentConfig } from "@clinebot/agents";
+import {
+	discoverPluginModulePaths as discoverPluginModulePathsFromShared,
+	resolveConfiguredPluginModulePaths,
+	resolvePluginConfigSearchPaths as resolvePluginConfigSearchPathsFromShared,
+} from "@clinebot/shared/storage";
+import { loadAgentPluginsFromPaths } from "./plugin-loader";
+import { loadSandboxedPlugins } from "./plugin-sandbox";
+
+type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
+
+export function resolvePluginConfigSearchPaths(
+	workspacePath?: string,
+): string[] {
+	return resolvePluginConfigSearchPathsFromShared(workspacePath);
+}
+
+export function discoverPluginModulePaths(directoryPath: string): string[] {
+	return discoverPluginModulePathsFromShared(directoryPath);
+}
+
+export interface ResolveAgentPluginPathsOptions {
+	pluginPaths?: ReadonlyArray<string>;
+	workspacePath?: string;
+	cwd?: string;
+}
+
+export function resolveAgentPluginPaths(
+	options: ResolveAgentPluginPathsOptions = {},
+): string[] {
+	const cwd = options.cwd ?? process.cwd();
+	const discoveredFromSearchPaths = resolvePluginConfigSearchPaths(
+		options.workspacePath,
+	)
+		.flatMap((directoryPath) => discoverPluginModulePaths(directoryPath))
+		.filter((path) => existsSync(path));
+	const configuredPaths = resolveConfiguredPluginModulePaths(
+		options.pluginPaths ?? [],
+		cwd,
+	);
+
+	const deduped: string[] = [];
+	const seen = new Set<string>();
+	for (const path of [...configuredPaths, ...discoveredFromSearchPaths]) {
+		if (seen.has(path)) {
+			continue;
+		}
+		seen.add(path);
+		deduped.push(path);
+	}
+	return deduped;
+}
+
+export interface ResolveAndLoadAgentPluginsOptions
+	extends ResolveAgentPluginPathsOptions {
+	mode?: "sandbox" | "in_process";
+	exportName?: string;
+	importTimeoutMs?: number;
+	hookTimeoutMs?: number;
+	contributionTimeoutMs?: number;
+	onEvent?: (event: { name: string; payload?: unknown }) => void;
+}
+
+export async function resolveAndLoadAgentPlugins(
+	options: ResolveAndLoadAgentPluginsOptions = {},
+): Promise<{
+	extensions: AgentPlugin[];
+	shutdown?: () => Promise<void>;
+}> {
+	const paths = resolveAgentPluginPaths(options);
+	if (paths.length === 0) {
+		return { extensions: [] };
+	}
+
+	if (options.mode === "in_process") {
+		return {
+			extensions: await loadAgentPluginsFromPaths(paths, {
+				cwd: options.cwd,
+				exportName: options.exportName,
+			}),
+		};
+	}
+
+	const sandboxed = await loadSandboxedPlugins({
+		pluginPaths: paths,
+		exportName: options.exportName,
+		importTimeoutMs: options.importTimeoutMs,
+		hookTimeoutMs: options.hookTimeoutMs,
+		contributionTimeoutMs: options.contributionTimeoutMs,
+		onEvent: options.onEvent,
+	});
+	return {
+		extensions: sandboxed.extensions ?? [],
+		shutdown: sandboxed.shutdown,
+	};
+}

package/src/agents/plugin-loader.test.ts

@@ -0,0 +1,210 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+	loadAgentPluginFromPath,
+	loadAgentPluginsFromPaths,
+} from "./plugin-loader";
+
+describe("plugin-loader", () => {
+	let dir = "";
+	let copyDir = "";
+
+	beforeAll(async () => {
+		dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		copyDir = await mkdtemp(join(tmpdir(), "core-plugin-loader-copy-"));
+
+		await writeFile(
+			join(dir, "plugin-default.mjs"),
+			[
+				"export default {",
+				"  name: 'from-default',",
+				"  manifest: { capabilities: ['hooks'], hookStages: ['input'] },",
+				"  onInput: ({ input }) => ({ overrideInput: input })",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-named.mjs"),
+			[
+				"export const plugin = {",
+				"  name: 'from-named',",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-a.mjs"),
+			"export default { name: 'plugin-a', manifest: { capabilities: ['tools'] } };",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-b.mjs"),
+			"export default { name: 'plugin-b', manifest: { capabilities: ['commands'] } };",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-ts.ts"),
+			[
+				"const name: string = 'plugin-ts';",
+				"export default {",
+				"  name,",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		const depDir = join(dir, "node_modules", "plugin-local-dep");
+		await mkdir(depDir, { recursive: true });
+		await writeFile(
+			join(depDir, "package.json"),
+			JSON.stringify({
+				name: "plugin-local-dep",
+				type: "module",
+				exports: "./index.js",
+			}),
+			"utf8",
+		);
+		await writeFile(
+			join(depDir, "index.js"),
+			"export const depName = 'plugin-local-dep';\n",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-with-dep.ts"),
+			[
+				"import { depName } from 'plugin-local-dep';",
+				"export default {",
+				"  name: depName,",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		const sdkDir = join(dir, "node_modules", "@clinebot", "shared");
+		await mkdir(sdkDir, { recursive: true });
+		await writeFile(
+			join(sdkDir, "package.json"),
+			JSON.stringify({
+				name: "@clinebot/shared",
+				type: "module",
+				exports: "./index.js",
+			}),
+			"utf8",
+		);
+		await writeFile(
+			join(sdkDir, "index.js"),
+			"export const sdkMarker = 'plugin-installed-sdk';\n",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-with-sdk-dep.ts"),
+			[
+				"import { sdkMarker } from '@clinebot/shared';",
+				"export default {",
+				"  name: sdkMarker,",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		await writeFile(
+			join(copyDir, "portable-subagents.ts"),
+			[
+				"import { resolveClineDataDir } from '@clinebot/shared/storage';",
+				"import YAML from 'yaml';",
+				"export default {",
+				"  name: typeof resolveClineDataDir === 'function' ? YAML.stringify({ ok: true }) : 'invalid',",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		await writeFile(
+			join(dir, "invalid-plugin.mjs"),
+			"export default { name: 'invalid-plugin' };",
+			"utf8",
+		);
+	});
+
+	afterAll(async () => {
+		if (dir) {
+			await rm(dir, { recursive: true, force: true });
+		}
+		if (copyDir) {
+			await rm(copyDir, { recursive: true, force: true });
+		}
+	});
+
+	it("loads default-exported plugin from path", async () => {
+		const plugin = await loadAgentPluginFromPath(
+			join(dir, "plugin-default.mjs"),
+		);
+		expect(plugin.name).toBe("from-default");
+		expect(plugin.manifest.capabilities).toContain("hooks");
+	});
+
+	it("loads named plugin export from path", async () => {
+		const plugin = await loadAgentPluginFromPath(
+			join(dir, "plugin-named.mjs"),
+			{
+				exportName: "plugin",
+			},
+		);
+		expect(plugin.name).toBe("from-named");
+	});
+
+	it("loads multiple plugins from file paths", async () => {
+		const plugins = await loadAgentPluginsFromPaths([
+			join(dir, "plugin-a.mjs"),
+			join(dir, "plugin-b.mjs"),
+		]);
+		expect(plugins.map((plugin) => plugin.name)).toEqual([
+			"plugin-a",
+			"plugin-b",
+		]);
+	});
+
+	it("loads TypeScript plugins from file paths", async () => {
+		const plugin = await loadAgentPluginFromPath(join(dir, "plugin-ts.ts"));
+		expect(plugin.name).toBe("plugin-ts");
+	});
+
+	it("resolves plugin-local dependencies from the plugin path", async () => {
+		const plugin = await loadAgentPluginFromPath(
+			join(dir, "plugin-with-dep.ts"),
+			{ cwd: dir },
+		);
+		expect(plugin.name).toBe("plugin-local-dep");
+	});
+
+	it("prefers plugin-installed SDK packages over workspace aliases", async () => {
+		const plugin = await loadAgentPluginFromPath(
+			join(dir, "plugin-with-sdk-dep.ts"),
+			{ cwd: dir },
+		);
+		expect(plugin.name).toBe("plugin-installed-sdk");
+	});
+
+	it("requires copied plugins to provide their own non-SDK dependencies", async () => {
+		await expect(
+			loadAgentPluginFromPath(join(copyDir, "portable-subagents.ts"), {
+				cwd: copyDir,
+				useCache: true,
+			}),
+		).rejects.toThrow(/Cannot find (package|module) 'yaml'/i);
+	});
+
+	it("rejects invalid plugin export missing manifest", async () => {
+		await expect(
+			loadAgentPluginFromPath(join(dir, "invalid-plugin.mjs")),
+		).rejects.toThrow(/missing required "manifest"/i);
+	});
+});

package/src/agents/plugin-loader.ts

@@ -0,0 +1,175 @@
+import { existsSync } from "node:fs";
+import { builtinModules, createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig } from "@clinebot/agents";
+import createJiti from "jiti";
+
+type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
+type PluginLike = {
+	name: string;
+	manifest: {
+		capabilities: string[];
+		hookStages?: string[];
+	};
+};
+
+export interface LoadAgentPluginFromPathOptions {
+	exportName?: string;
+	cwd?: string;
+	useCache?: boolean;
+}
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_ALIASES = collectWorkspaceAliases(MODULE_DIR);
+const BUILTIN_MODULES = new Set(
+	builtinModules.flatMap((id) => [id, id.replace(/^node:/, "")]),
+);
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function hasValidStringArray(value: unknown): value is string[] {
+	return (
+		Array.isArray(value) && value.every((entry) => typeof entry === "string")
+	);
+}
+
+function validatePluginManifest(
+	plugin: PluginLike,
+	absolutePath: string,
+): void {
+	if (!isObject(plugin.manifest)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: missing required "manifest"`,
+		);
+	}
+	if (!hasValidStringArray(plugin.manifest.capabilities)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.capabilities must be a string array`,
+		);
+	}
+	if (plugin.manifest.capabilities.length === 0) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.capabilities cannot be empty`,
+		);
+	}
+	if (
+		Object.hasOwn(plugin.manifest, "hookStages") &&
+		!hasValidStringArray(plugin.manifest.hookStages)
+	) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: manifest.hookStages must be a string array when provided`,
+		);
+	}
+}
+
+function validatePluginExport(
+	plugin: unknown,
+	absolutePath: string,
+): asserts plugin is PluginLike {
+	if (!isObject(plugin)) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: expected object export`,
+		);
+	}
+	if (typeof plugin.name !== "string" || plugin.name.length === 0) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: expected non-empty "name"`,
+		);
+	}
+	if (!Object.hasOwn(plugin, "manifest")) {
+		throw new Error(
+			`Invalid plugin module at ${absolutePath}: missing required "manifest"`,
+		);
+	}
+	validatePluginManifest(plugin as PluginLike, absolutePath);
+}
+
+function collectWorkspaceAliases(startDir: string): Record<string, string> {
+	const root = resolve(startDir, "..", "..", "..", "..");
+	const aliases: Record<string, string> = {};
+	const candidates: Record<string, string> = {
+		"@clinebot/agents": resolve(root, "packages/agents/src/index.ts"),
+		"@clinebot/core": resolve(root, "packages/core/src/index.ts"),
+		"@clinebot/llms": resolve(root, "packages/llms/src/index.ts"),
+		"@clinebot/llms/models": resolve(root, "packages/llms/src/models.ts"),
+		"@clinebot/llms/providers": resolve(root, "packages/llms/src/providers.ts"),
+		"@clinebot/llms/runtime": resolve(root, "packages/llms/src/runtime.ts"),
+		"@clinebot/rpc": resolve(root, "packages/rpc/src/index.ts"),
+		"@clinebot/scheduler": resolve(root, "packages/scheduler/src/index.ts"),
+		"@clinebot/shared": resolve(root, "packages/shared/src/index.ts"),
+		"@clinebot/shared/storage": resolve(
+			root,
+			"packages/shared/src/storage/index.ts",
+		),
+		"@clinebot/shared/db": resolve(root, "packages/shared/src/db/index.ts"),
+	};
+	for (const [key, value] of Object.entries(candidates)) {
+		if (existsSync(value)) {
+			aliases[key] = value;
+		}
+	}
+	return aliases;
+}
+
+function collectPluginImportAliases(
+	pluginPath: string,
+): Record<string, string> {
+	const pluginRequire = createRequire(pluginPath);
+	const aliases: Record<string, string> = {};
+	for (const [specifier, sourcePath] of Object.entries(WORKSPACE_ALIASES)) {
+		try {
+			pluginRequire.resolve(specifier);
+			continue;
+		} catch {
+			// Use the workspace source only when the plugin package does not provide
+			// its own installed SDK dependency.
+		}
+		aliases[specifier] = sourcePath;
+	}
+	return aliases;
+}
+
+async function importPluginModule(
+	absolutePath: string,
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<Record<string, unknown>> {
+	const aliases = collectPluginImportAliases(absolutePath);
+	const jiti = createJiti(absolutePath, {
+		alias: aliases,
+		cache: options.useCache,
+		requireCache: options.useCache,
+		esmResolve: true,
+		interopDefault: false,
+		nativeModules: [...BUILTIN_MODULES],
+		transformModules: Object.keys(aliases),
+	});
+	return (await jiti.import(absolutePath, {})) as Record<string, unknown>;
+}
+
+export async function loadAgentPluginFromPath(
+	pluginPath: string,
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<AgentPlugin> {
+	const absolutePath = resolve(options.cwd ?? process.cwd(), pluginPath);
+	const moduleExports = await importPluginModule(absolutePath, options);
+	const exportName = options.exportName ?? "plugin";
+	const plugin = (moduleExports.default ??
+		moduleExports[exportName]) as unknown;
+
+	validatePluginExport(plugin, absolutePath);
+	return plugin as AgentPlugin;
+}
+
+export async function loadAgentPluginsFromPaths(
+	pluginPaths: string[],
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<AgentPlugin[]> {
+	const loaded: AgentPlugin[] = [];
+	for (const pluginPath of pluginPaths) {
+		loaded.push(await loadAgentPluginFromPath(pluginPath, options));
+	}
+	return loaded;
+}