@clinebot/core 0.0.22 → 0.0.23

package/src/team/projections.ts

@@ -0,0 +1,285 @@
+import type {
+	TeamEvent,
+	TeamOutcome,
+	TeamOutcomeFragment,
+	TeamRuntimeState,
+} from "@clinebot/agents";
+import type {
+	TeamProgressLifecycleEvent,
+	TeamProgressSummary,
+} from "@clinebot/shared";
+
+function toIsoNow(): string {
+	return new Date().toISOString();
+}
+
+function pct(numerator: number, denominator: number): number {
+	if (denominator <= 0) {
+		return 0;
+	}
+	return Math.round((numerator / denominator) * 100);
+}
+
+function collectMissingRequiredSections(
+	outcomes: TeamOutcome[],
+	fragments: TeamOutcomeFragment[],
+): string[] {
+	const approvedSections = new Set<string>();
+	for (const fragment of fragments) {
+		if (fragment.status === "reviewed") {
+			approvedSections.add(`${fragment.outcomeId}:${fragment.section}`);
+		}
+	}
+	const missing = new Set<string>();
+	for (const outcome of outcomes) {
+		if (outcome.status === "finalized") {
+			continue;
+		}
+		for (const section of outcome.requiredSections) {
+			if (!approvedSections.has(`${outcome.id}:${section}`)) {
+				missing.add(`${outcome.id}:${section}`);
+			}
+		}
+	}
+	return [...missing].sort((a, b) => a.localeCompare(b));
+}
+
+export function buildTeamProgressSummary(
+	teamName: string,
+	state: TeamRuntimeState,
+): TeamProgressSummary {
+	const membersByStatus: Record<"idle" | "running" | "stopped", number> = {
+		idle: 0,
+		running: 0,
+		stopped: 0,
+	};
+	const tasksByStatus: Record<
+		"pending" | "in_progress" | "blocked" | "completed",
+		number
+	> = {
+		pending: 0,
+		in_progress: 0,
+		blocked: 0,
+		completed: 0,
+	};
+	const runsByStatus: Record<
+		"queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted",
+		number
+	> = {
+		queued: 0,
+		running: 0,
+		completed: 0,
+		failed: 0,
+		cancelled: 0,
+		interrupted: 0,
+	};
+	const outcomesByStatus: Record<"draft" | "in_review" | "finalized", number> =
+		{
+			draft: 0,
+			in_review: 0,
+			finalized: 0,
+		};
+	const fragmentsByStatus: Record<"draft" | "reviewed" | "rejected", number> = {
+		draft: 0,
+		reviewed: 0,
+		rejected: 0,
+	};
+
+	let leadCount = 0;
+	let teammateCount = 0;
+	for (const member of state.members) {
+		membersByStatus[member.status] += 1;
+		if (member.role === "lead") {
+			leadCount += 1;
+		} else {
+			teammateCount += 1;
+		}
+	}
+
+	const blockedTaskIds: string[] = [];
+	const readyTaskIds: string[] = [];
+	const completedTaskCount = state.tasks.filter(
+		(task) => task.status === "completed",
+	).length;
+	const taskById = new Map(state.tasks.map((task) => [task.id, task] as const));
+	for (const task of state.tasks) {
+		tasksByStatus[task.status] += 1;
+		if (task.status === "blocked") {
+			blockedTaskIds.push(task.id);
+			continue;
+		}
+		if (task.status !== "pending") {
+			continue;
+		}
+		const depsSatisfied = task.dependsOn.every((depId) => {
+			const dependency = taskById.get(depId);
+			return dependency?.status === "completed";
+		});
+		if (depsSatisfied) {
+			readyTaskIds.push(task.id);
+		}
+	}
+
+	const activeRunIds: string[] = [];
+	let latestRunId: string | undefined;
+	let latestRunTs = 0;
+	for (const run of state.runs) {
+		runsByStatus[run.status] += 1;
+		if (run.status === "queued" || run.status === "running") {
+			activeRunIds.push(run.id);
+		}
+		const startedAtTs = run.startedAt.getTime();
+		if (startedAtTs >= latestRunTs) {
+			latestRunTs = startedAtTs;
+			latestRunId = run.id;
+		}
+	}
+
+	for (const outcome of state.outcomes) {
+		outcomesByStatus[outcome.status] += 1;
+	}
+	for (const fragment of state.outcomeFragments) {
+		fragmentsByStatus[fragment.status] += 1;
+	}
+
+	return {
+		teamName,
+		updatedAt: toIsoNow(),
+		members: {
+			total: state.members.length,
+			byStatus: membersByStatus,
+			leadCount,
+			teammateCount,
+		},
+		tasks: {
+			total: state.tasks.length,
+			byStatus: tasksByStatus,
+			blockedTaskIds,
+			readyTaskIds,
+			completionPct: pct(completedTaskCount, state.tasks.length),
+		},
+		runs: {
+			total: state.runs.length,
+			byStatus: runsByStatus,
+			activeRunIds,
+			latestRunId,
+		},
+		outcomes: {
+			total: state.outcomes.length,
+			byStatus: outcomesByStatus,
+			finalizedPct: pct(outcomesByStatus.finalized, state.outcomes.length),
+			missingRequiredSections: collectMissingRequiredSections(
+				state.outcomes,
+				state.outcomeFragments,
+			),
+		},
+		fragments: {
+			total: state.outcomeFragments.length,
+			byStatus: fragmentsByStatus,
+		},
+	};
+}
+
+export function toTeamProgressLifecycleEvent(input: {
+	teamName: string;
+	sessionId: string;
+	event: TeamEvent;
+}): TeamProgressLifecycleEvent {
+	const { event } = input;
+	switch (event.type) {
+		case "team_task_updated":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				taskId: event.task.id,
+				agentId: event.task.assignee ?? event.task.createdBy,
+			};
+		case "run_queued":
+		case "run_started":
+		case "run_completed":
+		case "run_failed":
+		case "run_cancelled":
+		case "run_interrupted":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				runId: event.run.id,
+				taskId: event.run.taskId,
+				agentId: event.run.agentId,
+				message: event.run.error,
+			};
+		case "run_progress":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				runId: event.run.id,
+				taskId: event.run.taskId,
+				agentId: event.run.agentId,
+				message: event.message,
+			};
+		case "outcome_created":
+		case "outcome_finalized":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				outcomeId: event.outcome.id,
+			};
+		case "outcome_fragment_attached":
+		case "outcome_fragment_reviewed":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				outcomeId: event.fragment.outcomeId,
+				fragmentId: event.fragment.id,
+				agentId: event.fragment.sourceAgentId,
+			};
+		case "team_message":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				taskId: event.message.taskId,
+				agentId: event.message.fromAgentId,
+				message: event.message.subject,
+			};
+		case "team_mission_log":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				taskId: event.entry.taskId,
+				agentId: event.entry.agentId,
+				message: event.entry.summary,
+			};
+		case "teammate_spawned":
+		case "teammate_shutdown":
+		case "task_start":
+		case "task_end":
+		case "agent_event":
+			return {
+				teamName: input.teamName,
+				sessionId: input.sessionId,
+				eventType: event.type,
+				ts: toIsoNow(),
+				agentId: event.agentId,
+			};
+	}
+	return {
+		teamName: input.teamName,
+		sessionId: input.sessionId,
+		eventType: (event as TeamEvent).type,
+		ts: toIsoNow(),
+	};
+}

package/src/telemetry/ITelemetryAdapter.ts

@@ -0,0 +1,94 @@
+/**
+ * Telemetry adapter interface for the @clinebot/core SDK.
+ *
+ * This is the SDK-side counterpart to the extension's ITelemetryProvider.
+ * It is intentionally free of VS Code / host-provider dependencies so that
+ * any consumer (CLI, tests, third-party integrations) can plug in their own
+ * backend without pulling in the full extension runtime.
+ */
+
+import type { TelemetryProperties } from "@clinebot/shared";
+
+export type {
+	TelemetryArray,
+	TelemetryMetadata,
+	TelemetryObject,
+	TelemetryPrimitive,
+	TelemetryProperties,
+	TelemetryValue,
+} from "@clinebot/shared";
+
+// ---------------------------------------------------------------------------
+// Adapter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Telemetry adapter that an SDK consumer implements (or uses via the
+ * provided {@link OpenTelemetryAdapter}) to receive Cline telemetry events.
+ *
+ * The interface intentionally mirrors ITelemetryProvider from the extension
+ * so that shared logic can be re-used or compared easily.
+ */
+export interface ITelemetryAdapter {
+	/** Human-readable adapter name used for logging / diagnostics. */
+	readonly name: string;
+
+	/**
+	 * Emit a standard telemetry event.
+	 * Implementations may silently drop events when telemetry is disabled.
+	 */
+	emit(event: string, properties?: TelemetryProperties): void;
+
+	/**
+	 * Emit a *required* telemetry event that must not be suppressed by
+	 * user opt-out settings (e.g. final opt-out confirmation events).
+	 */
+	emitRequired(event: string, properties?: TelemetryProperties): void;
+
+	/**
+	 * Record a monotonically-increasing counter metric.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/**
+	 * Record a histogram (distribution) metric.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/**
+	 * Record a gauge (point-in-time) metric.
+	 * Pass `null` as `value` to retire the series identified by
+	 * `name + attributes` and prevent stale gauge entries.
+	 * Implementations that do not support metrics may treat this as a no-op.
+	 */
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+
+	/** Returns whether the adapter is currently accepting events. */
+	isEnabled(): boolean;
+
+	/** Flush any buffered events/metrics to the backend. */
+	flush(): Promise<void>;
+
+	/** Release all resources held by the adapter. */
+	dispose(): Promise<void>;
+}

package/src/telemetry/LoggerTelemetryAdapter.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+import { LoggerTelemetryAdapter } from "./LoggerTelemetryAdapter";
+
+describe("LoggerTelemetryAdapter", () => {
+	it("logs events and metrics through the provided logger", async () => {
+		const logger = {
+			debug: vi.fn(),
+			info: vi.fn(),
+			warn: vi.fn(),
+		};
+		const adapter = new LoggerTelemetryAdapter({ logger });
+
+		adapter.emit("session.started", { sessionId: "s1" });
+		adapter.emitRequired("user.opt_out", { reason: "manual" });
+		adapter.recordCounter("cline.session.starts.total", 1, {
+			sessionId: "s1",
+		});
+
+		expect(logger.info).toHaveBeenCalledWith("telemetry.event", {
+			adapter: "LoggerTelemetryAdapter",
+			event: "session.started",
+			properties: { sessionId: "s1" },
+		});
+		expect(logger.warn).toHaveBeenCalledWith("telemetry.required_event", {
+			adapter: "LoggerTelemetryAdapter",
+			event: "user.opt_out",
+			properties: { reason: "manual" },
+		});
+		expect(logger.debug).toHaveBeenCalledWith("telemetry.metric", {
+			adapter: "LoggerTelemetryAdapter",
+			instrument: "counter",
+			name: "cline.session.starts.total",
+			value: 1,
+			attributes: { sessionId: "s1" },
+			description: undefined,
+			required: false,
+		});
+
+		await adapter.flush();
+		await adapter.dispose();
+	});
+});

package/src/telemetry/LoggerTelemetryAdapter.ts

@@ -0,0 +1,114 @@
+import type { BasicLogger } from "@clinebot/shared";
+import type {
+	ITelemetryAdapter,
+	TelemetryProperties,
+} from "./ITelemetryAdapter";
+
+export interface LoggerTelemetryAdapterOptions {
+	logger?: BasicLogger;
+	name?: string;
+	enabled?: boolean | (() => boolean);
+}
+
+export class LoggerTelemetryAdapter implements ITelemetryAdapter {
+	readonly name: string;
+
+	private readonly logger?: BasicLogger;
+	private readonly enabled: boolean | (() => boolean);
+
+	constructor(options: LoggerTelemetryAdapterOptions = {}) {
+		this.name = options.name ?? "LoggerTelemetryAdapter";
+		this.logger = options.logger;
+		this.enabled = options.enabled ?? true;
+	}
+
+	emit(event: string, properties?: TelemetryProperties): void {
+		if (!this.isEnabled()) {
+			return;
+		}
+		this.logger?.info?.("telemetry.event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	emitRequired(event: string, properties?: TelemetryProperties): void {
+		this.logger?.warn?.("telemetry.required_event", {
+			adapter: this.name,
+			event,
+			properties,
+		});
+	}
+
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "counter",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "histogram",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void {
+		if (!required && !this.isEnabled()) {
+			return;
+		}
+		this.logger?.debug?.("telemetry.metric", {
+			adapter: this.name,
+			instrument: "gauge",
+			name,
+			value,
+			attributes,
+			description,
+			required: required === true,
+		});
+	}
+
+	isEnabled(): boolean {
+		return typeof this.enabled === "function" ? this.enabled() : this.enabled;
+	}
+
+	async flush(): Promise<void> {}
+
+	async dispose(): Promise<void> {}
+}

package/src/telemetry/OpenTelemetryAdapter.test.ts

@@ -0,0 +1,157 @@
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { describe, expect, it, vi } from "vitest";
+import { OpenTelemetryAdapter } from "./OpenTelemetryAdapter";
+
+describe("OpenTelemetryAdapter", () => {
+	it("emits events in the telemetry service log format", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			commonProperties: {
+				organization_id: "org-1",
+			},
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+		});
+
+		adapter.emit("task.created", {
+			ulid: "01HXYZ",
+			nested: {
+				mode: "act",
+			},
+			items: ["a", "b"],
+			nullable: null,
+		});
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "task.created",
+			attributes: expect.objectContaining({
+				ulid: "01HXYZ",
+				"nested.mode": "act",
+				items: JSON.stringify(["a", "b"]),
+				nullable: "null",
+				distinct_id: "user-123",
+				organization_id: "org-1",
+				extension_version: "1.2.3",
+				cline_type: "cli",
+				platform: "terminal",
+			}),
+		});
+	});
+
+	it("marks required events with the expected flag", () => {
+		const emit = vi.fn();
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			loggerProvider: {
+				getLogger: () => ({ emit }),
+			} as unknown as LoggerProvider,
+			enabled: false,
+		});
+
+		adapter.emitRequired("user.opt_out");
+
+		expect(emit).toHaveBeenCalledWith({
+			severityText: "INFO",
+			body: "user.opt_out",
+			attributes: expect.objectContaining({
+				_required: true,
+			}),
+		});
+	});
+
+	it("records metrics with merged telemetry attributes and retires gauge series", () => {
+		const counterAdd = vi.fn();
+		const histogramRecord = vi.fn();
+		let gaugeCallback:
+			| ((result: {
+					observe: (
+						value: number,
+						attributes?: Record<string, string | number | boolean>,
+					) => void;
+			  }) => void)
+			| undefined;
+
+		const forceFlush = vi.fn().mockResolvedValue(undefined);
+		const shutdown = vi.fn().mockResolvedValue(undefined);
+
+		const adapter = new OpenTelemetryAdapter({
+			metadata: makeMetadata(),
+			distinctId: "user-123",
+			meterProvider: {
+				getMeter: () =>
+					({
+						createCounter: () => ({ add: counterAdd }),
+						createHistogram: () => ({ record: histogramRecord }),
+						createObservableGauge: () => ({
+							addCallback: (callback: typeof gaugeCallback) => {
+								gaugeCallback = callback;
+							},
+						}),
+					}) as never,
+				forceFlush,
+				shutdown,
+			} as unknown as MeterProvider,
+		});
+
+		adapter.recordCounter("cline.turns.total", 2, { ulid: "01HXYZ" });
+		adapter.recordHistogram("cline.api.duration.seconds", 1.5, {
+			ulid: "01HXYZ",
+		});
+		adapter.recordGauge("cline.workspace.active_roots", 3, { workspace: "a" });
+
+		expect(counterAdd).toHaveBeenCalledWith(
+			2,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+				extension_version: "1.2.3",
+			}),
+		);
+		expect(histogramRecord).toHaveBeenCalledWith(
+			1.5,
+			expect.objectContaining({
+				ulid: "01HXYZ",
+				distinct_id: "user-123",
+			}),
+		);
+
+		const observe = vi.fn();
+		gaugeCallback?.({ observe });
+		expect(observe).toHaveBeenCalledWith(
+			3,
+			expect.objectContaining({
+				workspace: "a",
+				distinct_id: "user-123",
+			}),
+		);
+
+		adapter.recordGauge("cline.workspace.active_roots", null, {
+			workspace: "a",
+		});
+		const observeAfterRetire = vi.fn();
+		gaugeCallback?.({ observe: observeAfterRetire });
+		expect(observeAfterRetire).not.toHaveBeenCalled();
+
+		return Promise.all([adapter.flush(), adapter.dispose()]).then(() => {
+			expect(forceFlush).toHaveBeenCalledTimes(1);
+			expect(shutdown).toHaveBeenCalledTimes(1);
+		});
+	});
+});
+
+function makeMetadata() {
+	return {
+		extension_version: "1.2.3",
+		cline_type: "cli",
+		platform: "terminal",
+		platform_version: "1.0.0",
+		os_type: "darwin",
+		os_version: "24.0.0",
+		is_dev: "true",
+	};
+}