@clinebot/core 0.0.5 → 0.0.6

package/dist/tools/schemas.d.ts

@@ -23,6 +23,12 @@ export declare const ReadFilesInputUnionSchema: z.ZodUnion<readonly [z.ZodObject
 export declare const SearchCodebaseInputSchema: z.ZodObject<{
     queries: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Union schema for search_codebase tool input, allowing either a single string, an array of strings, or the full object schema
+ */
+export declare const SearchCodebaseUnionInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    queries: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodArray<z.ZodString>, z.ZodString]>;
 /**
  * Schema for run_commands tool input
  */

package/dist/types/config.d.ts

@@ -1,6 +1,6 @@
 import type { AgentConfig, AgentHooks, ConsecutiveMistakeLimitContext, ConsecutiveMistakeLimitDecision, HookErrorMode, TeamEvent, Tool } from "@clinebot/agents";
 import type { providers as LlmsProviders } from "@clinebot/llms";
-import type { AgentMode, BasicLogger, SessionExecutionConfig, SessionPromptConfig, SessionWorkspaceConfig } from "@clinebot/shared";
+import type { AgentMode, BasicLogger, ITelemetryService, SessionExecutionConfig, SessionPromptConfig, SessionWorkspaceConfig } from "@clinebot/shared";
 import type { ToolRoutingRule } from "../tools/model-tool-routing.js";
 export type CoreAgentMode = AgentMode;
 export interface CoreModelConfig {
@@ -35,6 +35,7 @@ export interface CoreSessionConfig extends CoreModelConfig, CoreRuntimeFeatures,
     hooks?: AgentHooks;
     hookErrorMode?: HookErrorMode;
     logger?: BasicLogger;
+    telemetry?: ITelemetryService;
     extraTools?: Tool[];
     pluginPaths?: string[];
     extensions?: AgentConfig["extensions"];

package/package.json

@@ -1,10 +1,18 @@
 {
 	"name": "@clinebot/core",
-	"version": "0.0.5",
+	"version": "0.0.6",
 	"main": "./dist/index.node.js",
 	"dependencies": {
-		"@clinebot/agents": "0.0.5",
-		"@clinebot/llms": "0.0.5",
+		"@clinebot/agents": "0.0.6",
+		"@clinebot/llms": "0.0.6",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/api-logs": "^0.56.0",
+		"@opentelemetry/exporter-logs-otlp-http": "^0.56.0",
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.56.0",
+		"@opentelemetry/resources": "^1.30.1",
+		"@opentelemetry/sdk-logs": "^0.56.0",
+		"@opentelemetry/sdk-metrics": "^1.30.1",
+		"@opentelemetry/semantic-conventions": "^1.37.0",
 		"better-sqlite3": "^11.10.0",
 		"nanoid": "^5.1.7",
 		"simple-git": "^3.32.3",
@@ -21,6 +29,11 @@
 			"development": "./src/index.node.ts",
 			"types": "./dist/index.node.d.ts",
 			"import": "./dist/index.node.js"
+		},
+		"./telemetry/opentelemetry": {
+			"development": "./src/telemetry/opentelemetry.ts",
+			"types": "./dist/telemetry/opentelemetry.d.ts",
+			"import": "./dist/telemetry/opentelemetry.js"
 		}
 	},
 	"description": "State-aware orchestration for Cline Agent runtimes",

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

@@ -45,10 +45,28 @@ const HOOK_CONFIG_FILE_LOOKUP = new Map<string, HookConfigFileName>(
 	Object.values(HookConfigFileName).map((name) => [name.toLowerCase(), name]),
 );
 
+const SUPPORTED_HOOK_FILE_EXTENSIONS = new Set([
+	"",
+	".sh",
+	".bash",
+	".zsh",
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+	".py",
+]);
+
 export function toHookConfigFileName(
 	fileName: string,
 ): HookConfigFileName | undefined {
-	const key = basename(fileName, extname(fileName)).trim().toLowerCase();
+	const extension = extname(fileName).toLowerCase();
+	if (!SUPPORTED_HOOK_FILE_EXTENSIONS.has(extension)) {
+		return undefined;
+	}
+	const key = basename(fileName, extension).trim().toLowerCase();
 	return HOOK_CONFIG_FILE_LOOKUP.get(key);
 }
 

package/src/index.node.ts

@@ -100,6 +100,9 @@ export {
 	OCI_HEADER_OPC_REQUEST_ID,
 	refreshOcaToken,
 } from "./auth/oca";
+export async function loadOpenTelemetryAdapter() {
+	return import("./telemetry/opentelemetry.js");
+}
 export { startLocalOAuthServer } from "./auth/server";
 export type {
 	OAuthCredentials,

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
 	BasicLogger,
 	ConnectorHookEvent,
 	HookSessionContext,
+	ITelemetryService,
 	RpcAddProviderActionRequest,
 	RpcChatMessage,
 	RpcChatRunTurnRequest,
@@ -38,6 +39,12 @@ export type {
 	RpcSaveProviderSettingsActionRequest,
 	SessionLineage,
 	TeamProgressProjectionEvent,
+	TelemetryArray,
+	TelemetryMetadata,
+	TelemetryObject,
+	TelemetryPrimitive,
+	TelemetryProperties,
+	TelemetryValue,
 	ToolPolicy,
 } from "@clinebot/shared";
 export {
@@ -116,6 +123,15 @@ export {
 	buildTeamProgressSummary,
 	toTeamProgressLifecycleEvent,
 } from "./team";
+export type { ITelemetryAdapter } from "./telemetry/ITelemetryAdapter";
+export {
+	LoggerTelemetryAdapter,
+	type LoggerTelemetryAdapterOptions,
+} from "./telemetry/LoggerTelemetryAdapter";
+export {
+	TelemetryService,
+	type TelemetryServiceOptions,
+} from "./telemetry/TelemetryService";
 export {
 	ALL_DEFAULT_TOOL_NAMES,
 	type AskQuestionExecutor,

package/src/runtime/hook-file-hooks.test.ts

@@ -17,6 +17,22 @@ async function createWorkspaceWithHook(
 }
 
 describe("createHookConfigFileHooks", () => {
+	it("ignores example hook files", async () => {
+		const { workspace } = await createWorkspaceWithHook(
+			"PreToolUse.example",
+			'echo \'HOOK_CONTROL\t{"cancel":true,"context":"should-not-run"}\'\n',
+		);
+		try {
+			const hooks = createHookConfigFileHooks({
+				cwd: workspace,
+				workspacePath: workspace,
+			});
+			expect(hooks).toBeUndefined();
+		} finally {
+			await rm(workspace, { recursive: true, force: true });
+		}
+	});
+
 	it("executes extensionless legacy hook files via bash fallback", async () => {
 		const { workspace } = await createWorkspaceWithHook(
 			"PreToolUse",
@@ -103,4 +119,35 @@ describe("createHookConfigFileHooks", () => {
 			await rm(workspace, { recursive: true, force: true });
 		}
 	});
+
+	it("executes python hook files", async () => {
+		const { workspace } = await createWorkspaceWithHook(
+			"PreToolUse.py",
+			'print(\'HOOK_CONTROL\\t{"cancel": false, "context": "python-ok"}\')\n',
+		);
+		try {
+			const hooks = createHookConfigFileHooks({
+				cwd: workspace,
+				workspacePath: workspace,
+			});
+			expect(hooks?.onToolCallStart).toBeTypeOf("function");
+			const control = await hooks?.onToolCallStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				iteration: 1,
+				call: {
+					id: "call_1",
+					name: "read_file",
+					input: { path: "README.md" },
+				},
+			});
+			expect(control).toMatchObject({
+				cancel: false,
+				context: "python-ok",
+			});
+		} finally {
+			await rm(workspace, { recursive: true, force: true });
+		}
+	});
 });

package/src/runtime/hook-file-hooks.ts

@@ -323,6 +323,9 @@ function inferHookCommand(path: string): string[] {
 	) {
 		return ["bun", "run", path];
 	}
+	if (lowered.endsWith(".py")) {
+		return ["python3", path];
+	}
 	// Default to bash for legacy hook files with no extension/shebang.
 	return ["/bin/bash", path];
 }

package/src/runtime/runtime-builder.test.ts

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Tool } from "@clinebot/agents";
 import { describe, expect, it } from "vitest";
+import { TelemetryService } from "../telemetry/TelemetryService";
 import { DefaultRuntimeBuilder } from "./runtime-builder";
 
 function makeSpawnTool(): Tool {
@@ -55,6 +56,25 @@ describe("DefaultRuntimeBuilder", () => {
 		expect(runtime.logger).toBe(logger);
 	});
 
+	it("forwards telemetry for downstream runtime consumers", () => {
+		const telemetry = new TelemetryService();
+		const runtime = new DefaultRuntimeBuilder().build({
+			config: {
+				providerId: "anthropic",
+				modelId: "claude-sonnet-4-6",
+				apiKey: "key",
+				systemPrompt: "test",
+				cwd: process.cwd(),
+				enableTools: false,
+				enableSpawnAgent: false,
+				enableAgentTeams: false,
+				telemetry,
+			},
+		});
+
+		expect(runtime.telemetry).toBe(telemetry);
+	});
+
 	it("uses readonly preset in plan mode", () => {
 		const runtime = new DefaultRuntimeBuilder().build({
 			config: {

package/src/runtime/runtime-builder.ts

@@ -522,6 +522,7 @@ export class DefaultRuntimeBuilder implements RuntimeBuilder {
 		return {
 			tools,
 			logger: logger ?? config.logger,
+			telemetry: input.telemetry ?? config.telemetry,
 			teamRuntime,
 			completionGuard,
 			shutdown: (reason: string) => {

package/src/runtime/session-runtime.ts

@@ -5,7 +5,7 @@ import type {
 	AgentTeamsRuntime,
 	Tool,
 } from "@clinebot/agents";
-import type { BasicLogger } from "@clinebot/shared";
+import type { BasicLogger, ITelemetryService } from "@clinebot/shared";
 import type { UserInstructionConfigWatcher } from "../agents";
 import type { ToolExecutors } from "../tools";
 import type { CoreSessionConfig } from "../types/config";
@@ -14,6 +14,7 @@ export interface BuiltRuntime {
 	tools: Tool[];
 	hooks?: AgentHooks;
 	logger?: BasicLogger;
+	telemetry?: ITelemetryService;
 	teamRuntime?: AgentTeamsRuntime;
 	completionGuard?: () => string | undefined;
 	shutdown: (reason: string) => Promise<void> | void;
@@ -29,6 +30,7 @@ export interface RuntimeBuilderInput {
 	userInstructionWatcher?: UserInstructionConfigWatcher;
 	defaultToolExecutors?: Partial<ToolExecutors>;
 	logger?: BasicLogger;
+	telemetry?: ITelemetryService;
 }
 
 export interface RuntimeBuilder {

package/src/session/default-session-manager.test.ts

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { AgentResult } from "@clinebot/agents";
 import { describe, expect, it, vi } from "vitest";
+import { TelemetryService } from "../telemetry/TelemetryService";
 import { SessionSource } from "../types/common";
 import type { CoreSessionConfig } from "../types/config";
 import { DefaultSessionManager } from "./default-session-manager";
@@ -70,6 +71,77 @@ function createConfig(
 }
 
 describe("DefaultSessionManager", () => {
+	it("emits session lifecycle telemetry when configured", async () => {
+		const sessionId = "sess-telemetry";
+		const manifest = createManifest(sessionId);
+		const adapter = {
+			name: "test",
+			emit: vi.fn(),
+			emitRequired: vi.fn(),
+			recordCounter: vi.fn(),
+			recordHistogram: vi.fn(),
+			recordGauge: vi.fn(),
+			isEnabled: vi.fn(() => true),
+			flush: vi.fn().mockResolvedValue(undefined),
+			dispose: vi.fn().mockResolvedValue(undefined),
+		};
+		const telemetry = new TelemetryService({
+			adapters: [adapter],
+			distinctId: distinctId,
+		});
+		const sessionService = {
+			ensureSessionsDir: vi.fn().mockReturnValue("/tmp/sessions"),
+			createRootSessionWithArtifacts: vi.fn().mockResolvedValue({
+				manifestPath: "/tmp/manifest.json",
+				transcriptPath: "/tmp/transcript.log",
+				hookPath: "/tmp/hook.log",
+				messagesPath: "/tmp/messages.json",
+				manifest,
+			}),
+			persistSessionMessages: vi.fn(),
+			updateSessionStatus: vi.fn().mockResolvedValue({
+				updated: true,
+				endedAt: "2026-01-01T00:00:05.000Z",
+			}),
+			writeSessionManifest: vi.fn(),
+			listSessions: vi.fn().mockResolvedValue([]),
+			deleteSession: vi.fn().mockResolvedValue({ deleted: true }),
+		};
+		const runtimeBuilder = {
+			build: vi.fn().mockReturnValue({
+				tools: [],
+				shutdown: vi.fn(),
+			}),
+		};
+		const agent = {
+			run: vi.fn().mockResolvedValue(createResult()),
+			continue: vi.fn().mockResolvedValue(createResult()),
+			getMessages: vi.fn().mockReturnValue([]),
+			abort: vi.fn(),
+			shutdown: vi.fn().mockResolvedValue(undefined),
+		};
+		const manager = new DefaultSessionManager({
+			distinctId,
+			sessionService: sessionService as never,
+			runtimeBuilder: runtimeBuilder as never,
+			createAgent: () => agent as never,
+			telemetry,
+		});
+
+		await manager.start({
+			config: createConfig({ telemetry, sessionId }),
+			prompt: "hello",
+		});
+
+		expect(adapter.emit).toHaveBeenCalledWith(
+			"session.started",
+			expect.objectContaining({
+				sessionId,
+				distinct_id: distinctId,
+			}),
+		);
+	});
+
 	it("runs a non-interactive prompt and persists messages/status", async () => {
 		const sessionId = "sess-1";
 		const manifest = createManifest(sessionId);

package/src/session/default-session-manager.ts

@@ -14,7 +14,11 @@ import {
 	type ToolApprovalResult,
 } from "@clinebot/agents";
 import type { providers as LlmsProviders } from "@clinebot/llms";
-import { formatUserInputBlock, normalizeUserInput } from "@clinebot/shared";
+import {
+	formatUserInputBlock,
+	type ITelemetryService,
+	normalizeUserInput,
+} from "@clinebot/shared";
 import { setHomeDirIfUnset } from "@clinebot/shared/storage";
 import { nanoid } from "nanoid";
 import { resolveAndLoadAgentPlugins } from "../agents/plugin-config-loader";
@@ -89,6 +93,7 @@ export interface DefaultSessionManagerOptions {
 	toolPolicies?: AgentConfig["toolPolicies"];
 	providerSettingsManager?: ProviderSettingsManager;
 	oauthTokenManager?: RuntimeOAuthTokenManager;
+	telemetry?: ITelemetryService;
 	requestToolApproval?: (
 		request: ToolApprovalRequest,
 	) => Promise<ToolApprovalResult>;
@@ -120,6 +125,7 @@ export class DefaultSessionManager implements SessionManager {
 	private readonly defaultToolPolicies?: AgentConfig["toolPolicies"];
 	private readonly providerSettingsManager: ProviderSettingsManager;
 	private readonly oauthTokenManager: RuntimeOAuthTokenManager;
+	private readonly defaultTelemetry?: ITelemetryService;
 	private readonly defaultRequestToolApproval?: (
 		request: ToolApprovalRequest,
 	) => Promise<ToolApprovalResult>;
@@ -143,6 +149,7 @@ export class DefaultSessionManager implements SessionManager {
 			new RuntimeOAuthTokenManager({
 				providerSettingsManager: this.providerSettingsManager,
 			});
+		this.defaultTelemetry = options.telemetry;
 		this.defaultRequestToolApproval = options.requestToolApproval;
 	}
 
@@ -263,6 +270,7 @@ export class DefaultSessionManager implements SessionManager {
 			...input.config,
 			hooks: effectiveHooks,
 			extensions: effectiveExtensions,
+			telemetry: input.config.telemetry ?? this.defaultTelemetry,
 		};
 		const providerConfig =
 			this.buildResolvedProviderConfig(effectiveConfigBase);
@@ -276,6 +284,7 @@ export class DefaultSessionManager implements SessionManager {
 			hooks: effectiveHooks,
 			extensions: effectiveExtensions,
 			logger: effectiveConfig.logger,
+			telemetry: effectiveConfig.telemetry,
 			onTeamEvent: (event: TeamEvent) => {
 				void this.handleTeamEvent(sessionId, event);
 				effectiveConfig.onTeamEvent?.(event);
@@ -287,6 +296,18 @@ export class DefaultSessionManager implements SessionManager {
 				input.defaultToolExecutors ?? this.defaultToolExecutors,
 		});
 		const tools = [...runtime.tools, ...(effectiveConfig.extraTools ?? [])];
+		effectiveConfig.telemetry?.capture({
+			event: "session.started",
+			properties: {
+				sessionId,
+				source,
+				providerId: effectiveConfig.providerId,
+				modelId: effectiveConfig.modelId,
+				enableTools: effectiveConfig.enableTools,
+				enableSpawnAgent: effectiveConfig.enableSpawnAgent,
+				enableAgentTeams: effectiveConfig.enableAgentTeams,
+			},
+		});
 		const agent = this.createAgentInstance({
 			providerId: providerConfig.providerId,
 			modelId: providerConfig.modelId,
@@ -326,6 +347,14 @@ export class DefaultSessionManager implements SessionManager {
 						}),
 					);
 				}
+				if (event.type === "iteration_end") {
+					void this.invoke<void>(
+						"persistSessionMessages",
+						sessionId,
+						liveSession?.agent.getMessages() ?? [],
+						liveSession?.config.systemPrompt,
+					);
+				}
 				this.emit({
 					type: "agent_event",
 					payload: {
@@ -397,6 +426,15 @@ export class DefaultSessionManager implements SessionManager {
 		if (!session) {
 			throw new Error(`session not found: ${input.sessionId}`);
 		}
+		session.config.telemetry?.capture({
+			event: "session.input_sent",
+			properties: {
+				sessionId: input.sessionId,
+				promptLength: input.prompt.length,
+				userImageCount: input.userImages?.length ?? 0,
+				userFileCount: input.userFiles?.length ?? 0,
+			},
+		});
 		try {
 			const result = await this.runTurn(session, {
 				prompt: input.prompt,
@@ -428,6 +466,10 @@ export class DefaultSessionManager implements SessionManager {
 		if (!session) {
 			return;
 		}
+		session.config.telemetry?.capture({
+			event: "session.aborted",
+			properties: { sessionId },
+		});
 		session.aborting = true;
 		session.agent.abort();
 	}
@@ -437,6 +479,10 @@ export class DefaultSessionManager implements SessionManager {
 		if (!session) {
 			return;
 		}
+		session.config.telemetry?.capture({
+			event: "session.stopped",
+			properties: { sessionId },
+		});
 		await this.shutdownSession(session, {
 			status: "cancelled",
 			exitCode: null,
@@ -1200,4 +1246,16 @@ export class DefaultSessionManager implements SessionManager {
 			apiKey: resolved.apiKey,
 		});
 	}
+
+	async updateSessionModel(sessionId: string, modelId: string): Promise<void> {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			throw new Error(`session not found: ${sessionId}`);
+		}
+		session.config.modelId = modelId;
+		const agentWithConnection = session.agent as Agent & {
+			updateConnection?: (overrides: { modelId?: string }) => void;
+		};
+		agentWithConnection.updateConnection?.({ modelId });
+	}
 }

package/src/session/session-host.ts

@@ -7,6 +7,7 @@ import type {
 	ToolApprovalResult,
 } from "@clinebot/agents";
 import { getRpcServerDefaultAddress, getRpcServerHealth } from "@clinebot/rpc";
+import type { ITelemetryService } from "@clinebot/shared";
 import { resolveSessionDataDir } from "@clinebot/shared/storage";
 import { nanoid } from "nanoid";
 import { SqliteSessionStore } from "../storage/sqlite-session-store";
@@ -33,6 +34,7 @@ export interface CreateSessionHostOptions {
 	rpcConnectAttempts?: number;
 	rpcConnectDelayMs?: number;
 	defaultToolExecutors?: Partial<ToolExecutors>;
+	telemetry?: ITelemetryService;
 	toolPolicies?: AgentConfig["toolPolicies"];
 	requestToolApproval?: (
 		request: ToolApprovalRequest,
@@ -190,13 +192,16 @@ export async function resolveSessionBackend(
 export async function createSessionHost(
 	options: CreateSessionHostOptions,
 ): Promise<SessionHost> {
+	const distinctId = resolveHostDistinctId(options.distinctId);
+	options.telemetry?.setDistinctId(distinctId);
 	const backend =
 		options.sessionService ?? (await resolveSessionBackend(options));
 	return new DefaultSessionManager({
 		sessionService: backend,
 		defaultToolExecutors: options.defaultToolExecutors,
+		telemetry: options.telemetry,
 		toolPolicies: options.toolPolicies,
 		requestToolApproval: options.requestToolApproval,
-		distinctId: resolveHostDistinctId(options.distinctId),
+		distinctId,
 	});
 }

package/src/session/session-manager.ts

@@ -64,4 +64,5 @@ export interface SessionManager {
 	readTranscript(sessionId: string, maxChars?: number): Promise<string>;
 	readHooks(sessionId: string, limit?: number): Promise<unknown[]>;
 	subscribe(listener: (event: CoreSessionEvent) => void): () => void;
+	updateSessionModel?(sessionId: string, modelId: string): Promise<void>;
 }

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();
+	});
+});