@clinebot/core 0.0.11 → 0.0.13

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));
+		}
+	},
+);

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

@@ -1,4 +1,4 @@
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, 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";
@@ -117,4 +117,201 @@ describe("plugin-sandbox", () => {
 			await rm(dir, { recursive: true, force: true });
 		}
 	});
+
+	it("forwards sandbox plugin events to the host", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-events-"));
+		try {
+			const pluginPath = join(dir, "plugin-events.mjs");
+			await writeFile(
+				pluginPath,
+				[
+					"export default {",
+					"  name: 'sandbox-events',",
+					"  manifest: { capabilities: ['tools'] },",
+					"  setup(api) {",
+					"    api.registerTool({",
+					"      name: 'emit_event',",
+					"      description: 'emit host event',",
+					"      inputSchema: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'] },",
+					"      execute: async (input) => {",
+					"        globalThis.__clinePluginHost?.emitEvent?.('test_event', { value: input.value });",
+					"        return { ok: true };",
+					"      },",
+					"    });",
+					"  },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const events: Array<{ name: string; payload?: unknown }> = [];
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+				onEvent: (event) => {
+					events.push(event);
+				},
+			});
+			try {
+				const extension = sandboxed.extensions?.[0];
+				const { tools, api } = createApiCapture();
+				await extension?.setup?.(api);
+				const tool = tools.find((entry) => entry.name === "emit_event");
+				await tool?.execute({ value: "hello" }, {
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					iteration: 1,
+				} as ToolContext);
+				expect(events).toEqual([
+					{
+						name: "test_event",
+						payload: { value: "hello" },
+					},
+				]);
+			} finally {
+				await sandboxed.shutdown();
+			}
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("loads TypeScript plugins in the sandbox process", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-ts-"));
+		try {
+			const pluginPath = join(dir, "plugin-ts.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"const TOOL_NAME: string = 'sandbox_ts_echo';",
+					"export default {",
+					"  name: 'sandbox-ts',",
+					"  manifest: { capabilities: ['tools'] },",
+					"  setup(api) {",
+					"    api.registerTool({",
+					"      name: TOOL_NAME,",
+					"      description: 'echo',",
+					"      inputSchema: { type: 'object', properties: { value: { type: 'string' } }, required: ['value'] },",
+					"      execute: async (input) => ({ echoed: input.value }),",
+					"    });",
+					"  },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+			});
+			try {
+				const extension = sandboxed.extensions?.[0];
+				expect(extension?.name).toBe("sandbox-ts");
+				const { tools, api } = createApiCapture();
+				await extension?.setup?.(api);
+				const tool = tools.find((entry) => entry.name === "sandbox_ts_echo");
+				expect(tool).toBeDefined();
+				const result = await tool?.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("resolves plugin-local dependencies in the sandbox process", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-deps-"));
+		try {
+			const depDir = join(dir, "node_modules", "sandbox-local-dep");
+			await mkdir(depDir, { recursive: true });
+			await writeFile(
+				join(depDir, "package.json"),
+				JSON.stringify({
+					name: "sandbox-local-dep",
+					type: "module",
+					exports: "./index.js",
+				}),
+				"utf8",
+			);
+			await writeFile(
+				join(depDir, "index.js"),
+				"export const depName = 'sandbox-local-dep';\n",
+				"utf8",
+			);
+			const pluginPath = join(dir, "plugin-dep.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"import { depName } from 'sandbox-local-dep';",
+					"export default {",
+					"  name: depName,",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+			});
+			try {
+				expect(sandboxed.extensions?.[0]?.name).toBe("sandbox-local-dep");
+			} finally {
+				await sandboxed.shutdown();
+			}
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("prefers plugin-installed SDK packages in the sandbox process", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-sdk-"));
+		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 = 'sandbox-plugin-installed-sdk';\n",
+				"utf8",
+			);
+			const pluginPath = join(dir, "plugin-sdk.ts");
+			await writeFile(
+				pluginPath,
+				[
+					"import { sdkMarker } from '@clinebot/shared';",
+					"export default {",
+					"  name: sdkMarker,",
+					"  manifest: { capabilities: ['tools'] },",
+					"};",
+				].join("\n"),
+				"utf8",
+			);
+
+			const sandboxed = await loadSandboxedPlugins({
+				pluginPaths: [pluginPath],
+			});
+			try {
+				expect(sandboxed.extensions?.[0]?.name).toBe(
+					"sandbox-plugin-installed-sdk",
+				);
+			} finally {
+				await sandboxed.shutdown();
+			}
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
 });