@clinebot/core 0.0.11 → 0.0.12

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

@@ -1,12 +1,16 @@
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import {
 	loadAgentPluginFromPath,
 	loadAgentPluginsFromPaths,
 } from "./plugin-loader";
 
+const TEST_DIR = fileURLToPath(new URL(".", import.meta.url));
+const REPO_ROOT = resolve(TEST_DIR, "..", "..", "..", "..");
+
 describe("plugin-loader", () => {
 	it("loads default-exported plugin from path", async () => {
 		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
@@ -82,6 +86,128 @@ describe("plugin-loader", () => {
 		}
 	});
 
+	it("loads TypeScript plugins from file paths", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const pluginPath = join(dir, "plugin-ts.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"const name: string = 'plugin-ts';",
+					"export default {",
+					"  name,",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const plugin = await loadAgentPluginFromPath(pluginPath);
+			expect(plugin.name).toBe("plugin-ts");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("resolves plugin-local dependencies from the plugin path", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			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",
+			);
+			const pluginPath = join(dir, "plugin-with-dep.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"import { depName } from 'plugin-local-dep';",
+					"export default {",
+					"  name: depName,",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const plugin = await loadAgentPluginFromPath(pluginPath, { cwd: dir });
+			expect(plugin.name).toBe("plugin-local-dep");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("prefers plugin-installed SDK packages over workspace aliases", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-"));
+		try {
+			const depDir = join(dir, "node_modules", "@clinebot", "shared");
+			await mkdir(depDir, { recursive: true });
+			await writeFile(
+				join(depDir, "package.json"),
+				JSON.stringify({
+					name: "@clinebot/shared",
+					type: "module",
+					exports: "./index.js",
+				}),
+				"utf8",
+			);
+			await writeFile(
+				join(depDir, "index.js"),
+				"export const sdkMarker = 'plugin-installed-sdk';\n",
+				"utf8",
+			);
+			const pluginPath = join(dir, "plugin-with-sdk-dep.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"import { sdkMarker } from '@clinebot/shared';",
+					"export default {",
+					"  name: sdkMarker,",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const plugin = await loadAgentPluginFromPath(pluginPath, { cwd: dir });
+			expect(plugin.name).toBe("plugin-installed-sdk");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("requires copied plugins to provide their own non-SDK dependencies", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-loader-copy-"));
+		try {
+			const pluginPath = join(dir, "portable-subagents.ts");
+			await writeFile(
+				pluginPath,
+				await readFile(
+					resolve(REPO_ROOT, "apps/examples/subagent-plugin/index.ts"),
+					"utf8",
+				),
+				"utf8",
+			);
+
+			await expect(
+				loadAgentPluginFromPath(pluginPath, { cwd: dir }),
+			).rejects.toThrow(/Cannot find (package|module) 'yaml'/i);
+		} 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 {

package/src/agents/plugin-loader.ts

@@ -1,6 +1,9 @@
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+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 = {
@@ -16,6 +19,12 @@ export interface LoadAgentPluginFromPathOptions {
 	cwd?: string;
 }
 
+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;
 }
@@ -77,14 +86,70 @@ function validatePluginExport(
 	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.node.ts"),
+		"@clinebot/llms": resolve(root, "packages/llms/src/index.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,
+): Promise<Record<string, unknown>> {
+	const aliases = collectPluginImportAliases(absolutePath);
+	const jiti = createJiti(absolutePath, {
+		alias: aliases,
+		cache: false,
+		requireCache: false,
+		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 import(
-		pathToFileURL(absolutePath).href
-	)) as Record<string, unknown>;
+	const moduleExports = await importPluginModule(absolutePath);
 	const exportName = options.exportName ?? "plugin";
 	const plugin = (moduleExports.default ??
 		moduleExports[exportName]) as unknown;

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

@@ -0,0 +1,445 @@
+import { existsSync } from "node:fs";
+import { builtinModules, createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+/**
+ * Bootstrap script for the plugin sandbox subprocess.
+ *
+ * This file runs inside an isolated Node.js child process spawned by
+ * {@link SubprocessSandbox}. It receives RPC calls over IPC and dynamically
+ * imports plugin modules, wiring up their contributions (tools, commands,
+ * shortcuts, flags, renderers, providers) and lifecycle hooks.
+ *
+ * Because it executes in a separate process it must be self-contained — no
+ * imports from the rest of the codebase are allowed.
+ */
+
+import { fileURLToPath } from "node:url";
+import createJiti from "jiti";
+
+// ---------------------------------------------------------------------------
+// Types (intentionally minimal – mirrors only what the RPC protocol needs)
+// ---------------------------------------------------------------------------
+
+interface PluginTool {
+	name: string;
+	description?: string;
+	inputSchema?: unknown;
+	timeoutMs?: number;
+	retryable?: boolean;
+	execute: (input: unknown, context: unknown) => Promise<unknown>;
+}
+
+interface PluginCommand {
+	name: string;
+	description?: string;
+	handler?: (input: string) => Promise<string>;
+}
+
+interface PluginShortcut {
+	name: string;
+	value: string;
+	description?: string;
+}
+
+interface PluginFlag {
+	name: string;
+	description?: string;
+	defaultValue?: boolean | string | number;
+}
+
+interface PluginMessageRenderer {
+	name: string;
+	render: (message: unknown) => string;
+}
+
+interface PluginProvider {
+	name: string;
+	description?: string;
+	metadata?: Record<string, unknown>;
+}
+
+interface PluginApi {
+	registerTool(tool: PluginTool): void;
+	registerCommand(command: PluginCommand): void;
+	registerShortcut(shortcut: PluginShortcut): void;
+	registerFlag(flag: PluginFlag): void;
+	registerMessageRenderer(renderer: PluginMessageRenderer): void;
+	registerProvider(provider: PluginProvider): void;
+}
+
+interface PluginModule {
+	name: string;
+	manifest: Record<string, unknown>;
+	setup?: (api: PluginApi) => void | Promise<void>;
+	[hookName: string]: unknown;
+}
+
+interface ContributionDescriptor {
+	id: string;
+	name: string;
+	description?: string;
+	inputSchema?: unknown;
+	timeoutMs?: number;
+	retryable?: boolean;
+	value?: string;
+	defaultValue?: boolean | string | number;
+	metadata?: Record<string, unknown>;
+}
+
+interface PluginDescriptor {
+	pluginId: string;
+	name: string;
+	manifest: Record<string, unknown>;
+	contributions: {
+		tools: ContributionDescriptor[];
+		commands: ContributionDescriptor[];
+		shortcuts: ContributionDescriptor[];
+		flags: ContributionDescriptor[];
+		messageRenderers: ContributionDescriptor[];
+		providers: ContributionDescriptor[];
+	};
+}
+
+interface PluginState {
+	plugin: PluginModule;
+	handlers: {
+		tools: Map<string, PluginTool["execute"]>;
+		commands: Map<string, NonNullable<PluginCommand["handler"]>>;
+		messageRenderers: Map<string, PluginMessageRenderer["render"]>;
+	};
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function assertValidPluginModule(
+	plugin: unknown,
+	pluginPath: string,
+): asserts plugin is PluginModule {
+	if (!isObject(plugin)) {
+		throw new Error(`Invalid plugin module: ${pluginPath}`);
+	}
+	if (typeof plugin.name !== "string" || !plugin.name) {
+		throw new Error(`Invalid plugin name: ${pluginPath}`);
+	}
+	if (!isObject(plugin.manifest)) {
+		throw new Error(`Invalid plugin manifest: ${pluginPath}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+let pluginCounter = 0;
+const pluginState = new Map<string, PluginState>();
+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:/, "")]),
+);
+
+// ---------------------------------------------------------------------------
+// IPC helpers
+// ---------------------------------------------------------------------------
+
+function toErrorPayload(error: unknown): { message: string; stack?: string } {
+	const message = error instanceof Error ? error.message : String(error);
+	const stack = error instanceof Error ? error.stack : undefined;
+	return { message, stack };
+}
+
+function sendResponse(
+	id: string,
+	ok: boolean,
+	result: unknown,
+	error?: { message: string; stack?: string },
+): void {
+	if (!process.send) return;
+	process.send({ type: "response", id, ok, result, error });
+}
+
+function emitEvent(name: string, payload?: unknown): void {
+	if (!process.send) return;
+	process.send({ type: "event", name, payload });
+}
+
+// Expose event emitter to plugins.
+(globalThis as Record<string, unknown>).__clinePluginHost = { emitEvent };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sanitizeObject(value: unknown): Record<string, unknown> {
+	if (!value || typeof value !== "object") return {};
+	return value as Record<string, unknown>;
+}
+
+function makeId(pluginId: string, prefix: string): string {
+	return `${pluginId}_${prefix}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function getPlugin(pluginId: string): PluginState {
+	const state = pluginState.get(pluginId);
+	if (!state) {
+		throw new Error(`Unknown sandbox plugin id: ${pluginId}`);
+	}
+	return state;
+}
+
+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.node.ts"),
+		"@clinebot/llms": resolve(root, "packages/llms/src/index.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(
+	pluginPath: string,
+): Promise<Record<string, unknown>> {
+	const aliases = collectPluginImportAliases(pluginPath);
+	const jiti = createJiti(pluginPath, {
+		alias: aliases,
+		cache: false,
+		requireCache: false,
+		esmResolve: true,
+		interopDefault: false,
+		nativeModules: [...BUILTIN_MODULES],
+		transformModules: Object.keys(aliases),
+	});
+	return (await jiti.import(pluginPath, {})) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// RPC methods
+// ---------------------------------------------------------------------------
+
+async function initialize(args: {
+	pluginPaths?: string[];
+	exportName?: string;
+}): Promise<PluginDescriptor[]> {
+	const descriptors: PluginDescriptor[] = [];
+	const exportName = args.exportName || "plugin";
+
+	for (const pluginPath of args.pluginPaths || []) {
+		const moduleExports = await importPluginModule(pluginPath);
+		const plugin = (moduleExports.default ??
+			moduleExports[exportName]) as unknown;
+		assertValidPluginModule(plugin, pluginPath);
+
+		const pluginId = `plugin_${++pluginCounter}`;
+		const contributions: PluginDescriptor["contributions"] = {
+			tools: [],
+			commands: [],
+			shortcuts: [],
+			flags: [],
+			messageRenderers: [],
+			providers: [],
+		};
+		const handlers: PluginState["handlers"] = {
+			tools: new Map(),
+			commands: new Map(),
+			messageRenderers: new Map(),
+		};
+
+		const api: PluginApi = {
+			registerTool: (tool) => {
+				const id = makeId(pluginId, "tool");
+				handlers.tools.set(id, tool.execute);
+				contributions.tools.push({
+					id,
+					name: tool.name,
+					description: tool.description,
+					inputSchema: tool.inputSchema,
+					timeoutMs: tool.timeoutMs,
+					retryable: tool.retryable,
+				});
+			},
+			registerCommand: (command) => {
+				const id = makeId(pluginId, "command");
+				if (typeof command.handler === "function") {
+					handlers.commands.set(id, command.handler);
+				}
+				contributions.commands.push({
+					id,
+					name: command.name,
+					description: command.description,
+				});
+			},
+			registerShortcut: (shortcut) => {
+				contributions.shortcuts.push({
+					id: makeId(pluginId, "shortcut"),
+					name: shortcut.name,
+					value: shortcut.value,
+					description: shortcut.description,
+				});
+			},
+			registerFlag: (flag) => {
+				contributions.flags.push({
+					id: makeId(pluginId, "flag"),
+					name: flag.name,
+					description: flag.description,
+					defaultValue: flag.defaultValue,
+				});
+			},
+			registerMessageRenderer: (renderer) => {
+				const id = makeId(pluginId, "renderer");
+				handlers.messageRenderers.set(id, renderer.render);
+				contributions.messageRenderers.push({ id, name: renderer.name });
+			},
+			registerProvider: (provider) => {
+				contributions.providers.push({
+					id: makeId(pluginId, "provider"),
+					name: provider.name,
+					description: provider.description,
+					metadata: sanitizeObject(provider.metadata),
+				});
+			},
+		};
+
+		if (typeof plugin.setup === "function") {
+			await plugin.setup(api);
+		}
+
+		pluginState.set(pluginId, { plugin, handlers });
+		descriptors.push({
+			pluginId,
+			name: plugin.name,
+			manifest: plugin.manifest,
+			contributions,
+		});
+	}
+
+	return descriptors;
+}
+
+async function invokeHook(args: {
+	pluginId: string;
+	hookName: string;
+	payload: unknown;
+}): Promise<unknown> {
+	const state = getPlugin(args.pluginId);
+	const handler = state.plugin[args.hookName];
+	if (typeof handler !== "function") {
+		return undefined;
+	}
+	return await (handler as (payload: unknown) => Promise<unknown>)(
+		args.payload,
+	);
+}
+
+async function executeTool(args: {
+	pluginId: string;
+	contributionId: string;
+	input: unknown;
+	context: unknown;
+}): Promise<unknown> {
+	const state = getPlugin(args.pluginId);
+	const handler = state.handlers.tools.get(args.contributionId);
+	if (typeof handler !== "function") {
+		throw new Error("Unknown sandbox tool contribution");
+	}
+	return await handler(args.input, args.context);
+}
+
+async function executeCommand(args: {
+	pluginId: string;
+	contributionId: string;
+	input: string;
+}): Promise<string> {
+	const state = getPlugin(args.pluginId);
+	const handler = state.handlers.commands.get(args.contributionId);
+	if (typeof handler !== "function") {
+		return "";
+	}
+	return await handler(args.input);
+}
+
+async function renderMessage(args: {
+	pluginId: string;
+	contributionId: string;
+	message: unknown;
+}): Promise<string> {
+	const state = getPlugin(args.pluginId);
+	const handler = state.handlers.messageRenderers.get(args.contributionId);
+	if (typeof handler !== "function") {
+		return "";
+	}
+	return await handler(args.message);
+}
+
+// ---------------------------------------------------------------------------
+// Message dispatch
+// ---------------------------------------------------------------------------
+
+const methods: Record<string, (args: never) => Promise<unknown>> = {
+	initialize,
+	invokeHook,
+	executeTool,
+	executeCommand,
+	renderMessage,
+};
+
+process.on(
+	"message",
+	async (message: {
+		type: string;
+		id: string;
+		method: string;
+		args?: unknown;
+	}) => {
+		if (!message || message.type !== "call") {
+			return;
+		}
+		const method = methods[message.method];
+		if (!method) {
+			sendResponse(message.id, false, undefined, {
+				message: `Unknown method: ${String(message.method)}`,
+			});
+			return;
+		}
+		try {
+			const result = await method((message.args || {}) as never);
+			sendResponse(message.id, true, result);
+		} catch (error) {
+			sendResponse(message.id, false, undefined, toErrorPayload(error));
+		}
+	},
+);