@clinebot/core 0.0.7 → 0.0.10

package/src/session/runtime-oauth-token-manager.ts

@@ -1,4 +1,9 @@
-import type { providers as LlmsProviders } from "@clinebot/llms";
+import type { LlmsProviders } from "@clinebot/llms";
+import {
+	type ITelemetryService,
+	isOAuthProviderId,
+	type OAuthProviderId,
+} from "@clinebot/shared";
 import {
 	type ClineOAuthCredentials,
 	getValidClineCredentials,
@@ -11,14 +16,7 @@ import { ProviderSettingsManager } from "../storage/provider-settings-manager";
 const DEFAULT_CLINE_API_BASE_URL = "https://api.cline.bot";
 const WORKOS_TOKEN_PREFIX = "workos:";
 
-const MANAGED_OAUTH_PROVIDERS = ["cline", "oca", "openai-codex"] as const;
-type ManagedOAuthProviderId = (typeof MANAGED_OAUTH_PROVIDERS)[number];
-
-function isManagedOAuthProviderId(
-	providerId: string,
-): providerId is ManagedOAuthProviderId {
-	return (MANAGED_OAUTH_PROVIDERS as readonly string[]).includes(providerId);
-}
+type ManagedOAuthProviderId = OAuthProviderId;
 
 function toStoredAccessToken(
 	providerId: ManagedOAuthProviderId,
@@ -143,21 +141,26 @@ export type RuntimeOAuthResolution = {
 
 export class RuntimeOAuthTokenManager {
 	private readonly providerSettingsManager: ProviderSettingsManager;
+	private readonly telemetry?: ITelemetryService;
 	private readonly refreshInFlight = new Map<
 		ManagedOAuthProviderId,
 		Promise<RuntimeOAuthResolution | null>
 	>();
 
-	constructor(options?: { providerSettingsManager?: ProviderSettingsManager }) {
+	constructor(options?: {
+		providerSettingsManager?: ProviderSettingsManager;
+		telemetry?: ITelemetryService;
+	}) {
 		this.providerSettingsManager =
 			options?.providerSettingsManager ?? new ProviderSettingsManager();
+		this.telemetry = options?.telemetry;
 	}
 
 	public async resolveProviderApiKey(input: {
 		providerId: string;
 		forceRefresh?: boolean;
 	}): Promise<RuntimeOAuthResolution | null> {
-		if (!isManagedOAuthProviderId(input.providerId)) {
+		if (!isOAuthProviderId(input.providerId)) {
 			return null;
 		}
 		return this.resolveWithSingleFlight(input.providerId, input.forceRefresh);
@@ -249,6 +252,7 @@ export class RuntimeOAuthTokenManager {
 				currentCredentials,
 				{
 					apiBaseUrl: settings.baseUrl?.trim() || DEFAULT_CLINE_API_BASE_URL,
+					telemetry: this.telemetry,
 				},
 				{ forceRefresh },
 			);
@@ -256,10 +260,13 @@ export class RuntimeOAuthTokenManager {
 		if (providerId === "oca") {
 			return getValidOcaCredentials(
 				currentCredentials,
-				{ forceRefresh },
-				{ mode: settings.oca?.mode },
+				{ forceRefresh, telemetry: this.telemetry },
+				{ mode: settings.oca?.mode, telemetry: this.telemetry },
 			);
 		}
-		return getValidOpenAICodexCredentials(currentCredentials, { forceRefresh });
+		return getValidOpenAICodexCredentials(currentCredentials, {
+			forceRefresh,
+			telemetry: this.telemetry,
+		});
 	}
 }

package/src/session/session-agent-events.ts

@@ -0,0 +1,159 @@
+import type { AgentEvent } from "@clinebot/agents";
+import {
+	captureConversationTurnEvent,
+	captureDiffEditFailure,
+	captureProviderApiError,
+	captureSkillUsed,
+	captureTokenUsage,
+	captureToolUsage,
+} from "../telemetry/core-events";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { SessionAccumulatedUsage } from "./session-manager";
+import { serializeAgentEvent } from "./utils/helpers";
+import type { ActiveSession } from "./utils/types";
+import { accumulateUsageTotals } from "./utils/usage";
+
+export function extractSkillNameFromToolInput(
+	input: unknown,
+): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	const skillName = record.skill ?? record.skill_name ?? record.skillName;
+	if (typeof skillName !== "string") return undefined;
+	const trimmed = skillName.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export interface AgentEventContext {
+	sessionId: string;
+	config: CoreSessionConfig;
+	liveSession: ActiveSession | undefined;
+	usageBySession: Map<string, SessionAccumulatedUsage>;
+	persistMessages: (
+		sessionId: string,
+		messages: unknown[],
+		systemPrompt?: string,
+	) => void;
+	emit: (event: CoreSessionEvent) => void;
+}
+
+export function handleAgentEvent(
+	ctx: AgentEventContext,
+	event: AgentEvent,
+): void {
+	const { sessionId, config, liveSession, emit } = ctx;
+	const telemetry = config.telemetry;
+
+	if (
+		event.type === "content_start" &&
+		event.contentType === "tool" &&
+		event.toolName === "skills"
+	) {
+		const skillName = extractSkillNameFromToolInput(event.input);
+		if (skillName) {
+			captureSkillUsed(telemetry, {
+				ulid: sessionId,
+				skillName,
+				skillSource: "project",
+				skillsAvailableGlobal: 0,
+				skillsAvailableProject: 0,
+				provider: config.providerId,
+				modelId: config.modelId,
+			});
+		}
+	}
+
+	if (event.type === "content_end" && event.contentType === "tool") {
+		const toolName = event.toolName ?? "unknown";
+		const success = !event.error;
+		captureToolUsage(telemetry, {
+			ulid: sessionId,
+			tool: toolName,
+			autoApproved: undefined,
+			success,
+			modelId: config.modelId,
+			provider: config.providerId,
+			isNativeToolCall: false,
+		});
+		if (!success && (toolName === "editor" || toolName === "apply_patch")) {
+			captureDiffEditFailure(telemetry, {
+				ulid: sessionId,
+				modelId: config.modelId,
+				provider: config.providerId,
+				errorType: event.error,
+				isNativeToolCall: false,
+			});
+		}
+	}
+
+	if (event.type === "notice" && event.reason === "api_error") {
+		captureProviderApiError(telemetry, {
+			ulid: sessionId,
+			model: config.modelId,
+			provider: config.providerId,
+			errorMessage: event.message,
+		});
+	}
+
+	if (event.type === "error") {
+		captureProviderApiError(telemetry, {
+			ulid: sessionId,
+			model: config.modelId,
+			provider: config.providerId,
+			errorMessage: event.error?.message ?? "unknown error",
+		});
+	}
+
+	if (event.type === "usage" && liveSession?.turnUsageBaseline) {
+		ctx.usageBySession.set(
+			sessionId,
+			accumulateUsageTotals(liveSession.turnUsageBaseline, {
+				inputTokens: event.totalInputTokens,
+				outputTokens: event.totalOutputTokens,
+				totalCost: event.totalCost,
+			}),
+		);
+		captureConversationTurnEvent(telemetry, {
+			ulid: sessionId,
+			provider: config.providerId,
+			model: config.modelId,
+			source: "assistant",
+			mode: config.mode,
+			tokensIn: event.inputTokens,
+			tokensOut: event.outputTokens,
+			cacheWriteTokens: event.cacheWriteTokens,
+			cacheReadTokens: event.cacheReadTokens,
+			totalCost: event.cost,
+			isNativeToolCall: false,
+		});
+		captureTokenUsage(telemetry, {
+			ulid: sessionId,
+			tokensIn: event.inputTokens,
+			tokensOut: event.outputTokens,
+			model: config.modelId,
+		});
+	}
+
+	if (event.type === "iteration_end") {
+		ctx.persistMessages(
+			sessionId,
+			liveSession?.agent.getMessages() ?? [],
+			liveSession?.config.systemPrompt,
+		);
+	}
+
+	emit({
+		type: "agent_event",
+		payload: { sessionId, event },
+	});
+	emit({
+		type: "chunk",
+		payload: {
+			sessionId,
+			stream: "agent",
+			chunk: serializeAgentEvent(event),
+			ts: Date.now(),
+		},
+	});
+}

package/src/session/session-config-builder.ts

@@ -0,0 +1,111 @@
+import type { LlmsProviders } from "@clinebot/llms";
+import type { ITelemetryService } from "@clinebot/shared";
+import { resolveAndLoadAgentPlugins } from "../agents/plugin-config-loader";
+import {
+	createHookAuditHooks,
+	createHookConfigFileHooks,
+	mergeAgentHooks,
+} from "../runtime/hook-file-hooks";
+import type { ProviderSettingsManager } from "../storage/provider-settings-manager";
+import type { CoreSessionConfig } from "../types/config";
+import {
+	type ProviderSettings,
+	toProviderConfig,
+} from "../types/provider-settings";
+import type { StartSessionInput } from "./session-manager";
+import { hasRuntimeHooks, mergeAgentExtensions } from "./utils/helpers";
+
+export function resolveWorkspacePath(config: CoreSessionConfig): string {
+	return config.workspaceRoot ?? config.cwd;
+}
+
+export async function buildEffectiveConfig(
+	input: StartSessionInput,
+	hookPath: string,
+	sessionId: string,
+	defaultTelemetry: ITelemetryService | undefined,
+): Promise<{
+	config: CoreSessionConfig;
+	pluginSandboxShutdown?: () => Promise<void>;
+}> {
+	const workspacePath = resolveWorkspacePath(input.config);
+
+	const fileHooks = createHookConfigFileHooks({
+		cwd: input.config.cwd,
+		workspacePath,
+		rootSessionId: sessionId,
+		hookLogPath: hookPath,
+		logger: input.config.logger,
+	});
+	const auditHooks = hasRuntimeHooks(input.config.hooks)
+		? undefined
+		: createHookAuditHooks({
+				hookLogPath: hookPath,
+				rootSessionId: sessionId,
+				workspacePath,
+			});
+	const effectiveHooks = mergeAgentHooks([
+		input.config.hooks,
+		fileHooks,
+		auditHooks,
+	]);
+
+	const loadedPlugins = await resolveAndLoadAgentPlugins({
+		pluginPaths: input.config.pluginPaths,
+		workspacePath,
+		cwd: input.config.cwd,
+	});
+	const effectiveExtensions = mergeAgentExtensions(
+		input.config.extensions,
+		loadedPlugins.extensions,
+	);
+
+	return {
+		config: {
+			...input.config,
+			hooks: effectiveHooks,
+			extensions: effectiveExtensions,
+			telemetry: input.config.telemetry ?? defaultTelemetry,
+		},
+		pluginSandboxShutdown: loadedPlugins.shutdown,
+	};
+}
+
+export function buildResolvedProviderConfig(
+	config: CoreSessionConfig,
+	providerSettingsManager: ProviderSettingsManager,
+	resolveReasoningFn: (
+		config: CoreSessionConfig,
+		storedReasoning: ProviderSettings["reasoning"],
+	) => ProviderSettings["reasoning"],
+): LlmsProviders.ProviderConfig {
+	const stored = providerSettingsManager.getProviderSettings(config.providerId);
+	const settings: ProviderSettings = {
+		...(stored ?? {}),
+		provider: config.providerId,
+		model: config.modelId,
+		apiKey: config.apiKey ?? stored?.apiKey,
+		baseUrl: config.baseUrl ?? stored?.baseUrl,
+		headers: config.headers ?? stored?.headers,
+		reasoning: resolveReasoningFn(config, stored?.reasoning),
+	};
+	const providerConfig = toProviderConfig(settings);
+	if (config.knownModels) {
+		providerConfig.knownModels = config.knownModels;
+	}
+	return providerConfig;
+}
+
+export function resolveReasoningSettings(
+	config: CoreSessionConfig,
+	storedReasoning: ProviderSettings["reasoning"],
+): ProviderSettings["reasoning"] {
+	const hasThinking = typeof config.thinking === "boolean";
+	const hasEffort = typeof config.reasoningEffort === "string";
+	if (!hasThinking && !hasEffort) return storedReasoning;
+	return {
+		...(storedReasoning ?? {}),
+		...(hasThinking ? { enabled: config.thinking } : {}),
+		...(hasEffort ? { effort: config.reasoningEffort } : {}),
+	};
+}

package/src/session/session-host.ts

@@ -44,6 +44,15 @@ export interface CreateSessionHostOptions {
 
 export type SessionHost = SessionManager;
 
+async function reconcileDeadSessionsIfSupported(
+	backend: SessionBackend,
+): Promise<void> {
+	const service = backend as SessionBackend & {
+		reconcileDeadSessions?: (limit?: number) => Promise<number>;
+	};
+	await service.reconcileDeadSessions?.().catch(() => {});
+}
+
 function startRpcServerInBackground(address: string): void {
 	const lease = tryAcquireRpcSpawnLease(address);
 	if (!lease) {
@@ -156,12 +165,14 @@ export async function resolveSessionBackend(
 	backendInitPromise = (async () => {
 		if (mode === "local") {
 			cachedBackend = createLocalBackend();
+			await reconcileDeadSessionsIfSupported(cachedBackend);
 			return cachedBackend;
 		}
 
 		const existingRpcBackend = await tryConnectRpcBackend(address);
 		if (existingRpcBackend) {
 			cachedBackend = existingRpcBackend;
+			await reconcileDeadSessionsIfSupported(cachedBackend);
 			return cachedBackend;
 		}
 
@@ -180,6 +191,7 @@ export async function resolveSessionBackend(
 				const rpcBackend = await tryConnectRpcBackend(address);
 				if (rpcBackend) {
 					cachedBackend = rpcBackend;
+					await reconcileDeadSessionsIfSupported(cachedBackend);
 					return cachedBackend;
 				}
 				if (delayMs > 0) {
@@ -189,6 +201,7 @@ export async function resolveSessionBackend(
 		}
 
 		cachedBackend = createLocalBackend();
+		await reconcileDeadSessionsIfSupported(cachedBackend);
 		return cachedBackend;
 	})().finally(() => {
 		backendInitPromise = undefined;

package/src/session/session-manager.ts

@@ -1,5 +1,5 @@
 import type { AgentResult } from "@clinebot/agents";
-import type { providers as LlmsProviders } from "@clinebot/llms";
+import type { LlmsProviders } from "@clinebot/llms";
 import type { SessionSource } from "../types/common";
 import type { CoreSessionConfig } from "../types/config";
 import type { CoreSessionEvent } from "../types/events";
@@ -54,7 +54,7 @@ export interface SessionManager {
 	getAccumulatedUsage(
 		sessionId: string,
 	): Promise<SessionAccumulatedUsage | undefined>;
-	abort(sessionId: string): Promise<void>;
+	abort(sessionId: string, reason?: unknown): Promise<void>;
 	stop(sessionId: string): Promise<void>;
 	dispose(reason?: string): Promise<void>;
 	get(sessionId: string): Promise<SessionRecord | undefined>;

package/src/session/session-team-coordination.ts

@@ -0,0 +1,198 @@
+import type { AgentResult, TeamEvent } from "@clinebot/agents";
+import { formatUserInputBlock } from "@clinebot/shared";
+import {
+	buildTeamProgressSummary,
+	toTeamProgressLifecycleEvent,
+} from "../team";
+import type { CoreSessionEvent } from "../types/events";
+import type { ActiveSession, TeamRunUpdate } from "./utils/types";
+
+export function trackTeamRunState(
+	session: ActiveSession,
+	event: TeamEvent,
+): void {
+	switch (event.type) {
+		case "run_queued":
+		case "run_started":
+			session.activeTeamRunIds.add(event.run.id);
+			break;
+		case "run_completed":
+		case "run_failed":
+		case "run_cancelled":
+		case "run_interrupted": {
+			let runError: string | undefined;
+			if (event.type === "run_failed") {
+				runError = event.run.error;
+			} else if (
+				event.type === "run_cancelled" ||
+				event.type === "run_interrupted"
+			) {
+				runError = event.run.error ?? event.reason;
+			}
+			session.activeTeamRunIds.delete(event.run.id);
+			session.pendingTeamRunUpdates.push({
+				runId: event.run.id,
+				agentId: event.run.agentId,
+				taskId: event.run.taskId,
+				status: event.type.replace("run_", "") as TeamRunUpdate["status"],
+				error: runError,
+				iterations: event.run.result?.iterations,
+			});
+			notifyTeamRunWaiters(session);
+			break;
+		}
+		default:
+			break;
+	}
+}
+
+export async function dispatchTeamEventToBackend(
+	rootSessionId: string,
+	event: TeamEvent,
+	invokeOptional: (method: string, ...args: unknown[]) => Promise<void>,
+): Promise<void> {
+	switch (event.type) {
+		case "task_start":
+			await invokeOptional(
+				"onTeamTaskStart",
+				rootSessionId,
+				event.agentId,
+				event.message,
+			);
+			break;
+		case "task_end": {
+			if (event.error) {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"failed",
+					`[error] ${event.error.message}`,
+					event.messages,
+				);
+			} else if (event.result?.finishReason === "aborted") {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"cancelled",
+					"[done] aborted",
+					event.result.messages,
+				);
+			} else {
+				await invokeOptional(
+					"onTeamTaskEnd",
+					rootSessionId,
+					event.agentId,
+					"completed",
+					`[done] ${event.result?.finishReason ?? "completed"}`,
+					event.result?.messages,
+				);
+			}
+			break;
+		}
+		default:
+			break;
+	}
+}
+
+export function emitTeamProgress(
+	session: ActiveSession,
+	rootSessionId: string,
+	event: TeamEvent,
+	emit: (event: CoreSessionEvent) => void,
+): void {
+	if (!session.runtime.teamRuntime) return;
+	const teamName = session.config.teamName?.trim() || "team";
+	emit({
+		type: "team_progress",
+		payload: {
+			sessionId: rootSessionId,
+			teamName,
+			lifecycle: toTeamProgressLifecycleEvent({
+				teamName,
+				sessionId: rootSessionId,
+				event,
+			}),
+			summary: buildTeamProgressSummary(
+				teamName,
+				session.runtime.teamRuntime.exportState(),
+			),
+		},
+	});
+}
+
+export function hasPendingTeamRunWork(session: ActiveSession): boolean {
+	return (
+		session.activeTeamRunIds.size > 0 ||
+		session.pendingTeamRunUpdates.length > 0
+	);
+}
+
+export function shouldAutoContinueTeamRuns(
+	session: ActiveSession,
+	finishReason: AgentResult["finishReason"],
+): boolean {
+	if (
+		session.aborting ||
+		finishReason === "aborted" ||
+		finishReason === "error"
+	) {
+		return false;
+	}
+	return (
+		session.config.enableAgentTeams === true && hasPendingTeamRunWork(session)
+	);
+}
+
+export function notifyTeamRunWaiters(session: ActiveSession): void {
+	const waiters = session.teamRunWaiters.splice(0);
+	for (const resolve of waiters) resolve();
+}
+
+export async function waitForTeamRunUpdates(
+	session: ActiveSession,
+): Promise<TeamRunUpdate[]> {
+	while (true) {
+		if (session.aborting) return [];
+		if (session.pendingTeamRunUpdates.length > 0) {
+			const updates = [...session.pendingTeamRunUpdates];
+			session.pendingTeamRunUpdates.length = 0;
+			return updates;
+		}
+		if (session.activeTeamRunIds.size === 0) return [];
+		await new Promise<void>((resolve) => {
+			session.teamRunWaiters.push(resolve);
+		});
+	}
+}
+
+export function buildTeamRunContinuationPrompt(
+	session: ActiveSession,
+	updates: TeamRunUpdate[],
+): string {
+	const lines = updates.map((u) => {
+		const parts = [`- ${u.runId} (${u.agentId}) -> ${u.status}`];
+		if (u.taskId) parts.push(` task=${u.taskId}`);
+		if (typeof u.iterations === "number")
+			parts.push(` iterations=${u.iterations}`);
+		if (u.error) parts.push(` error=${u.error}`);
+		return parts.join("");
+	});
+	const remaining = session.activeTeamRunIds.size;
+	const instruction =
+		remaining > 0
+			? `There are still ${remaining} teammate run(s) in progress. Continue coordination and decide whether to wait for more updates.`
+			: "No teammate runs are currently in progress. Continue coordination using these updates.";
+	return formatModePrompt(
+		`System-delivered teammate async run updates:\n${lines.join("\n")}\n\n${instruction}`,
+		session.config.mode,
+	);
+}
+
+export function formatModePrompt(
+	prompt: string,
+	mode: "act" | "plan" | undefined,
+): string {
+	return formatUserInputBlock(prompt, mode === "plan" ? "plan" : "act");
+}

package/src/session/session-telemetry.ts

@@ -0,0 +1,95 @@
+import type { ITelemetryService } from "@clinebot/shared";
+import {
+	listHookConfigFiles,
+	resolveDocumentsHooksDirectoryPath,
+} from "../agents/hooks-config-loader";
+import type { enrichPromptWithMentions } from "../input";
+import {
+	captureHookDiscovery,
+	captureMentionFailed,
+	captureMentionSearchResults,
+	captureMentionUsed,
+	captureTaskCreated,
+	captureTaskRestarted,
+} from "../telemetry/core-events";
+import type { SessionSource } from "../types/common";
+import type { CoreSessionConfig } from "../types/config";
+
+export function emitSessionCreationTelemetry(
+	config: CoreSessionConfig,
+	sessionId: string,
+	source: SessionSource,
+	isRestart: boolean,
+	workspacePath: string,
+): void {
+	if (isRestart) {
+		captureTaskRestarted(config.telemetry, {
+			ulid: sessionId,
+			apiProvider: config.providerId,
+		});
+	} else {
+		captureTaskCreated(config.telemetry, {
+			ulid: sessionId,
+			apiProvider: config.providerId,
+		});
+	}
+	captureHookDiscoveryTelemetry(config.telemetry, { workspacePath });
+	config.telemetry?.capture({
+		event: "session.started",
+		properties: {
+			sessionId,
+			source,
+			providerId: config.providerId,
+			modelId: config.modelId,
+			enableTools: config.enableTools,
+			enableSpawnAgent: config.enableSpawnAgent,
+			enableAgentTeams: config.enableAgentTeams,
+		},
+	});
+}
+
+export function captureHookDiscoveryTelemetry(
+	telemetry: ITelemetryService | undefined,
+	options: { workspacePath: string },
+): void {
+	const globalHooksDir = resolveDocumentsHooksDirectoryPath();
+	const entries = listHookConfigFiles(options.workspacePath);
+	const counts = new Map<string, { global: number; workspace: number }>();
+	for (const entry of entries) {
+		const hookName = entry.hookEventName ?? "unknown";
+		const current = counts.get(hookName) ?? { global: 0, workspace: 0 };
+		if (
+			entry.path === globalHooksDir ||
+			entry.path.startsWith(`${globalHooksDir}/`)
+		) {
+			current.global += 1;
+		} else {
+			current.workspace += 1;
+		}
+		counts.set(hookName, current);
+	}
+	for (const [hookName, count] of counts.entries()) {
+		captureHookDiscovery(telemetry, hookName, count.global, count.workspace);
+	}
+}
+
+export function emitMentionTelemetry(
+	telemetry: ITelemetryService | undefined,
+	enriched: Awaited<ReturnType<typeof enrichPromptWithMentions>>,
+): void {
+	for (const mention of enriched.mentions) {
+		captureMentionSearchResults(
+			telemetry,
+			mention,
+			enriched.matchedFiles.includes(mention) ? 1 : 0,
+			"file",
+			!enriched.matchedFiles.includes(mention),
+		);
+	}
+	for (const matched of enriched.matchedFiles) {
+		captureMentionUsed(telemetry, "file", matched.length);
+	}
+	for (const ignored of enriched.ignoredMentions) {
+		captureMentionFailed(telemetry, "file", "not_found", ignored);
+	}
+}