@clinebot/core 0.0.18 → 0.0.21

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

@@ -1,317 +0,0 @@
-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 { 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 });
-		}
-	});
-
-	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 });
-		}
-	});
-});

package/src/agents/plugin-sandbox.ts

@@ -1,341 +0,0 @@
-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 });
-		}
-	}
-}