@clinebot/core 0.0.35 → 0.0.37

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

@@ -4,13 +4,22 @@
  * 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.
+ * message builders, providers) and lifecycle hooks.
  *
  * Because it executes in a separate process it must stay bundle-safe and only
  * depend on local helpers that can be inlined into the sandbox build.
  */
 
+import {
+	type AutomationEventEnvelope,
+	normalizePluginManifest,
+	type PluginManifest,
+} from "@clinebot/shared";
 import { importPluginModule } from "./plugin-module-import";
+import {
+	matchesPluginManifestTargeting,
+	type PluginTargeting,
+} from "./plugin-targeting";
 
 // ---------------------------------------------------------------------------
 // Types (intentionally minimal – mirrors only what the RPC protocol needs)
@@ -31,18 +40,6 @@ interface PluginCommand {
 	handler?: (input: string) => Promise<string>;
 }
 
-interface PluginShortcut {
-	name: string;
-	value: string;
-	description?: string;
-}
-
-interface PluginFlag {
-	name: string;
-	description?: string;
-	defaultValue?: boolean | string | number;
-}
-
 interface PluginMessageBuilder {
 	name: string;
 	build: (message: unknown[]) => unknown[]; // Message[]
@@ -54,19 +51,43 @@ interface PluginProvider {
 	metadata?: Record<string, unknown>;
 }
 
+interface PluginAutomationEventType {
+	eventType: string;
+	source: string;
+	description?: string;
+	attributesSchema?: Record<string, unknown>;
+	payloadSchema?: Record<string, unknown>;
+	examples?: AutomationEventEnvelope[];
+	metadata?: Record<string, unknown>;
+}
+
 interface PluginApi {
 	registerTool(tool: PluginTool): void;
 	registerCommand(command: PluginCommand): void;
-	registerShortcut(shortcut: PluginShortcut): void;
-	registerFlag(flag: PluginFlag): void;
 	registerMessageBuilder(builder: PluginMessageBuilder): void;
 	registerProvider(provider: PluginProvider): void;
+	registerAutomationEventType(eventType: PluginAutomationEventType): void;
+}
+
+interface PluginSetupCtx {
+	session?: unknown;
+	client?: unknown;
+	user?: unknown;
+	workspaceInfo?: unknown;
+	automation?: {
+		ingestEvent(event: AutomationEventEnvelope): void | Promise<void>;
+	};
+	logger?: {
+		debug(message: string, metadata?: Record<string, unknown>): void;
+		log(message: string, metadata?: Record<string, unknown>): void;
+		error(message: string, metadata?: Record<string, unknown>): void;
+	};
 }
 
 interface PluginModule {
 	name: string;
-	manifest: Record<string, unknown>;
-	setup?: (api: PluginApi) => void | Promise<void>;
+	manifest: PluginManifest;
+	setup?: (api: PluginApi, ctx: PluginSetupCtx) => void | Promise<void>;
 	[hookName: string]: unknown;
 }
 
@@ -82,18 +103,30 @@ interface ContributionDescriptor {
 	metadata?: Record<string, unknown>;
 }
 
+interface AutomationEventTypeDescriptor {
+	id: string;
+	eventType: string;
+	source: string;
+	description?: string;
+	attributesSchema?: Record<string, unknown>;
+	payloadSchema?: Record<string, unknown>;
+	examples?: AutomationEventEnvelope[];
+	metadata?: Record<string, unknown>;
+}
+
 interface PluginDescriptor {
 	pluginId: string;
 	pluginPath: string;
 	name: string;
-	manifest: Record<string, unknown>;
+	manifest: PluginManifest;
 	contributions: {
 		tools: ContributionDescriptor[];
 		commands: ContributionDescriptor[];
-		shortcuts: ContributionDescriptor[];
-		flags: ContributionDescriptor[];
 		messageBuilders: ContributionDescriptor[];
 		providers: ContributionDescriptor[];
+		automationEventTypes: AutomationEventTypeDescriptor[];
+		shortcuts?: ContributionDescriptor[];
+		flags?: ContributionDescriptor[];
 	};
 }
 
@@ -132,6 +165,12 @@ 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 assertValidPluginModule(
 	plugin: unknown,
 	pluginPath: string,
@@ -145,6 +184,52 @@ function assertValidPluginModule(
 	if (!isObject(plugin.manifest)) {
 		throw new Error(`Invalid plugin manifest: ${pluginPath}`);
 	}
+	if (
+		Object.hasOwn(plugin.manifest, "providerIds") &&
+		!hasValidStringArray(plugin.manifest.providerIds)
+	) {
+		throw new Error(`Invalid plugin manifest.providerIds: ${pluginPath}`);
+	}
+	if (
+		Object.hasOwn(plugin.manifest, "modelIds") &&
+		!hasValidStringArray(plugin.manifest.modelIds)
+	) {
+		throw new Error(`Invalid plugin manifest.modelIds: ${pluginPath}`);
+	}
+}
+
+function assertValidPluginSetupCtx(
+	ctx: unknown,
+): asserts ctx is PluginSetupCtx {
+	if (!isObject(ctx)) {
+		throw new Error("Plugin setup context must be an object");
+	}
+	if (ctx.session !== undefined && !isObject(ctx.session)) {
+		throw new Error("Plugin setup context session must be an object");
+	}
+	if (ctx.client !== undefined && !isObject(ctx.client)) {
+		throw new Error("Plugin setup context client must be an object");
+	}
+	if (ctx.user !== undefined && !isObject(ctx.user)) {
+		throw new Error("Plugin setup context user must be an object");
+	}
+	if (ctx.workspaceInfo !== undefined && !isObject(ctx.workspaceInfo)) {
+		throw new Error("Plugin setup context workspaceInfo must be an object");
+	}
+	if (ctx.automation !== undefined && !isObject(ctx.automation)) {
+		throw new Error("Plugin setup context automation must be an object");
+	}
+	if (
+		ctx.automation !== undefined &&
+		typeof ctx.automation.ingestEvent !== "function"
+	) {
+		throw new Error(
+			"Plugin setup context automation.ingestEvent must be a function",
+		);
+	}
+	if (ctx.logger !== undefined && !isObject(ctx.logger)) {
+		throw new Error("Plugin setup context logger must be an object");
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -183,6 +268,16 @@ function emitEvent(name: string, payload?: unknown): void {
 // Expose event emitter to plugins.
 (globalThis as Record<string, unknown>).__clinePluginHost = { emitEvent };
 
+/**
+ * Session workspace env — populated by `initialize()` and available to any
+ * plugin code that executes before the setup hook, or cannot use hook context.
+ * Prefer using PluginSetupCtx from the setup function when possible.
+ */
+(globalThis as Record<string, unknown>).__clineSessionEnv = {
+	cwd: undefined as string | undefined,
+	workspaceInfo: undefined as unknown,
+};
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -192,6 +287,45 @@ function sanitizeObject(value: unknown): Record<string, unknown> {
 	return value as Record<string, unknown>;
 }
 
+function sanitizeLogMetadata(
+	value: unknown,
+): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+	const metadata = { ...(value as Record<string, unknown>) };
+	if (metadata.error instanceof Error) {
+		metadata.error = {
+			name: metadata.error.name,
+			message: metadata.error.message,
+			stack: metadata.error.stack,
+		};
+	}
+	return metadata;
+}
+
+function createPluginLogger(
+	pluginName: string,
+): NonNullable<PluginSetupCtx["logger"]> {
+	const emitLog = (
+		level: "debug" | "log" | "error",
+		message: string,
+		metadata?: Record<string, unknown>,
+	) => {
+		emitEvent("plugin_log", {
+			level,
+			pluginName,
+			message,
+			metadata: sanitizeLogMetadata(metadata),
+		});
+	};
+	return {
+		debug: (message, metadata) => emitLog("debug", message, metadata),
+		log: (message, metadata) => emitLog("log", message, metadata),
+		error: (message, metadata) => emitLog("error", message, metadata),
+	};
+}
+
 function makeId(pluginId: string, prefix: string): string {
 	const key = `${pluginId}:${prefix}`;
 	const next = (contributionCounters.get(key) ?? 0) + 1;
@@ -199,6 +333,30 @@ function makeId(pluginId: string, prefix: string): string {
 	return `${pluginId}_${prefix}_${next}`;
 }
 
+function normalizeAutomationEventType(
+	eventType: PluginAutomationEventType,
+): PluginAutomationEventType {
+	const normalizedEventType =
+		typeof eventType.eventType === "string" ? eventType.eventType.trim() : "";
+	const source =
+		typeof eventType.source === "string" ? eventType.source.trim() : "";
+	if (!normalizedEventType) {
+		throw new Error("Automation event type contribution requires eventType");
+	}
+	if (!source) {
+		throw new Error("Automation event type contribution requires source");
+	}
+	return {
+		...eventType,
+		eventType: normalizedEventType,
+		source,
+		examples: eventType.examples ? [...eventType.examples] : undefined,
+		metadata: eventType.metadata
+			? sanitizeObject(eventType.metadata)
+			: undefined,
+	};
+}
+
 function getPlugin(pluginId: string): PluginState {
 	const state = pluginState.get(pluginId);
 	if (!state) {
@@ -214,16 +372,48 @@ function getPlugin(pluginId: string): PluginState {
 async function initialize(args: {
 	pluginPaths?: string[];
 	exportName?: string;
+	providerId?: string;
+	modelId?: string;
+	cwd?: string;
+	session?: unknown;
+	client?: unknown;
+	user?: unknown;
+	workspaceInfo?: unknown;
+	loggerEnabled?: boolean;
 }): Promise<InitializeResult> {
 	pluginState.clear();
 	pluginCounter = 0;
 	contributionCounters.clear();
 
+	// Apply the session's working directory so that process.cwd() and relative
+	// path resolution inside plugins reflect the correct workspace, not the
+	// host process's cwd (which may differ when --cwd was used without calling
+	// process.chdir() on the host side).
+	if (args.cwd) {
+		try {
+			process.chdir(args.cwd);
+		} catch {
+			// Ignore — best-effort; path may not exist in unusual environments.
+		}
+	}
+
+	// Keep the global escape-hatch in sync with the active session.
+	const sessionEnv = (globalThis as Record<string, unknown>)
+		.__clineSessionEnv as Record<string, unknown>;
+	if (sessionEnv) {
+		sessionEnv.cwd = args.cwd;
+		sessionEnv.workspaceInfo = args.workspaceInfo;
+	}
+
 	const descriptors: PluginDescriptor[] = [];
 	const failures: PluginInitializationFailure[] = [];
 	const warnings: PluginInitializationWarning[] = [];
 	const exportName = args.exportName || "plugin";
 	const pluginIndexByName = new Map<string, number>();
+	const targeting: PluginTargeting = {
+		providerId: args.providerId,
+		modelId: args.modelId,
+	};
 
 	for (const pluginPath of args.pluginPaths || []) {
 		let plugin: PluginModule | undefined;
@@ -232,15 +422,20 @@ async function initialize(args: {
 			plugin = (moduleExports.default ??
 				moduleExports[exportName]) as unknown as PluginModule;
 			assertValidPluginModule(plugin, pluginPath);
+			plugin.manifest = normalizePluginManifest(plugin.manifest);
+			if (!matchesPluginManifestTargeting(plugin.manifest, targeting)) {
+				continue;
+			}
 
 			const pluginId = `plugin_${++pluginCounter}`;
 			const contributions: PluginDescriptor["contributions"] = {
 				tools: [],
 				commands: [],
-				shortcuts: [],
-				flags: [],
 				messageBuilders: [],
 				providers: [],
+				automationEventTypes: [],
+				shortcuts: [],
+				flags: [],
 			};
 			const handlers: PluginState["handlers"] = {
 				tools: new Map(),
@@ -272,22 +467,6 @@ async function initialize(args: {
 						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,
-					});
-				},
 				registerMessageBuilder: (builder) => {
 					const id = makeId(pluginId, "builder");
 					handlers.messageBuilders.set(id, builder.build);
@@ -301,11 +480,36 @@ async function initialize(args: {
 						metadata: sanitizeObject(provider.metadata),
 					});
 				},
+				registerAutomationEventType: (eventType) => {
+					contributions.automationEventTypes.push({
+						id: makeId(pluginId, "automation_event"),
+						...normalizeAutomationEventType(eventType),
+					});
+				},
 			};
 
 			if (typeof plugin.setup === "function") {
 				try {
-					await plugin.setup(api);
+					const setupCtx = {
+						session: args.session,
+						client: args.client,
+						user: args.user,
+						workspaceInfo: args.workspaceInfo,
+						...(args.loggerEnabled
+							? { logger: createPluginLogger(plugin.name) }
+							: {}),
+						...(plugin.manifest.capabilities.includes("automationEvents")
+							? {
+									automation: {
+										ingestEvent: (event: AutomationEventEnvelope) => {
+											emitEvent("automation_event", event);
+										},
+									},
+								}
+							: {}),
+					};
+					assertValidPluginSetupCtx(setupCtx);
+					await plugin.setup(api, setupCtx);
 				} catch (error) {
 					failures.push({
 						pluginPath,