@clinebot/core 0.0.33 → 0.0.35

package/src/auth/cline.ts

@@ -5,7 +5,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { startLocalOAuthServer } from "./server";
 import type {
 	OAuthCredentials,
@@ -457,6 +457,8 @@ export async function loginClineOAuth(
 		: await startLocalOAuthServer({
 				ports: callbackPorts,
 				callbackPath,
+				onListening: options.callbacks.onServerListening,
+				onClose: options.callbacks.onServerClose,
 			});
 	const callbackUrl =
 		localServer?.callbackUrl ||

package/src/auth/codex.ts

@@ -13,7 +13,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { startLocalOAuthServer } from "./server";
 import type {
 	OAuthCredentials,

package/src/auth/oca.ts

@@ -6,7 +6,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { BoundedTtlCache } from "./bounded-ttl-cache";
 import { startLocalOAuthServer } from "./server";
 import type {
@@ -363,6 +363,8 @@ export async function loginOcaOAuth(
 	const localServer = await startLocalOAuthServer({
 		ports: callbackPorts,
 		callbackPath,
+		onListening: options.callbacks.onServerListening,
+		onClose: options.callbacks.onServerClose,
 	});
 	const callbackUrl = localServer.callbackUrl;
 	if (!callbackUrl) {

package/src/auth/server.test.ts

@@ -0,0 +1,287 @@
+import http from "node:http";
+import net from "node:net";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startLocalOAuthServer } from "./server";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Bind to port 0 to let the OS pick a free port, then release it. */
+function getFreePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const srv = net.createServer();
+		srv.listen(0, "127.0.0.1", () => {
+			const addr = srv.address() as net.AddressInfo;
+			srv.close(() => resolve(addr.port));
+		});
+		srv.on("error", reject);
+	});
+}
+
+/** Occupy a port so the OAuth server cannot bind to it. */
+function occupyPort(port: number): Promise<http.Server> {
+	return new Promise((resolve, reject) => {
+		const srv = http.createServer();
+		srv.listen(port, "127.0.0.1", () => resolve(srv));
+		srv.on("error", reject);
+	});
+}
+
+/** Close an http.Server, resolving when the socket is gone. */
+function closeServer(srv: http.Server): Promise<void> {
+	return new Promise((resolve, reject) =>
+		srv.close((err) => (err ? reject(err) : resolve())),
+	);
+}
+
+/** Make a GET request and return status + body. */
+function get(url: string): Promise<{ status: number; body: string }> {
+	return new Promise((resolve, reject) => {
+		http
+			.get(url, (res) => {
+				let body = "";
+				res.on("data", (chunk: Buffer) => {
+					body += chunk.toString();
+				});
+				res.on("end", () => resolve({ status: res.statusCode ?? 0, body }));
+			})
+			.on("error", reject);
+	});
+}
+
+/** Flush microtasks + a short macro-task delay for fire-and-forget promises. */
+function flushAsync(): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+// ---------------------------------------------------------------------------
+// onListening
+// ---------------------------------------------------------------------------
+
+describe("auth/server startLocalOAuthServer — onListening", () => {
+	it("is called with host, port, and callbackUrl when the server binds", async () => {
+		const port = await getFreePort();
+		const onListening = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onListening,
+		});
+
+		expect(onListening).toHaveBeenCalledOnce();
+		expect(onListening).toHaveBeenCalledWith({
+			host: "127.0.0.1",
+			port,
+			callbackUrl: `http://127.0.0.1:${port}/callback`,
+		});
+
+		server.close();
+	});
+
+	it("is not called when no port can be bound", async () => {
+		const port = await getFreePort();
+		const blocker = await occupyPort(port);
+		const onListening = vi.fn();
+
+		await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onListening,
+		});
+
+		expect(onListening).not.toHaveBeenCalled();
+
+		await closeServer(blocker);
+	});
+
+	it("fires for the first available port and skips occupied ones", async () => {
+		const [port1, port2] = await Promise.all([getFreePort(), getFreePort()]);
+		const blocker = await occupyPort(port1);
+		const onListening = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port1, port2],
+			callbackPath: "/cb",
+			onListening,
+		});
+
+		expect(onListening).toHaveBeenCalledOnce();
+		expect(onListening).toHaveBeenCalledWith(
+			expect.objectContaining({ port: port2 }),
+		);
+
+		server.close();
+		await closeServer(blocker);
+	});
+
+	it("swallows errors thrown by the onListening callback", async () => {
+		const port = await getFreePort();
+		const onListening = vi
+			.fn()
+			.mockReturnValue(Promise.reject(new Error("listening boom")));
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onListening,
+		});
+
+		await flushAsync();
+		expect(onListening).toHaveBeenCalledOnce();
+
+		server.close();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// onClose
+// ---------------------------------------------------------------------------
+
+describe("auth/server startLocalOAuthServer — onClose", () => {
+	it("is called with host and port when close() is invoked", async () => {
+		const port = await getFreePort();
+		const onClose = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onClose,
+		});
+
+		server.close();
+
+		expect(onClose).toHaveBeenCalledOnce();
+		expect(onClose).toHaveBeenCalledWith({ host: "127.0.0.1", port });
+	});
+
+	it("is called with host and port when cancelWait() is invoked", async () => {
+		const port = await getFreePort();
+		const onClose = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onClose,
+		});
+
+		server.cancelWait();
+
+		expect(onClose).toHaveBeenCalledOnce();
+		expect(onClose).toHaveBeenCalledWith({ host: "127.0.0.1", port });
+	});
+
+	it("is called after a successful OAuth callback request", async () => {
+		const port = await getFreePort();
+		const onClose = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onClose,
+		});
+
+		const waitPromise = server.waitForCallback();
+		const { status } = await get(
+			`http://127.0.0.1:${port}/callback?code=tok123`,
+		);
+		expect(status).toBe(200);
+
+		await waitPromise;
+
+		expect(onClose).toHaveBeenCalledOnce();
+		expect(onClose).toHaveBeenCalledWith({ host: "127.0.0.1", port });
+	});
+
+	it("is not called when no port was bound", async () => {
+		const port = await getFreePort();
+		const blocker = await occupyPort(port);
+		const onClose = vi.fn();
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onClose,
+		});
+
+		server.close();
+		expect(onClose).not.toHaveBeenCalled();
+
+		await closeServer(blocker);
+	});
+
+	it("swallows errors thrown by the onClose callback", async () => {
+		const port = await getFreePort();
+		const onClose = vi
+			.fn()
+			.mockReturnValue(Promise.reject(new Error("teardown failed")));
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/callback",
+			onClose,
+		});
+
+		server.close();
+		await flushAsync();
+
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// onListening + onClose ordering
+// ---------------------------------------------------------------------------
+
+describe("auth/server startLocalOAuthServer — onListening + onClose together", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("fires onListening on bind then onClose after a successful callback", async () => {
+		const port = await getFreePort();
+		const order: string[] = [];
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/cb",
+			onListening: vi.fn(() => {
+				order.push("listening");
+			}),
+			onClose: vi.fn(() => {
+				order.push("close");
+			}),
+		});
+
+		expect(order).toEqual(["listening"]);
+
+		const waitPromise = server.waitForCallback();
+		await get(`http://127.0.0.1:${port}/cb?code=mycode`);
+		const payload = await waitPromise;
+
+		expect(payload?.code).toBe("mycode");
+		expect(order).toEqual(["listening", "close"]);
+	});
+
+	it("fires onListening on bind then onClose after cancelWait()", async () => {
+		const port = await getFreePort();
+		const order: string[] = [];
+
+		const server = await startLocalOAuthServer({
+			ports: [port],
+			callbackPath: "/cb",
+			onListening: vi.fn(() => {
+				order.push("listening");
+			}),
+			onClose: vi.fn(() => {
+				order.push("close");
+			}),
+		});
+
+		expect(order).toEqual(["listening"]);
+
+		server.cancelWait();
+		expect(order).toEqual(["listening", "close"]);
+	});
+});

package/src/auth/server.ts

@@ -19,6 +19,17 @@ function createDeferred<T>(): Deferred<T> {
 	return { promise, resolve };
 }
 
+export interface OAuthServerListeningInfo {
+	host: string;
+	port: number;
+	callbackUrl: string;
+}
+
+export interface OAuthServerCloseInfo {
+	host: string;
+	port: number;
+}
+
 export interface LocalOAuthServerOptions {
 	host?: string;
 	ports: number[];
@@ -26,6 +37,29 @@ export interface LocalOAuthServerOptions {
 	timeoutMs?: number;
 	expectedState?: string;
 	successHtml?: string;
+	/**
+	 * Called when the local redirect server successfully binds to a port and is
+	 * ready to receive the OAuth callback. Hosts can use this to display a
+	 * "waiting for callback" status indicator or — in remote-development
+	 * environments like JetBrains Gateway — to forward the port from the remote
+	 * machine to the local machine where the user's browser is running.
+	 *
+	 * May be async; `startLocalOAuthServer` will **await** this callback before
+	 * returning so that any setup it performs (e.g. port-forwarding) is
+	 * guaranteed to complete before the caller opens the auth URL. Errors
+	 * thrown by this callback are swallowed — they do not prevent the OAuth
+	 * flow from proceeding.
+	 */
+	onListening?: (info: OAuthServerListeningInfo) => void | Promise<void>;
+	/**
+	 * Called when the local redirect server closes, either because the OAuth
+	 * callback was received, the flow was cancelled, or the timeout elapsed.
+	 * Hosts should use this to tear down any port-forward set up in
+	 * `onListening` and clear any "waiting for callback" status UI.
+	 *
+	 * May be async; fired after the underlying server socket is closed.
+	 */
+	onClose?: (info: OAuthServerCloseInfo) => void | Promise<void>;
 }
 
 export interface LocalOAuthServer {
@@ -48,6 +82,7 @@ export async function startLocalOAuthServer(
 	let settled = false;
 	let timeout: ReturnType<typeof setTimeout> | null = null;
 	let activeServer: import("node:http").Server | null = null;
+	let boundPort: number | null = null;
 
 	const settle = (value: OAuthCallbackPayload | null) => {
 		if (settled) return;
@@ -60,10 +95,17 @@ export async function startLocalOAuthServer(
 			clearTimeout(timeout);
 			timeout = null;
 		}
+		const closingPort = boundPort;
+		boundPort = null;
 		if (activeServer) {
 			activeServer.close();
 			activeServer = null;
 		}
+		if (closingPort !== null && options.onClose) {
+			void Promise.resolve(options.onClose({ host, port: closingPort })).catch(
+				() => {},
+			);
+		}
 	};
 
 	const waitForCallback = async () => {
@@ -149,8 +191,15 @@ export async function startLocalOAuthServer(
 		}
 
 		if (bindResult.bound) {
+			boundPort = port;
+			const callbackUrl = `http://${host}:${port}${options.callbackPath}`;
+			if (options.onListening) {
+				await Promise.resolve(
+					options.onListening({ host, port, callbackUrl }),
+				).catch(() => {});
+			}
 			return {
-				callbackUrl: `http://${host}:${port}${options.callbackPath}`,
+				callbackUrl,
 				waitForCallback,
 				cancelWait: () => {
 					close();

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/config/agent-config-loader.test.ts

@@ -2,6 +2,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Tool, ToolContext } from "@clinebot/shared";
+import { resolveDocumentsExtensionPath } from "@clinebot/shared/storage";
 import { afterEach, describe, expect, it } from "vitest";
 import {
 	AGENT_CONFIG_DIRECTORY_NAME,
@@ -12,7 +13,6 @@ import {
 	resolveAgentConfigSearchPaths,
 	resolveAgentsConfigDirPath,
 	resolveAgentTools,
-	resolveDocumentsAgentConfigDirectoryPath,
 	toPartialAgentConfig,
 } from "./agent-config-loader";
 
@@ -46,7 +46,7 @@ describe("agent config YAML loader", () => {
 	it("includes documents and settings search paths", () => {
 		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
 		expect(resolveAgentConfigSearchPaths()).toEqual([
-			resolveDocumentsAgentConfigDirectoryPath(),
+			resolveDocumentsExtensionPath("Agents"),
 			join("/tmp/cline-data", "settings", AGENT_CONFIG_DIRECTORY_NAME),
 		]);
 	});
@@ -56,7 +56,7 @@ describe("agent config YAML loader", () => {
 		const definition = createAgentConfigDefinition();
 		expect(definition.type).toBe("agent");
 		expect(definition.directories).toEqual([
-			resolveDocumentsAgentConfigDirectoryPath(),
+			resolveDocumentsExtensionPath("Agents"),
 			join("/tmp/cline-data", "settings", AGENT_CONFIG_DIRECTORY_NAME),
 		]);
 		expect(definition.includeFile?.("agent.yaml", "/tmp/agent.yaml")).toBe(

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

@@ -2,7 +2,6 @@ import {
 	AGENT_CONFIG_DIRECTORY_NAME,
 	resolveAgentConfigSearchPaths as resolveAgentConfigSearchPathsFromShared,
 	resolveAgentsConfigDirPath as resolveAgentsConfigDirPathFromShared,
-	resolveDocumentsAgentConfigDirectoryPath,
 } from "@clinebot/shared/storage";
 import {
 	type AgentYamlConfig,
@@ -38,10 +37,7 @@ export type AgentConfigWatcherEvent = UnifiedConfigWatcherEvent<
 	AgentYamlConfig
 >;
 
-export {
-	AGENT_CONFIG_DIRECTORY_NAME,
-	resolveDocumentsAgentConfigDirectoryPath,
-};
+export { AGENT_CONFIG_DIRECTORY_NAME };
 
 export function resolveAgentsConfigDirPath(): string {
 	return resolveAgentsConfigDirPathFromShared();

package/src/extensions/config/agent-config-parser.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig, Tool } from "@clinebot/shared";
 import YAML from "yaml";
 import { z } from "zod";
-import { ALL_DEFAULT_TOOL_NAMES, type DefaultToolName } from "../../tools";
+import { ALL_DEFAULT_TOOL_NAMES, type DefaultToolName } from "../tools/";
 
 const AgentConfigFrontmatterSchema = z.object({
 	name: z.string().trim().min(1),

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

@@ -2,12 +2,11 @@ import { existsSync, readdirSync } from "node:fs";
 import { basename, extname, join } from "node:path";
 import {
 	HOOKS_CONFIG_DIRECTORY_NAME,
-	resolveDocumentsHooksDirectoryPath,
 	resolveHooksConfigSearchPaths as resolveHooksConfigSearchPathsFromShared,
 } from "@clinebot/shared/storage";
 import type { HookEventName } from "../../hooks";
 
-export { HOOKS_CONFIG_DIRECTORY_NAME, resolveDocumentsHooksDirectoryPath };
+export { HOOKS_CONFIG_DIRECTORY_NAME };
 
 export function resolveHooksConfigSearchPaths(
 	workspacePath?: string,

package/src/extensions/config/index.ts

@@ -17,7 +17,6 @@ export {
 	resolveAgentConfigSearchPaths,
 	resolveAgentsConfigDirPath,
 	resolveAgentTools,
-	resolveDocumentsAgentConfigDirectoryPath,
 	toPartialAgentConfig,
 } from "./agent-config-loader";
 export {
@@ -26,7 +25,6 @@ export {
 	type HookConfigFileEntry,
 	HookConfigFileName,
 	listHookConfigFiles,
-	resolveDocumentsHooksDirectoryPath,
 	resolveHooksConfigSearchPaths,
 	toHookConfigFileName,
 } from "./hooks-config-loader";
@@ -71,8 +69,6 @@ export {
 	parseSkillConfigFromMarkdown,
 	parseWorkflowConfigFromMarkdown,
 	RULES_CONFIG_DIRECTORY_NAME,
-	resolveDocumentsRulesDirectoryPath,
-	resolveDocumentsWorkflowsDirectoryPath,
 	resolveRulesConfigSearchPaths,
 	resolveSkillsConfigSearchPaths,
 	resolveWorkflowsConfigSearchPaths,

package/src/extensions/config/user-instruction-config-loader.ts

@@ -2,8 +2,6 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import {
 	RULES_CONFIG_DIRECTORY_NAME,
-	resolveDocumentsRulesDirectoryPath,
-	resolveDocumentsWorkflowsDirectoryPath,
 	resolveRulesConfigSearchPaths as resolveRulesConfigSearchPathsFromShared,
 	resolveSkillsConfigSearchPaths as resolveSkillsConfigSearchPathsFromShared,
 	resolveWorkflowsConfigSearchPaths as resolveWorkflowsConfigSearchPathsFromShared,
@@ -25,8 +23,6 @@ const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
 
 export {
 	RULES_CONFIG_DIRECTORY_NAME,
-	resolveDocumentsRulesDirectoryPath,
-	resolveDocumentsWorkflowsDirectoryPath,
 	SKILLS_CONFIG_DIRECTORY_NAME,
 	WORKFLOWS_CONFIG_DIRECTORY_NAME,
 };

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,42 @@ 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,
+			});
+
+			// Filter to only our test plugins to ignore any discovered system plugins
+			const testPlugins = loaded.extensions.filter(
+				(plugin) => plugin.name === "duplicate-plugin",
+			);
+			expect(testPlugins).toHaveLength(1);
+			expect(testPlugins[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 });
+		}
+	});
 });