@clinebot/core 0.0.0

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

@@ -0,0 +1,102 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+	loadAgentPluginFromPath,
+	loadAgentPluginsFromPaths,
+} from "./plugin-loader";
+
+describe("plugin-loader", () => {
+	it("loads default-exported plugin from path", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const pluginPath = join(dir, "plugin-default.mjs");
+			await writeFile(
+				pluginPath,
+				[
+					"export default {",
+					"  name: 'from-default',",
+					"  manifest: { capabilities: ['hooks'], hookStages: ['input'] },",
+					"  onInput: ({ input }) => ({ overrideInput: input })",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const plugin = await loadAgentPluginFromPath(pluginPath);
+			expect(plugin.name).toBe("from-default");
+			expect(plugin.manifest.capabilities).toContain("hooks");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("loads named plugin export from path", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const pluginPath = join(dir, "plugin-named.mjs");
+			await writeFile(
+				pluginPath,
+				[
+					"export const plugin = {",
+					"  name: 'from-named',",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const plugin = await loadAgentPluginFromPath(pluginPath, {
+				exportName: "plugin",
+			});
+			expect(plugin.name).toBe("from-named");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("loads multiple plugins from file paths", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const firstPath = join(dir, "plugin-a.mjs");
+			const secondPath = join(dir, "plugin-b.mjs");
+			await writeFile(
+				firstPath,
+				"export default { name: 'plugin-a', manifest: { capabilities: ['tools'] } };",
+				"utf8",
+			);
+			await writeFile(
+				secondPath,
+				"export default { name: 'plugin-b', manifest: { capabilities: ['commands'] } };",
+				"utf8",
+			);
+
+			const plugins = await loadAgentPluginsFromPaths([firstPath, secondPath]);
+			expect(plugins.map((plugin) => plugin.name)).toEqual([
+				"plugin-a",
+				"plugin-b",
+			]);
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects invalid plugin export missing manifest", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const pluginPath = join(dir, "invalid-plugin.mjs");
+			await writeFile(
+				pluginPath,
+				"export default { name: 'invalid-plugin' };",
+				"utf8",
+			);
+
+			await expect(loadAgentPluginFromPath(pluginPath)).rejects.toThrow(
+				/missing required "manifest"/i,
+			);
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+});

package/src/agents/plugin-loader.ts

@@ -0,0 +1,105 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { AgentConfig } from "@clinebot/agents";
+
+type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
+type PluginLike = {
+	name: string;
+	manifest: {
+		capabilities: string[];
+		hookStages?: string[];
+	};
+};
+
+export interface LoadAgentPluginFromPathOptions {
+	exportName?: string;
+	cwd?: string;
+}
+
+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);
+}
+
+export async function loadAgentPluginFromPath(
+	pluginPath: string,
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<AgentPlugin> {
+	const absolutePath = resolve(options.cwd ?? process.cwd(), pluginPath);
+	const moduleExports = (await import(
+		pathToFileURL(absolutePath).href
+	)) as Record<string, unknown>;
+	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;
+}

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

@@ -0,0 +1,120 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentConfig, Tool, ToolContext } from "@clinebot/agents";
+import { describe, expect, it } from "vitest";
+import { loadSandboxedPlugins } from "./plugin-sandbox";
+
+function createApiCapture() {
+	const tools: Tool[] = [];
+	const api = {
+		registerTool: (tool: Tool) => tools.push(tool),
+		registerCommand: () => {},
+		registerShortcut: () => {},
+		registerFlag: () => {},
+		registerMessageRenderer: () => {},
+		registerProvider: () => {},
+	};
+	return { tools, api };
+}
+
+describe("plugin-sandbox", () => {
+	it("runs plugin hooks and tool contributions in sandbox process", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-"));
+		try {
+			const pluginPath = join(dir, "plugin.mjs");
+			await writeFile(
+				pluginPath,
+				[
+					"export default {",
+					"  name: 'sandbox-test',",
+					"  manifest: { capabilities: ['hooks','tools'], hookStages: ['input'] },",
+					"  setup(api) {",
+					"    api.registerTool({",
+					"      name: 'sandbox_echo',",
+					"      description: 'echo',",
+					"      inputSchema: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'] },",
+					"      execute: async (input) => ({ echoed: input.value }),",
+					"    });",
+					"  },",
+					"  onInput(ctx) { return { overrideInput: String(ctx.input || '').toUpperCase() }; }",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+			});
+			try {
+				expect(sandboxed.extensions).toBeDefined();
+				const extension = sandboxed.extensions?.[0];
+				expect(extension?.name).toBe("sandbox-test");
+				type AgentExtensionInputContext = Parameters<
+					NonNullable<NonNullable<AgentConfig["extensions"]>[number]["onInput"]>
+				>[0];
+				const inputContext: AgentExtensionInputContext = {
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					parentAgentId: null,
+					mode: "run",
+					input: "hello",
+				};
+				const control = await extension?.onInput?.(inputContext);
+				expect(control?.overrideInput).toBe("HELLO");
+
+				const { tools, api } = createApiCapture();
+				await extension?.setup?.(api);
+				expect(tools.map((tool) => tool.name)).toContain("sandbox_echo");
+				const echoTool = tools.find((tool) => tool.name === "sandbox_echo");
+				expect(echoTool).toBeDefined();
+				const result = await echoTool?.execute({ value: "ok" }, {
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					iteration: 1,
+				} as ToolContext);
+				expect(result).toEqual({ echoed: "ok" });
+			} finally {
+				await sandboxed.shutdown();
+			}
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("enforces hook timeout and cancels sandbox process", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-timeout-"));
+		try {
+			const pluginPath = join(dir, "plugin-timeout.mjs");
+			await writeFile(
+				pluginPath,
+				[
+					"export default {",
+					"  name: 'sandbox-timeout',",
+					"  manifest: { capabilities: ['hooks'], hookStages: ['input'] },",
+					"  onInput() { return new Promise(() => {}); }",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+				hookTimeoutMs: 50,
+			});
+			const extension = sandboxed.extensions?.[0];
+			await expect(
+				extension?.onInput?.({
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					parentAgentId: null,
+					mode: "run",
+					input: "hello",
+				}),
+			).rejects.toThrow(/timed out/i);
+			await sandboxed.shutdown();
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+});