@clinebot/core 0.0.21 → 0.0.23

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

@@ -0,0 +1,296 @@
+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";
+import { afterAll, beforeAll, beforeEach, 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", () => {
+	let dir = "";
+	let sharedSandbox:
+		| Awaited<ReturnType<typeof loadSandboxedPlugins>>
+		| undefined;
+	let sharedExtensions = new Map<
+		string,
+		NonNullable<AgentConfig["extensions"]>[number]
+	>();
+	const forwardedEvents: Array<{ name: string; payload?: unknown }> = [];
+
+	beforeAll(async () => {
+		dir = await mkdtemp(join(tmpdir(), "core-plugin-sandbox-"));
+
+		await writeFile(
+			join(dir, "plugin.mjs"),
+			[
+				"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",
+		);
+
+		await writeFile(
+			join(dir, "plugin-events.mjs"),
+			[
+				"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",
+		);
+
+		await writeFile(
+			join(dir, "plugin-ts.ts"),
+			[
+				"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 localDepDir = join(dir, "node_modules", "sandbox-local-dep");
+		await mkdir(localDepDir, { recursive: true });
+		await writeFile(
+			join(localDepDir, "package.json"),
+			JSON.stringify({
+				name: "sandbox-local-dep",
+				type: "module",
+				exports: "./index.js",
+			}),
+			"utf8",
+		);
+		await writeFile(
+			join(localDepDir, "index.js"),
+			"export const depName = 'sandbox-local-dep';\n",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-dep.ts"),
+			[
+				"import { depName } from 'sandbox-local-dep';",
+				"export default {",
+				"  name: depName,",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		const sdkDepDir = join(dir, "node_modules", "@clinebot", "shared");
+		await mkdir(sdkDepDir, { recursive: true });
+		await writeFile(
+			join(sdkDepDir, "package.json"),
+			JSON.stringify({
+				name: "@clinebot/shared",
+				type: "module",
+				exports: "./index.js",
+			}),
+			"utf8",
+		);
+		await writeFile(
+			join(sdkDepDir, "index.js"),
+			"export const sdkMarker = 'sandbox-plugin-installed-sdk';\n",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-sdk.ts"),
+			[
+				"import { sdkMarker } from '@clinebot/shared';",
+				"export default {",
+				"  name: sdkMarker,",
+				"  manifest: { capabilities: ['tools'] },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		sharedSandbox = await loadSandboxedPlugins({
+			pluginPaths: [
+				join(dir, "plugin.mjs"),
+				join(dir, "plugin-events.mjs"),
+				join(dir, "plugin-ts.ts"),
+				join(dir, "plugin-dep.ts"),
+				join(dir, "plugin-sdk.ts"),
+			],
+			onEvent: (event) => {
+				forwardedEvents.push(event);
+			},
+		});
+		sharedExtensions = new Map(
+			(sharedSandbox.extensions ?? []).map((extension) => [
+				extension.name,
+				extension,
+			]),
+		);
+	});
+
+	beforeEach(() => {
+		forwardedEvents.length = 0;
+	});
+
+	afterAll(async () => {
+		await sharedSandbox?.shutdown();
+		if (dir) {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("runs plugin hooks and tool contributions in sandbox process", async () => {
+		expect(sharedSandbox?.extensions).toBeDefined();
+		const extension = sharedExtensions.get("sandbox-test");
+		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" });
+	});
+
+	it("enforces hook timeout and cancels sandbox process", async () => {
+		const timeoutDir = await mkdtemp(
+			join(tmpdir(), "core-plugin-sandbox-timeout-"),
+		);
+		try {
+			const pluginPath = join(timeoutDir, "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(timeoutDir, { recursive: true, force: true });
+		}
+	});
+
+	it("forwards sandbox plugin events to the host", async () => {
+		const extension = sharedExtensions.get("sandbox-events");
+		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(forwardedEvents).toEqual([
+			{
+				name: "test_event",
+				payload: { value: "hello" },
+			},
+		]);
+	});
+
+	it("loads TypeScript plugins in the sandbox process", async () => {
+		const extension = sharedExtensions.get("sandbox-ts");
+		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" });
+	});
+
+	it("resolves plugin-local dependencies in the sandbox process", async () => {
+		expect(sharedExtensions.get("sandbox-local-dep")?.name).toBe(
+			"sandbox-local-dep",
+		);
+	});
+
+	it("prefers plugin-installed SDK packages in the sandbox process", async () => {
+		expect(sharedExtensions.get("sandbox-plugin-installed-sdk")?.name).toBe(
+			"sandbox-plugin-installed-sdk",
+		);
+	});
+});

package/src/agents/plugin-sandbox.ts

@@ -0,0 +1,341 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig, Tool } from "@clinebot/agents";
+import { SubprocessSandbox } from "../runtime/sandbox/subprocess-sandbox";
+
+export interface PluginSandboxOptions {
+	pluginPaths: string[];
+	exportName?: string;
+	importTimeoutMs?: number;
+	hookTimeoutMs?: number;
+	contributionTimeoutMs?: number;
+	onEvent?: (event: { name: string; payload?: unknown }) => void;
+}
+
+type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
+type AgentExtensionApi = Parameters<NonNullable<AgentExtension["setup"]>>[0];
+type HookStage =
+	| "input"
+	| "runtime_event"
+	| "session_start"
+	| "before_agent_start"
+	| "tool_call_before"
+	| "tool_call_after"
+	| "turn_end"
+	| "session_shutdown"
+	| "error";
+
+type SandboxedContributionDescriptor = {
+	id: string;
+	name: string;
+	description?: string;
+	inputSchema?: unknown;
+	timeoutMs?: number;
+	retryable?: boolean;
+	value?: string;
+	defaultValue?: boolean | string | number;
+	metadata?: Record<string, unknown>;
+};
+
+type SandboxedPluginDescriptor = {
+	pluginId: string;
+	name: string;
+	manifest: AgentExtension["manifest"];
+	contributions: {
+		tools: SandboxedContributionDescriptor[];
+		commands: SandboxedContributionDescriptor[];
+		shortcuts: SandboxedContributionDescriptor[];
+		flags: SandboxedContributionDescriptor[];
+		messageRenderers: SandboxedContributionDescriptor[];
+		providers: SandboxedContributionDescriptor[];
+	};
+};
+
+/**
+ * Resolve the bootstrap for the sandbox subprocess.
+ *
+ * In production (bundled), the compiled `.js` file lives next to this module
+ * and can be passed directly as a file to spawn. In development/test
+ * (unbundled, where only the `.ts` source exists), we load the TypeScript
+ * bootstrap through jiti from an inline script.
+ */
+function resolveBootstrap(): { file: string } | { script: string } {
+	const dir = dirname(fileURLToPath(import.meta.url));
+	// In dev, the bootstrap sits next to this file in src/agents/.
+	// In production, the main bundle is at dist/ but bootstrap is at dist/agents/.
+	const candidates = [
+		join(dir, "plugin-sandbox-bootstrap.js"),
+		join(dir, "agents", "plugin-sandbox-bootstrap.js"),
+	];
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return { file: candidate };
+	}
+	const tsPath = join(dir, "plugin-sandbox-bootstrap.ts");
+	return {
+		script: [
+			"const createJiti = require('jiti');",
+			`const jiti = createJiti(${JSON.stringify(tsPath)}, { cache: false, requireCache: false, esmResolve: true, interopDefault: false });`,
+			`Promise.resolve(jiti.import(${JSON.stringify(tsPath)}, {})).catch((error) => {`,
+			"  console.error(error);",
+			"  process.exitCode = 1;",
+			"});",
+		].join("\n"),
+	};
+}
+
+const BOOTSTRAP = resolveBootstrap();
+
+/**
+ * Map from hook stage names in the manifest to the property name on AgentExtension
+ * and the corresponding hook method name inside the sandbox subprocess.
+ */
+const HOOK_BINDINGS: Array<{
+	stage: HookStage;
+	extensionKey: keyof AgentExtension;
+	sandboxHookName: string;
+}> = [
+	{ stage: "input", extensionKey: "onInput", sandboxHookName: "onInput" },
+	{
+		stage: "session_start",
+		extensionKey: "onSessionStart",
+		sandboxHookName: "onSessionStart",
+	},
+	{
+		stage: "before_agent_start",
+		extensionKey: "onBeforeAgentStart",
+		sandboxHookName: "onBeforeAgentStart",
+	},
+	{
+		stage: "tool_call_before",
+		extensionKey: "onToolCall",
+		sandboxHookName: "onToolCall",
+	},
+	{
+		stage: "tool_call_after",
+		extensionKey: "onToolResult",
+		sandboxHookName: "onToolResult",
+	},
+	{
+		stage: "turn_end",
+		extensionKey: "onAgentEnd",
+		sandboxHookName: "onAgentEnd",
+	},
+	{
+		stage: "session_shutdown",
+		extensionKey: "onSessionShutdown",
+		sandboxHookName: "onSessionShutdown",
+	},
+	{
+		stage: "runtime_event",
+		extensionKey: "onRuntimeEvent",
+		sandboxHookName: "onRuntimeEvent",
+	},
+	{ stage: "error", extensionKey: "onError", sandboxHookName: "onError" },
+];
+
+function hasHookStage(extension: AgentExtension, stage: HookStage): boolean {
+	return extension.manifest.hookStages?.includes(stage) === true;
+}
+
+function withTimeoutFallback(
+	timeoutMs: number | undefined,
+	fallback: number,
+): number {
+	return typeof timeoutMs === "number" && timeoutMs > 0 ? timeoutMs : fallback;
+}
+
+export async function loadSandboxedPlugins(
+	options: PluginSandboxOptions,
+): Promise<{
+	extensions: AgentConfig["extensions"];
+	shutdown: () => Promise<void>;
+}> {
+	const sandbox = new SubprocessSandbox({
+		name: "plugin-sandbox",
+		...("file" in BOOTSTRAP
+			? { bootstrapFile: BOOTSTRAP.file }
+			: { bootstrapScript: BOOTSTRAP.script }),
+		onEvent: options.onEvent,
+	});
+	const importTimeoutMs = withTimeoutFallback(options.importTimeoutMs, 4000);
+	const hookTimeoutMs = withTimeoutFallback(options.hookTimeoutMs, 3000);
+	const contributionTimeoutMs = withTimeoutFallback(
+		options.contributionTimeoutMs,
+		5000,
+	);
+
+	let descriptors: SandboxedPluginDescriptor[];
+	try {
+		descriptors = await sandbox.call<SandboxedPluginDescriptor[]>(
+			"initialize",
+			{
+				pluginPaths: options.pluginPaths,
+				exportName: options.exportName,
+			},
+			{ timeoutMs: importTimeoutMs },
+		);
+	} catch (error) {
+		await sandbox.shutdown().catch(() => {
+			// Best-effort cleanup when sandbox initialization fails.
+		});
+		throw error;
+	}
+
+	const extensions: NonNullable<AgentConfig["extensions"]> = descriptors.map(
+		(descriptor) => {
+			const extension: AgentExtension = {
+				name: descriptor.name,
+				manifest: descriptor.manifest,
+				setup: (api: AgentExtensionApi) => {
+					registerTools(api, sandbox, descriptor, contributionTimeoutMs);
+					registerCommands(api, sandbox, descriptor, contributionTimeoutMs);
+					registerSimpleContributions(api, descriptor);
+				},
+			};
+
+			bindHooks(extension, sandbox, descriptor.pluginId, hookTimeoutMs);
+
+			return extension;
+		},
+	);
+
+	return {
+		extensions,
+		shutdown: async () => {
+			await sandbox.shutdown();
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Contribution registration helpers
+// ---------------------------------------------------------------------------
+
+function registerTools(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+): void {
+	for (const td of descriptor.contributions.tools) {
+		const tool: Tool = {
+			name: td.name,
+			description: td.description ?? "",
+			inputSchema: (td.inputSchema ?? {
+				type: "object",
+				properties: {},
+			}) as Tool["inputSchema"],
+			timeoutMs: td.timeoutMs,
+			retryable: td.retryable,
+			execute: async (input: unknown, context: unknown) =>
+				await sandbox.call(
+					"executeTool",
+					{
+						pluginId: descriptor.pluginId,
+						contributionId: td.id,
+						input,
+						context,
+					},
+					{ timeoutMs },
+				),
+		};
+		api.registerTool(tool);
+	}
+}
+
+function registerCommands(
+	api: AgentExtensionApi,
+	sandbox: SubprocessSandbox,
+	descriptor: SandboxedPluginDescriptor,
+	timeoutMs: number,
+): void {
+	for (const cd of descriptor.contributions.commands) {
+		api.registerCommand({
+			name: cd.name,
+			description: cd.description,
+			handler: async (input: string) =>
+				await sandbox.call<string>(
+					"executeCommand",
+					{
+						pluginId: descriptor.pluginId,
+						contributionId: cd.id,
+						input,
+					},
+					{ timeoutMs },
+				),
+		});
+	}
+}
+
+function registerSimpleContributions(
+	api: AgentExtensionApi,
+	descriptor: SandboxedPluginDescriptor,
+): void {
+	for (const sd of descriptor.contributions.shortcuts) {
+		api.registerShortcut({
+			name: sd.name,
+			value: sd.value ?? "",
+			description: sd.description,
+		});
+	}
+
+	for (const fd of descriptor.contributions.flags) {
+		api.registerFlag({
+			name: fd.name,
+			description: fd.description,
+			defaultValue: fd.defaultValue,
+		});
+	}
+
+	for (const rd of descriptor.contributions.messageRenderers) {
+		api.registerMessageRenderer({
+			name: rd.name,
+			render: () => `[sandbox renderer ${rd.name} requires async bridge]`,
+		});
+	}
+
+	for (const pd of descriptor.contributions.providers) {
+		api.registerProvider({
+			name: pd.name,
+			description: pd.description,
+			metadata: pd.metadata,
+		});
+	}
+}
+
+function makeHookHandler(
+	sandbox: SubprocessSandbox,
+	pluginId: string,
+	hookName: string,
+	timeoutMs: number,
+): (payload: unknown) => Promise<unknown> {
+	return async (payload: unknown) =>
+		await sandbox.call(
+			"invokeHook",
+			{ pluginId, hookName, payload },
+			{ timeoutMs },
+		);
+}
+
+function bindHooks(
+	extension: AgentExtension,
+	sandbox: SubprocessSandbox,
+	pluginId: string,
+	hookTimeoutMs: number,
+): void {
+	for (const { stage, extensionKey, sandboxHookName } of HOOK_BINDINGS) {
+		if (hasHookStage(extension, stage)) {
+			const handler = makeHookHandler(
+				sandbox,
+				pluginId,
+				sandboxHookName,
+				hookTimeoutMs,
+			);
+			// Each hook property on AgentExtension accepts (payload: unknown) => Promise<unknown>.
+			// TypeScript cannot narrow a union of optional callback keys via computed access,
+			// so we use Object.assign to set the property safely.
+			Object.assign(extension, { [extensionKey]: handler });
+		}
+	}
+}