@clinebot/core 0.0.33 → 0.0.34

package/src/auth/types.ts

@@ -1,4 +1,5 @@
 import type { ITelemetryService } from "@clinebot/shared";
+import type { OAuthServerCloseInfo, OAuthServerListeningInfo } from "./server";
 
 export interface OAuthPrompt {
 	message: string;
@@ -31,6 +32,34 @@ export interface OAuthLoginCallbacks {
 	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
 	onProgress?: (message: string) => void;
 	onManualCodeInput?: () => Promise<string>;
+	/**
+	 * Called when the local OAuth redirect server successfully binds to a port
+	 * and is ready to receive the browser callback. The `info` object contains
+	 * the host, the bound port number, and the full `callbackUrl`.
+	 *
+	 * Use this to:
+	 * - Show a "waiting for OAuth callback on port N" status indicator in your UI.
+	 * - Forward the port in remote-development environments (e.g. JetBrains
+	 *   Gateway) from the remote machine to the machine running the browser.
+	 *
+	 * Paired with `onServerClose` for teardown.
+	 *
+	 * Only fired when the provider uses a local callback server
+	 * (`OAuthProviderInterface.usesCallbackServer === true`).
+	 */
+	onServerListening?: (info: OAuthServerListeningInfo) => void | Promise<void>;
+	/**
+	 * Called when the local OAuth redirect server closes — either because the
+	 * callback was received, the flow was cancelled, or the timeout elapsed.
+	 *
+	 * Use this to:
+	 * - Clear any "waiting for callback" status UI shown in `onServerListening`.
+	 * - Tear down port-forwards set up in `onServerListening`.
+	 *
+	 * Only fired when the provider uses a local callback server
+	 * (`OAuthProviderInterface.usesCallbackServer === true`).
+	 */
+	onServerClose?: (info: OAuthServerCloseInfo) => void | Promise<void>;
 }
 
 export interface OAuthProviderInterface {

package/src/extensions/index.ts

@@ -5,8 +5,14 @@ export {
 	resolveAndLoadAgentPlugins,
 	resolvePluginConfigSearchPaths,
 } from "./plugin/plugin-config-loader";
+export type {
+	PluginInitializationFailure,
+	PluginInitializationWarning,
+	PluginLoadDiagnostics,
+} from "./plugin/plugin-load-report";
 export type { LoadAgentPluginFromPathOptions } from "./plugin/plugin-loader";
 export {
 	loadAgentPluginFromPath,
 	loadAgentPluginsFromPaths,
+	loadAgentPluginsFromPathsWithDiagnostics,
 } from "./plugin/plugin-loader";

package/src/extensions/plugin/plugin-config-loader.test.ts

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import {
 	discoverPluginModulePaths,
 	resolveAgentPluginPaths,
+	resolveAndLoadAgentPlugins,
 	resolvePluginConfigSearchPaths,
 } from "./plugin-config-loader";
 
@@ -142,4 +143,40 @@ describe("plugin-config-loader", () => {
 			await rm(workspace, { recursive: true, force: true });
 		}
 	});
+
+	it("loads valid plugins while reporting failures and duplicate overrides", async () => {
+		const root = await mkdtemp(join(tmpdir(), "core-plugin-config-loader-"));
+		try {
+			const first = join(root, "duplicate-one.js");
+			const second = join(root, "duplicate-two.js");
+			const invalid = join(root, "invalid.js");
+			await writeFile(
+				first,
+				"export default { name: 'duplicate-plugin', manifest: { capabilities: ['tools'] } };",
+				"utf8",
+			);
+			await writeFile(
+				second,
+				"export default { name: 'duplicate-plugin', manifest: { capabilities: ['commands'] } };",
+				"utf8",
+			);
+			await writeFile(invalid, "export default { name: 'broken' };", "utf8");
+
+			const loaded = await resolveAndLoadAgentPlugins({
+				mode: "in_process",
+				pluginPaths: [first, invalid, second],
+				cwd: root,
+			});
+
+			expect(loaded.extensions.map((plugin) => plugin.name)).toEqual([
+				"duplicate-plugin",
+			]);
+			expect(loaded.extensions[0]?.manifest.capabilities).toEqual(["commands"]);
+			expect(loaded.failures).toHaveLength(1);
+			expect(loaded.warnings).toHaveLength(1);
+			expect(loaded.warnings[0]?.overriddenPluginPath).toBe(first);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
 });

package/src/extensions/plugin/plugin-config-loader.ts

@@ -5,7 +5,8 @@ import {
 	resolveConfiguredPluginModulePaths,
 	resolvePluginConfigSearchPaths as resolvePluginConfigSearchPathsFromShared,
 } from "@clinebot/shared/storage";
-import { loadAgentPluginsFromPaths } from "./plugin-loader";
+import type { PluginLoadDiagnostics } from "./plugin-load-report";
+import { loadAgentPluginsFromPathsWithDiagnostics } from "./plugin-loader";
 import { loadSandboxedPlugins } from "./plugin-sandbox";
 
 type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
@@ -64,21 +65,26 @@ export interface ResolveAndLoadAgentPluginsOptions
 
 export async function resolveAndLoadAgentPlugins(
 	options: ResolveAndLoadAgentPluginsOptions = {},
-): Promise<{
-	extensions: AgentPlugin[];
-	shutdown?: () => Promise<void>;
-}> {
+): Promise<
+	{
+		extensions: AgentPlugin[];
+		shutdown?: () => Promise<void>;
+	} & PluginLoadDiagnostics
+> {
 	const paths = resolveAgentPluginPaths(options);
 	if (paths.length === 0) {
-		return { extensions: [] };
+		return { extensions: [], failures: [], warnings: [] };
 	}
 
 	if (options.mode === "in_process") {
+		const report = await loadAgentPluginsFromPathsWithDiagnostics(paths, {
+			cwd: options.cwd,
+			exportName: options.exportName,
+		});
 		return {
-			extensions: await loadAgentPluginsFromPaths(paths, {
-				cwd: options.cwd,
-				exportName: options.exportName,
-			}),
+			extensions: report.plugins,
+			failures: report.failures,
+			warnings: report.warnings,
 		};
 	}
 
@@ -93,5 +99,7 @@ export async function resolveAndLoadAgentPlugins(
 	return {
 		extensions: sandboxed.extensions ?? [],
 		shutdown: sandboxed.shutdown,
+		failures: sandboxed.failures,
+		warnings: sandboxed.warnings,
 	};
 }

package/src/extensions/plugin/plugin-load-report.ts

@@ -0,0 +1,20 @@
+export interface PluginInitializationFailure {
+	pluginPath: string;
+	pluginName?: string;
+	phase: "load" | "setup";
+	message: string;
+	stack?: string;
+}
+
+export interface PluginInitializationWarning {
+	type: "duplicate_plugin_override";
+	pluginPath: string;
+	pluginName: string;
+	overriddenPluginPath: string;
+	message: string;
+}
+
+export interface PluginLoadDiagnostics {
+	failures: PluginInitializationFailure[];
+	warnings: PluginInitializationWarning[];
+}

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

@@ -5,6 +5,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
 	loadAgentPluginFromPath,
 	loadAgentPluginsFromPaths,
+	loadAgentPluginsFromPathsWithDiagnostics,
 } from "./plugin-loader";
 
 describe("plugin-loader", () => {
@@ -158,6 +159,17 @@ describe("plugin-loader", () => {
 			"export default { name: 'invalid-plugin' };",
 			"utf8",
 		);
+
+		await writeFile(
+			join(dir, "duplicate-one.mjs"),
+			"export default { name: 'duplicate-plugin', manifest: { capabilities: ['tools'] } };",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "duplicate-two.mjs"),
+			"export default { name: 'duplicate-plugin', manifest: { capabilities: ['commands'] } };",
+			"utf8",
+		);
 	});
 
 	afterAll(async () => {
@@ -244,4 +256,37 @@ describe("plugin-loader", () => {
 			loadAgentPluginFromPath(join(dir, "invalid-plugin.mjs")),
 		).rejects.toThrow(/missing required "manifest"/i);
 	});
+
+	it("continues loading valid plugins when one plugin fails", async () => {
+		const report = await loadAgentPluginsFromPathsWithDiagnostics([
+			join(dir, "plugin-a.mjs"),
+			join(dir, "invalid-plugin.mjs"),
+			join(dir, "plugin-b.mjs"),
+		]);
+
+		expect(report.plugins.map((plugin) => plugin.name)).toEqual([
+			"plugin-a",
+			"plugin-b",
+		]);
+		expect(report.failures).toHaveLength(1);
+		expect(report.failures[0]?.pluginPath).toBe(
+			join(dir, "invalid-plugin.mjs"),
+		);
+		expect(report.warnings).toEqual([]);
+	});
+
+	it("keeps the later duplicate plugin and reports the override", async () => {
+		const report = await loadAgentPluginsFromPathsWithDiagnostics([
+			join(dir, "duplicate-one.mjs"),
+			join(dir, "duplicate-two.mjs"),
+		]);
+
+		expect(report.plugins).toHaveLength(1);
+		expect(report.plugins[0]?.name).toBe("duplicate-plugin");
+		expect(report.plugins[0]?.manifest.capabilities).toEqual(["commands"]);
+		expect(report.warnings).toHaveLength(1);
+		expect(report.warnings[0]?.overriddenPluginPath).toBe(
+			join(dir, "duplicate-one.mjs"),
+		);
+	});
 });

package/src/extensions/plugin/plugin-loader.ts

@@ -1,5 +1,9 @@
 import { resolve } from "node:path";
 import type { AgentConfig } from "@clinebot/shared";
+import type {
+	PluginInitializationFailure,
+	PluginInitializationWarning,
+} from "./plugin-load-report";
 import { importPluginModule } from "./plugin-module-import";
 
 type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
@@ -98,9 +102,59 @@ export async function loadAgentPluginsFromPaths(
 	pluginPaths: string[],
 	options: LoadAgentPluginFromPathOptions = {},
 ): Promise<AgentPlugin[]> {
-	const loaded: AgentPlugin[] = [];
+	const report = await loadAgentPluginsFromPathsWithDiagnostics(
+		pluginPaths,
+		options,
+	);
+	return report.plugins;
+}
+
+export async function loadAgentPluginsFromPathsWithDiagnostics(
+	pluginPaths: string[],
+	options: LoadAgentPluginFromPathOptions = {},
+): Promise<{
+	plugins: AgentPlugin[];
+	failures: PluginInitializationFailure[];
+	warnings: PluginInitializationWarning[];
+}> {
+	const failures: PluginInitializationFailure[] = [];
+	const warnings: PluginInitializationWarning[] = [];
+	const loadedByName = new Map<
+		string,
+		{ plugin: AgentPlugin; pluginPath: string; order: number }
+	>();
+	let order = 0;
+
 	for (const pluginPath of pluginPaths) {
-		loaded.push(await loadAgentPluginFromPath(pluginPath, options));
+		try {
+			const plugin = await loadAgentPluginFromPath(pluginPath, options);
+			const existing = loadedByName.get(plugin.name);
+			if (existing) {
+				warnings.push({
+					type: "duplicate_plugin_override",
+					pluginName: plugin.name,
+					pluginPath,
+					overriddenPluginPath: existing.pluginPath,
+					message: `Plugin "${plugin.name}" from ${pluginPath} overrides ${existing.pluginPath}`,
+				});
+			}
+			loadedByName.set(plugin.name, { plugin, pluginPath, order: order++ });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			failures.push({
+				pluginPath,
+				phase: "load",
+				message,
+				stack: error instanceof Error ? error.stack : undefined,
+			});
+		}
 	}
-	return loaded;
+
+	return {
+		plugins: [...loadedByName.values()]
+			.sort((left, right) => left.order - right.order)
+			.map((entry) => entry.plugin),
+		failures,
+		warnings,
+	};
 }

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

@@ -84,6 +84,7 @@ interface ContributionDescriptor {
 
 interface PluginDescriptor {
 	pluginId: string;
+	pluginPath: string;
 	name: string;
 	manifest: Record<string, unknown>;
 	contributions: {
@@ -96,6 +97,28 @@ interface PluginDescriptor {
 	};
 }
 
+interface PluginInitializationFailure {
+	pluginPath: string;
+	pluginName?: string;
+	phase: "load" | "setup";
+	message: string;
+	stack?: string;
+}
+
+interface PluginInitializationWarning {
+	type: "duplicate_plugin_override";
+	pluginPath: string;
+	pluginName: string;
+	overriddenPluginPath: string;
+	message: string;
+}
+
+interface InitializeResult {
+	plugins: PluginDescriptor[];
+	failures: PluginInitializationFailure[];
+	warnings: PluginInitializationWarning[];
+}
+
 interface PluginState {
 	plugin: PluginModule;
 	handlers: {
@@ -191,104 +214,153 @@ function getPlugin(pluginId: string): PluginState {
 async function initialize(args: {
 	pluginPaths?: string[];
 	exportName?: string;
-}): Promise<PluginDescriptor[]> {
+}): Promise<InitializeResult> {
 	pluginState.clear();
 	pluginCounter = 0;
 	contributionCounters.clear();
 
 	const descriptors: PluginDescriptor[] = [];
+	const failures: PluginInitializationFailure[] = [];
+	const warnings: PluginInitializationWarning[] = [];
 	const exportName = args.exportName || "plugin";
+	const pluginIndexByName = new Map<string, number>();
 
 	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: [],
-			messageBuilders: [],
-			providers: [],
-		};
-		const handlers: PluginState["handlers"] = {
-			tools: new Map(),
-			commands: new Map(),
-			messageBuilders: 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);
+		let plugin: PluginModule | undefined;
+		try {
+			const moduleExports = await importPluginModule(pluginPath);
+			plugin = (moduleExports.default ??
+				moduleExports[exportName]) as unknown as PluginModule;
+			assertValidPluginModule(plugin, pluginPath);
+
+			const pluginId = `plugin_${++pluginCounter}`;
+			const contributions: PluginDescriptor["contributions"] = {
+				tools: [],
+				commands: [],
+				shortcuts: [],
+				flags: [],
+				messageBuilders: [],
+				providers: [],
+			};
+			const handlers: PluginState["handlers"] = {
+				tools: new Map(),
+				commands: new Map(),
+				messageBuilders: 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,
+					});
+				},
+				registerMessageBuilder: (builder) => {
+					const id = makeId(pluginId, "builder");
+					handlers.messageBuilders.set(id, builder.build);
+					contributions.messageBuilders.push({ id, name: builder.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") {
+				try {
+					await plugin.setup(api);
+				} catch (error) {
+					failures.push({
+						pluginPath,
+						pluginName: plugin.name,
+						phase: "setup",
+						message: error instanceof Error ? error.message : String(error),
+						stack: error instanceof Error ? error.stack : undefined,
+					});
+					continue;
+				}
+			}
+
+			const previousIndex = pluginIndexByName.get(plugin.name);
+			if (previousIndex !== undefined) {
+				const previous = descriptors[previousIndex];
+				if (!previous) {
+					pluginIndexByName.delete(plugin.name);
+				} else {
+					warnings.push({
+						type: "duplicate_plugin_override",
+						pluginName: plugin.name,
+						pluginPath,
+						overriddenPluginPath: previous.pluginPath,
+						message: `Plugin "${plugin.name}" from ${pluginPath} overrides ${previous.pluginPath}`,
+					});
+					pluginState.delete(previous.pluginId);
+					descriptors.splice(previousIndex, 1);
+					pluginIndexByName.clear();
+					for (const [index, descriptor] of descriptors.entries()) {
+						pluginIndexByName.set(descriptor.name, index);
+					}
 				}
-				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,
-				});
-			},
-			registerMessageBuilder: (builder) => {
-				const id = makeId(pluginId, "builder");
-				handlers.messageBuilders.set(id, builder.build);
-				contributions.messageBuilders.push({ id, name: builder.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 });
+			pluginIndexByName.set(plugin.name, descriptors.length);
+			descriptors.push({
+				pluginId,
+				pluginPath,
+				name: plugin.name,
+				manifest: plugin.manifest,
+				contributions,
+			});
+		} catch (error) {
+			failures.push({
+				pluginPath,
+				pluginName: plugin?.name,
+				phase: "load",
+				message: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : undefined,
+			});
 		}
-
-		pluginState.set(pluginId, { plugin, handlers });
-		descriptors.push({
-			pluginId,
-			name: plugin.name,
-			manifest: plugin.manifest,
-			contributions,
-		});
 	}
 
-	return descriptors;
+	return { plugins: descriptors, failures, warnings };
 }
 
 async function invokeHook(args: {

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

@@ -184,6 +184,31 @@ describe("plugin-sandbox", () => {
 			"utf8",
 		);
 
+		await writeFile(
+			join(dir, "plugin-broken-setup.mjs"),
+			[
+				"export default {",
+				"  name: 'sandbox-broken-setup',",
+				"  manifest: { capabilities: ['tools'] },",
+				"  async setup() {",
+				"    throw new Error('broken setup');",
+				"  },",
+				"};",
+			].join("\n"),
+			"utf8",
+		);
+
+		await writeFile(
+			join(dir, "plugin-duplicate-a.mjs"),
+			"export default { name: 'sandbox-duplicate', manifest: { capabilities: ['tools'] } };",
+			"utf8",
+		);
+		await writeFile(
+			join(dir, "plugin-duplicate-b.mjs"),
+			"export default { name: 'sandbox-duplicate', manifest: { capabilities: ['commands'] } };",
+			"utf8",
+		);
+
 		sharedSandbox = await loadSandboxedPlugins({
 			pluginPaths: [
 				join(dir, "plugin.mjs"),
@@ -321,6 +346,51 @@ describe("plugin-sandbox", () => {
 		expect(result).toEqual({ echoed: "ok" });
 	});
 
+	it("continues loading remaining sandbox plugins when one setup fails", async () => {
+		const sandboxed = await loadSandboxedPlugins({
+			pluginPaths: [
+				join(dir, "plugin.mjs"),
+				join(dir, "plugin-broken-setup.mjs"),
+				join(dir, "plugin-events.mjs"),
+			],
+		});
+
+		try {
+			expect(sandboxed.extensions?.map((extension) => extension.name)).toEqual([
+				"sandbox-test",
+				"sandbox-events",
+			]);
+			expect(sandboxed.failures).toHaveLength(1);
+			expect(sandboxed.failures[0]?.pluginName).toBe("sandbox-broken-setup");
+			expect(sandboxed.failures[0]?.phase).toBe("setup");
+		} finally {
+			await sandboxed.shutdown();
+		}
+	});
+
+	it("keeps the later duplicate sandbox plugin and reports the override", async () => {
+		const sandboxed = await loadSandboxedPlugins({
+			pluginPaths: [
+				join(dir, "plugin-duplicate-a.mjs"),
+				join(dir, "plugin-duplicate-b.mjs"),
+			],
+		});
+
+		try {
+			expect(sandboxed.extensions).toHaveLength(1);
+			expect(sandboxed.extensions?.[0]?.name).toBe("sandbox-duplicate");
+			expect(sandboxed.extensions?.[0]?.manifest.capabilities).toEqual([
+				"commands",
+			]);
+			expect(sandboxed.warnings).toHaveLength(1);
+			expect(sandboxed.warnings[0]?.overriddenPluginPath).toBe(
+				join(dir, "plugin-duplicate-a.mjs"),
+			);
+		} finally {
+			await sandboxed.shutdown();
+		}
+	});
+
 	it("resolves plugin-local dependencies in the sandbox process", async () => {
 		expect(sharedExtensions.get("sandbox-local-dep")?.name).toBe(
 			"sandbox-local-dep",