@clinebot/core 0.0.32 → 0.0.34

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/context/agentic-compaction.ts

@@ -106,14 +106,26 @@ export async function runAgenticCompaction(options: {
 		(total, message) => total + options.estimateMessageTokens(message),
 		0,
 	);
-	return {
-		messages: [
-			buildSummaryMessage({
-				summary,
-				fileOps,
-				tokensBefore,
-			}),
-			...messages.slice(cutIndex),
-		],
-	};
+	const resultMessages = [
+		buildSummaryMessage({
+			summary,
+			fileOps,
+			tokensBefore,
+		}),
+		...messages.slice(cutIndex),
+	];
+	const tokensAfter = resultMessages.reduce(
+		(total, message) => total + options.estimateMessageTokens(message),
+		0,
+	);
+	options.logger?.debug("Performed agentic compaction", {
+		messagesBefore: messages.length,
+		messagesAfter: resultMessages.length,
+		messagesSummarized: cutIndex,
+		messagesPreserved: messages.length - cutIndex,
+		tokensBefore,
+		tokensAfter,
+		contextWindowTokens: options.context.contextWindowTokens,
+	});
+	return { messages: resultMessages };
 }

package/src/extensions/context/basic-compaction.ts

@@ -33,17 +33,19 @@ function sanitizeMessageForBasic(
 		return text ? { ...message, content: text } : undefined;
 	}
 
-	const textParts: string[] = [];
-	for (const block of message.content) {
-		if (block.type === "text") {
-			const text = block.text.trim();
-			if (text) {
-				textParts.push(text);
-			}
-		}
+	// Preserve array structure: keep only text blocks with non-empty content.
+	const kept = message.content.filter(
+		(block) => block.type === "text" && block.text.trim(),
+	);
+	if (kept.length === 0) {
+		return undefined;
 	}
-	const text = textParts.join("\n\n").trim();
-	return text ? { ...message, content: text } : undefined;
+	return {
+		...message,
+		content: kept.map((block) =>
+			block.type === "text" ? { ...block, text: block.text.trim() } : block,
+		),
+	};
 }
 
 function getTotalTokens(
@@ -60,14 +62,25 @@ function truncateMessageToTokens(
 	message: MessageWithMetadata,
 	maxTokens: number,
 ): MessageWithMetadata {
-	const content = typeof message.content === "string" ? message.content : "";
 	const safeMaxTokens = Math.max(1, maxTokens);
 	const targetChars = Math.max(16, safeMaxTokens * 4);
-	const truncated = truncateText(content, targetChars).trim();
-	return {
-		...message,
-		content: truncated || "...",
-	};
+
+	if (typeof message.content === "string") {
+		const truncated = truncateText(message.content, targetChars).trim();
+		return { ...message, content: truncated || "..." };
+	}
+
+	// Preserve content block array structure while truncating text blocks.
+	let remaining = targetChars;
+	const truncatedBlocks = message.content.map((block) => {
+		if (block.type !== "text" || remaining <= 0) {
+			return block;
+		}
+		const truncated = truncateText(block.text, remaining).trim();
+		remaining -= truncated.length;
+		return { ...block, text: truncated || "..." };
+	});
+	return { ...message, content: truncatedBlocks };
 }
 
 function buildBasicCandidates(
@@ -265,10 +278,22 @@ export function runBasicCompaction(options: {
 		return undefined;
 	}
 
+	const beforeTokens = getTotalTokens(
+		options.context.messages.map((m) => sanitizeMessageForBasic(m) ?? m),
+		options.estimateMessageTokens,
+	);
+	const afterTokens = getTotalTokens(
+		nextMessages,
+		options.estimateMessageTokens,
+	);
 	options.logger?.debug("Performed basic compaction", {
-		beforeCount: options.context.messages.length,
-		afterCount: nextMessages.length,
+		messagesBefore: options.context.messages.length,
+		messagesAfter: nextMessages.length,
+		messagesRemoved: options.context.messages.length - nextMessages.length,
+		tokensBefore: beforeTokens,
+		tokensAfter: afterTokens,
 		targetTokens,
+		contextWindowTokens: options.context.contextWindowTokens,
 	});
 
 	return { messages: nextMessages };

package/src/extensions/context/compaction-shared.ts

@@ -6,7 +6,7 @@ import type {
 } from "../../types/config";
 
 export const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
-export const DEFAULT_THRESHOLD_RATIO = 0.8;
+export const DEFAULT_THRESHOLD_RATIO = 0.95;
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_PRESERVE_RECENT_TOKENS = 20_000;
 export const DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS = 1_024;

package/src/extensions/context/compaction.test.ts

@@ -363,16 +363,22 @@ describe("createContextCompactionPrepareTurn", () => {
 		);
 		expect(result?.messages).toBeDefined();
 		expect(result?.messages.length).toBeGreaterThan(0);
-		expect(
-			result?.messages.every((message) => typeof message.content === "string"),
-		).toBe(true);
-		expect(
-			result?.messages.some((message) =>
-				typeof message.content === "string"
-					? message.content.includes("tool output that should be removed")
-					: false,
-			),
-		).toBe(false);
+		// Compacted messages should not contain tool_result content that was pruned.
+		for (const message of result?.messages ?? []) {
+			if (typeof message.content === "string") {
+				expect(message.content).not.toContain(
+					"tool output that should be removed",
+				);
+			} else {
+				for (const block of message.content) {
+					if (block.type === "text") {
+						expect(block.text).not.toContain(
+							"tool output that should be removed",
+						);
+					}
+				}
+			}
+		}
 	});
 
 	it("defaults to threshold ratio when reserveTokens is not configured", async () => {

package/src/extensions/context/compaction.ts

@@ -185,19 +185,42 @@ export function createContextCompactionPrepareTurn(
 			contextWindowTokens,
 		});
 
-		if (userCompaction?.compact) {
-			return await userCompaction.compact(compactionContext);
+		const beforeMessageCount = context.messages.length;
+
+		const result = userCompaction?.compact
+			? await userCompaction.compact(compactionContext)
+			: await runBuiltinStrategy({
+					context: compactionContext,
+					providerConfig: {
+						...providerConfig,
+						abortSignal: context.abortSignal,
+					},
+					compaction: userCompaction,
+					estimateMessageTokens,
+					logger: config.logger,
+				});
+
+		if (result?.messages) {
+			const afterTokens = result.messages.reduce(
+				(total: number, message) => total + estimateMessageTokens(message),
+				0,
+			);
+			config.logger?.log("Context compaction completed", {
+				severity: "info",
+				strategy: strategy,
+				contextWindowTokens,
+				inputTokens,
+				afterTokens,
+				tokensSaved: inputTokens - afterTokens,
+				utilizationBefore: `${((inputTokens / contextWindowTokens) * 100).toFixed(1)}%`,
+				utilizationAfter: `${((afterTokens / contextWindowTokens) * 100).toFixed(1)}%`,
+				thresholdTrigger: `${(triggerState.thresholdRatio * 100).toFixed(1)}%`,
+				messagesBefore: beforeMessageCount,
+				messagesAfter: result.messages.length,
+				messagesRemoved: beforeMessageCount - result.messages.length,
+			} as Record<string, unknown>);
 		}
 
-		return await runBuiltinStrategy({
-			context: compactionContext,
-			providerConfig: {
-				...providerConfig,
-				abortSignal: context.abortSignal,
-			},
-			compaction: userCompaction,
-			estimateMessageTokens,
-			logger: config.logger,
-		});
+		return result;
 	};
 }

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,
+	};
 }