@clinebot/core 0.0.36 → 0.0.37

package/src/ClineCore.ts

@@ -1,16 +1,41 @@
 import type {
 	AgentConfig,
+	AgentExtensionAutomationContext,
+	AgentResult,
+	AutomationEventEnvelope,
 	BasicLogger,
+	ChatRunTurnRequest,
+	ChatStartSessionRequest,
+	ChatTurnResult,
+	ExtensionContext,
 	ITelemetryService,
 	ToolApprovalRequest,
 	ToolApprovalResult,
 } from "@clinebot/shared";
+import type {
+	CronEventIngressResult,
+	CronEventSuppression,
+} from "./cron/cron-event-ingress";
+import { CronService } from "./cron/cron-service";
+import type { HubScheduleRuntimeHandlers } from "./cron/schedule-service";
+import type {
+	CronEventLogRecord,
+	CronRunRecord,
+	CronSpecRecord,
+} from "./cron/sqlite-cron-store";
 import type { ToolExecutors } from "./extensions/tools";
-import { hydrateSessionHistory } from "./runtime/history";
+import { normalizeProviderId } from "./llms/provider-settings";
+import type { SessionHistoryListOptions } from "./runtime/history";
+import { listSessionHistory } from "./runtime/history";
 import type { SessionBackend } from "./runtime/host";
 import { createRuntimeHost } from "./runtime/host";
 import type {
 	LocalRuntimeStartOptions,
+	PendingPromptMutationResult,
+	PendingPromptsAction,
+	PendingPromptsDeleteInput,
+	PendingPromptsListInput,
+	PendingPromptsUpdateInput,
 	RuntimeHost,
 	RuntimeHostMode,
 	RuntimeHostSubscribeOptions,
@@ -18,9 +43,12 @@ import type {
 	StartSessionResult,
 } from "./runtime/runtime-host";
 import { splitCoreSessionConfig } from "./runtime/runtime-host";
+import { CORE_TELEMETRY_EVENTS } from "./services/telemetry/core-events";
+import { SessionSource } from "./types/common";
 import type { CoreSessionConfig } from "./types/config";
-import type { CoreSessionEvent } from "./types/events";
+import type { CoreSessionEvent, SessionPendingPrompt } from "./types/events";
 import type { SessionMessagesArtifactUploader } from "./types/session";
+import type { SessionHistoryRecord } from "./types/sessions";
 
 export interface HubOptions {
 	endpoint?: string;
@@ -41,8 +69,84 @@ export interface RemoteOptions {
 	cwd?: string;
 }
 
+export interface ClineCoreAutomationOptions {
+	/** @deprecated Use `cronSpecsDir`. */
+	cronDir?: string;
+	cronSpecsDir?: string;
+	/** @deprecated Reports are written under the resolved cron specs directory. */
+	reportsDir?: string;
+	cronScope?: "global" | "user" | "workspace";
+	workspaceRoot?: string;
+	dbPath?: string;
+	pollIntervalMs?: number;
+	claimLeaseSeconds?: number;
+	globalMaxConcurrency?: number;
+	watcherDebounceMs?: number;
+	autoStart?: boolean;
+}
+
+export type ClineAutomationSpec = CronSpecRecord;
+export type ClineAutomationRun = CronRunRecord;
+export type ClineAutomationEventLog = CronEventLogRecord;
+export type ClineAutomationEventSuppression = CronEventSuppression;
+export type ClineAutomationRunStatus =
+	| "queued"
+	| "running"
+	| "done"
+	| "failed"
+	| "cancelled";
+
+export interface ClineAutomationListSpecsOptions {
+	triggerKind?: "one_off" | "schedule" | "event";
+	enabled?: boolean;
+	parseStatus?: "valid" | "invalid";
+	includeRemoved?: boolean;
+	limit?: number;
+}
+
+export interface ClineAutomationListRunsOptions {
+	specId?: string;
+	status?: ClineAutomationRunStatus | ClineAutomationRunStatus[];
+	limit?: number;
+}
+
+export interface ClineAutomationListEventsOptions {
+	eventType?: string;
+	source?: string;
+	processingStatus?:
+		| "received"
+		| "unmatched"
+		| "queued"
+		| "suppressed"
+		| "failed";
+	limit?: number;
+}
+
+export interface ClineAutomationEventIngressResult {
+	event: ClineAutomationEventLog;
+	duplicate: boolean;
+	matchedSpecIds: string[];
+	queuedRuns: ClineAutomationRun[];
+	suppressions: ClineAutomationEventSuppression[];
+}
+
+export interface ClineCoreAutomationApi {
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	reconcileNow(): Promise<void>;
+	ingestEvent(event: any): ClineAutomationEventIngressResult;
+	listEvents(
+		options?: ClineAutomationListEventsOptions,
+	): ClineAutomationEventLog[];
+	getEvent(eventId: string): ClineAutomationEventLog | undefined;
+	listSpecs(options?: ClineAutomationListSpecsOptions): ClineAutomationSpec[];
+	listRuns(options?: ClineAutomationListRunsOptions): ClineAutomationRun[];
+}
+
 export type { RuntimeHostMode };
 
+export type ClineCoreListHistoryOptions = SessionHistoryListOptions;
+
 export interface ClineCoreStartInput
 	extends Omit<StartSessionInput, "config" | "localRuntime"> {
 	config: CoreSessionConfig;
@@ -112,6 +216,12 @@ export interface ClineCoreOptions {
 	 * Consumers can use this to mirror session transcripts into remote storage.
 	 */
 	messagesArtifactUploader?: SessionMessagesArtifactUploader;
+	/**
+	 * Enables file-based and event-driven automation through this ClineCore
+	 * instance. When configured, callers use `cline.automation.*` instead of
+	 * constructing cron services directly.
+	 */
+	automation?: boolean | ClineCoreAutomationOptions;
 	/**
 	 * Custom `fetch` implementation forwarded to the AI gateway providers used
 	 * by local sessions. When supplied, it is threaded into each
@@ -159,6 +269,102 @@ export interface StartSessionBootstrap {
 	dispose?(): Promise<void> | void;
 }
 
+function normalizeAutomationOptions(
+	options: ClineCoreOptions["automation"],
+): ClineCoreAutomationOptions | undefined {
+	if (options === true) return {};
+	if (!options) return undefined;
+	return options;
+}
+
+function normalizeAutomationCronScope(
+	scope: ClineCoreAutomationOptions["cronScope"],
+): "global" | "workspace" | undefined {
+	if (scope === "user") return "global";
+	return scope;
+}
+
+function toChatTurnResult(result: AgentResult): ChatTurnResult {
+	return {
+		text: result.text,
+		usage: {
+			inputTokens: result.usage.inputTokens,
+			outputTokens: result.usage.outputTokens,
+			cacheReadTokens: result.usage.cacheReadTokens,
+			cacheWriteTokens: result.usage.cacheWriteTokens,
+			totalCost: result.usage.totalCost,
+		},
+		inputTokens: result.usage.inputTokens,
+		outputTokens: result.usage.outputTokens,
+		iterations: result.iterations,
+		finishReason: result.finishReason,
+		toolCalls: result.toolCalls.map((call) => ({
+			name: call.name,
+			input: call.input,
+			output: call.output,
+			error: call.error,
+			durationMs: call.durationMs,
+		})),
+	};
+}
+
+function resolveMode(
+	request: ChatStartSessionRequest | ChatRunTurnRequest["config"],
+): "act" | "plan" | "yolo" {
+	return request.mode === "plan"
+		? "plan"
+		: request.mode === "yolo"
+			? "yolo"
+			: "act";
+}
+
+class ClineCoreAutomationController implements ClineCoreAutomationApi {
+	constructor(private readonly getService: () => CronService) {}
+
+	async start(): Promise<void> {
+		await this.getService().start();
+	}
+
+	async stop(): Promise<void> {
+		await this.getService().stop();
+	}
+
+	async reconcileNow(): Promise<void> {
+		await this.getService().reconcileNow();
+	}
+
+	ingestEvent(
+		event: AutomationEventEnvelope,
+	): ClineAutomationEventIngressResult {
+		const result: CronEventIngressResult = this.getService().ingestEvent(event);
+		return {
+			event: result.event,
+			duplicate: result.duplicate,
+			matchedSpecIds: result.matchedSpecs.map((spec) => spec.specId),
+			queuedRuns: result.queuedRuns,
+			suppressions: result.suppressions,
+		};
+	}
+
+	listEvents(
+		options?: ClineAutomationListEventsOptions,
+	): ClineAutomationEventLog[] {
+		return this.getService().listEventLogs(options);
+	}
+
+	getEvent(eventId: string): ClineAutomationEventLog | undefined {
+		return this.getService().getEventLog(eventId);
+	}
+
+	listSpecs(options?: ClineAutomationListSpecsOptions): ClineAutomationSpec[] {
+		return this.getService().listSpecs(options);
+	}
+
+	listRuns(options?: ClineAutomationListRunsOptions): ClineAutomationRun[] {
+		return this.getService().listRuns(options);
+	}
+}
+
 /**
  * The primary entry point for the Cline Core SDK.
  *
@@ -173,9 +379,14 @@ export interface StartSessionBootstrap {
 export class ClineCore implements RuntimeHost {
 	readonly clientName: string | undefined;
 	readonly runtimeAddress: string | undefined;
+	readonly automation: ClineCoreAutomationApi;
 	private readonly host: RuntimeHost;
 	private readonly prepare: ClineCoreOptions["prepare"] | undefined;
 	private readonly defaultToolExecutors: Partial<ToolExecutors> | undefined;
+	private readonly logger: BasicLogger | undefined;
+	private readonly telemetry: ITelemetryService | undefined;
+	private readonly distinctId: string | undefined;
+	private readonly automationService: CronService | undefined;
 	private readonly activeSessionBootstraps = new Map<
 		string,
 		StartSessionBootstrap
@@ -188,12 +399,47 @@ export class ClineCore implements RuntimeHost {
 		runtimeAddress: string | undefined,
 		prepare: ClineCoreOptions["prepare"],
 		defaultToolExecutors: Partial<ToolExecutors> | undefined,
+		logger: BasicLogger | undefined,
+		telemetry: ITelemetryService | undefined,
+		distinctId: string | undefined,
+		automationOptions:
+			| (ClineCoreAutomationOptions & { logger?: BasicLogger })
+			| undefined,
 	) {
 		this.clientName = clientName;
 		this.runtimeAddress = runtimeAddress;
 		this.host = host;
 		this.prepare = prepare;
 		this.defaultToolExecutors = defaultToolExecutors;
+		this.logger = logger;
+		this.telemetry = telemetry;
+		this.distinctId = distinctId;
+		this.automationService = automationOptions
+			? new CronService({
+					workspaceRoot: automationOptions.workspaceRoot ?? process.cwd(),
+					specs: {
+						cronSpecsDir:
+							automationOptions.cronSpecsDir ?? automationOptions.cronDir,
+						scope: normalizeAutomationCronScope(automationOptions.cronScope),
+						workspaceRoot: automationOptions.workspaceRoot,
+					},
+					runtimeHandlers: this.createAutomationRuntimeHandlers(host),
+					dbPath: automationOptions.dbPath,
+					logger: automationOptions.logger,
+					pollIntervalMs: automationOptions.pollIntervalMs,
+					claimLeaseSeconds: automationOptions.claimLeaseSeconds,
+					globalMaxConcurrency: automationOptions.globalMaxConcurrency,
+					watcherDebounceMs: automationOptions.watcherDebounceMs,
+				})
+			: undefined;
+		this.automation = new ClineCoreAutomationController(() => {
+			if (!this.automationService) {
+				throw new Error(
+					"ClineCore automation is not enabled. Pass `automation: true` or automation options to ClineCore.create().",
+				);
+			}
+			return this.automationService;
+		});
 		this.unsubscribeBootstrapCleanup = this.host.subscribe((event) => {
 			if (event.type !== "ended") {
 				return;
@@ -202,15 +448,155 @@ export class ClineCore implements RuntimeHost {
 		});
 	}
 
+	/**
+	 * Creates a new ClineCore instance.
+	 *
+	 * This is the primary factory method for initializing the SDK. It sets up the runtime
+	 * host (local, hub, or remote) based on the provided options and prepares the SDK for
+	 * starting sessions.
+	 *
+	 * @param options Configuration options for the SDK instance
+	 * @returns A promise that resolves to a new ClineCore instance
+	 *
+	 * @example
+	 * ```ts
+	 * const cline = await ClineCore.create({
+	 *   clientName: "my-app",
+	 *   backendMode: "local",
+	 * });
+	 * ```
+	 */
 	static async create(options: ClineCoreOptions = {}): Promise<ClineCore> {
 		const host = await createRuntimeHost(options);
-		return new ClineCore(
+		const automationOptions = normalizeAutomationOptions(options.automation);
+		const core = new ClineCore(
 			host,
 			options.clientName,
 			host.runtimeAddress,
 			options.prepare,
 			options.defaultToolExecutors,
+			options.logger,
+			options.telemetry,
+			options.distinctId,
+			automationOptions
+				? { ...automationOptions, logger: options.logger }
+				: undefined,
 		);
+		if (automationOptions && automationOptions.autoStart !== false) {
+			await core.automation.start();
+		}
+		return core;
+	}
+
+	private createAutomationRuntimeHandlers(
+		host: RuntimeHost,
+	): HubScheduleRuntimeHandlers {
+		const core = this;
+		return {
+			async startSession(request) {
+				const cwd = (request.cwd?.trim() || request.workspaceRoot).trim();
+				const started = await host.start({
+					source: request.source?.trim() || SessionSource.CLI,
+					interactive: false,
+					config: {
+						providerId: normalizeProviderId(request.provider),
+						modelId: request.model,
+						apiKey: request.apiKey?.trim() || undefined,
+						cwd,
+						workspaceRoot: request.workspaceRoot,
+						systemPrompt: request.systemPrompt ?? "",
+						mode: resolveMode(request),
+						maxIterations: request.maxIterations,
+						enableTools: request.enableTools !== false,
+						enableSpawnAgent: request.enableSpawn !== false,
+						enableAgentTeams: request.enableTeams !== false,
+						disableMcpSettingsTools: request.disableMcpSettingsTools,
+						missionLogIntervalSteps: request.missionStepInterval,
+						missionLogIntervalMs: request.missionTimeIntervalMs,
+					},
+					toolPolicies: request.toolPolicies ?? {
+						"*": {
+							autoApprove: request.autoApproveTools !== false,
+						},
+					},
+					localRuntime: {
+						configOverrides: {
+							extensionContext: core.withAutomationExtensionContext(),
+						},
+						configExtensions: request.configExtensions,
+					},
+				});
+				return {
+					sessionId: started.sessionId,
+					startResult: {
+						sessionId: started.sessionId,
+						manifestPath: started.manifestPath,
+						messagesPath: started.messagesPath,
+					},
+				};
+			},
+			async sendSession(sessionId, request) {
+				const result = await host.send({
+					sessionId,
+					prompt: request.prompt,
+					userImages: request.attachments?.userImages,
+					userFiles: request.attachments?.userFiles?.map(
+						(file) => file.content,
+					),
+					delivery: request.delivery,
+				});
+				if (!result) {
+					throw new Error("ClineCore automation runtime returned no result");
+				}
+				return { result: toChatTurnResult(result) };
+			},
+			async abortSession(sessionId) {
+				await host.abort(sessionId, new Error("ClineCore automation abort"));
+				return { applied: true };
+			},
+			async stopSession(sessionId) {
+				await host.stop(sessionId);
+				return { applied: true };
+			},
+		};
+	}
+
+	private createAutomationPluginContext():
+		| AgentExtensionAutomationContext
+		| undefined {
+		if (!this.automationService) {
+			return undefined;
+		}
+		return {
+			ingestEvent: (event: AutomationEventEnvelope) => {
+				this.automation.ingestEvent(event);
+			},
+		};
+	}
+
+	private withAutomationExtensionContext(
+		context?: ExtensionContext,
+	): ExtensionContext | undefined {
+		const automation = this.createAutomationPluginContext();
+		const client =
+			context?.client ??
+			(this.clientName ? { name: this.clientName } : undefined);
+		const user =
+			context?.user ??
+			(this.distinctId ? { distinctId: this.distinctId } : undefined);
+		const logger = context?.logger ?? this.logger;
+		const telemetry = context?.telemetry ?? this.telemetry;
+		if (!automation && !client && !user && !logger && !telemetry) {
+			return context;
+		}
+		return {
+			...(context ?? {}),
+			...(client ? { client } : {}),
+			...(user ? { user } : {}),
+			...(logger ? { logger } : {}),
+			...(telemetry ? { telemetry } : {}),
+			...(automation ? { automation } : {}),
+		};
 	}
 
 	private async disposeSessionBootstrap(sessionId: string): Promise<void> {
@@ -245,7 +631,7 @@ export class ClineCore implements RuntimeHost {
 
 	private normalizeStartInput(input: ClineCoreStartInput): StartSessionInput {
 		const split = splitCoreSessionConfig(input.config);
-		const localRuntime =
+		let localRuntime: LocalRuntimeStartOptions | undefined =
 			split.localRuntime || input.localRuntime || this.defaultToolExecutors
 				? {
 						...(split.localRuntime ?? {}),
@@ -261,6 +647,18 @@ export class ClineCore implements RuntimeHost {
 						},
 					}
 				: undefined;
+		const automationExtensionContext = this.withAutomationExtensionContext(
+			localRuntime?.configOverrides?.extensionContext,
+		);
+		if (automationExtensionContext) {
+			localRuntime = {
+				...(localRuntime ?? {}),
+				configOverrides: {
+					...(localRuntime?.configOverrides ?? {}),
+					extensionContext: automationExtensionContext,
+				},
+			};
+		}
 		return {
 			...input,
 			...split,
@@ -268,7 +666,36 @@ export class ClineCore implements RuntimeHost {
 		};
 	}
 
+	/**
+	 * Starts a new Cline session with the provided configuration.
+	 *
+	 * This method initializes and begins a new agent session. It handles session setup,
+	 * runs any preparation hooks, and returns session metadata along with event streams.
+	 * The session continues to run until explicitly stopped or aborted.
+	 *
+	 * @param input The session configuration and startup parameters
+	 * @returns A promise that resolves to session metadata and event stream
+	 *
+	 * @example
+	 * ```ts
+	 * const result = await cline.start({
+	 *   config: {
+	 *     providerId: "anthropic",
+	 *     modelId: "claude-opus-4-1",
+	 *   },
+	 * });
+	 *
+	 * // Subscribe to session events
+	 * result.subscribe((event) => {
+	 *   console.log("Session event:", event);
+	 * });
+	 * ```
+	 */
 	start(input: StartSessionInput): Promise<StartSessionResult>;
+	/**
+	 * Starts a new Cline session with extended core-specific configuration.
+	 * This overload allows specifying local runtime options and config overrides.
+	 */
 	start(input: ClineCoreStartInput): Promise<StartSessionResult>;
 	async start(
 		input: StartSessionInput | ClineCoreStartInput,
@@ -290,22 +717,154 @@ export class ClineCore implements RuntimeHost {
 					await Promise.resolve(bootstrap.dispose?.());
 				}
 			}
+			this.emitSessionStartedTelemetry(preparedInput, result.sessionId);
 			return result;
 		} catch (error) {
 			await Promise.resolve(bootstrap?.dispose?.());
 			throw error;
 		}
 	}
+
+	private emitSessionStartedTelemetry(
+		input: ClineCoreStartInput,
+		sessionId: string,
+	): void {
+		// Per-session telemetry override (passed via `CoreSessionConfig.telemetry`)
+		// takes precedence over the instance-wide telemetry service configured
+		// on `ClineCore.create`. Either way we fire a single `session.started`
+		// event here so the signal is emitted for every backend (local, hub,
+		// remote), not just the in-process local transport.
+		const telemetry = input.config.telemetry ?? this.telemetry;
+		if (!telemetry) {
+			return;
+		}
+		telemetry.capture({
+			event: CORE_TELEMETRY_EVENTS.SESSION.STARTED,
+			properties: {
+				sessionId,
+				source: input.source ?? SessionSource.CORE,
+				providerId: input.config.providerId,
+				modelId: input.config.modelId,
+				enableTools: input.config.enableTools,
+				enableSpawnAgent: input.config.enableSpawnAgent,
+				enableAgentTeams: input.config.enableAgentTeams,
+				clientName: this.clientName,
+				runtimeAddress: this.runtimeAddress,
+			},
+		});
+	}
+	/**
+	 * Sends a message or command to an active session.
+	 *
+	 * This method communicates with a running session, allowing you to send user messages,
+	 * tool responses, or other session input while the session is in progress.
+	 *
+	 * @example
+	 * ```ts
+	 * await cline.send(sessionId, {
+	 *   type: "user_message",
+	 *   text: "Please implement the login feature",
+	 * });
+	 * ```
+	 */
 	send: RuntimeHost["send"] = (...args) => this.host.send(...args);
+	pendingPrompts(
+		action: "list",
+		input: PendingPromptsListInput,
+	): Promise<SessionPendingPrompt[]>;
+	pendingPrompts(
+		action: "update",
+		input: PendingPromptsUpdateInput,
+	): Promise<PendingPromptMutationResult>;
+	pendingPrompts(
+		action: "delete",
+		input: PendingPromptsDeleteInput,
+	): Promise<PendingPromptMutationResult>;
+	pendingPrompts(
+		action: PendingPromptsAction,
+		input:
+			| PendingPromptsListInput
+			| PendingPromptsUpdateInput
+			| PendingPromptsDeleteInput,
+	): Promise<SessionPendingPrompt[] | PendingPromptMutationResult> {
+		switch (action) {
+			case "list":
+				return this.host.pendingPrompts(
+					"list",
+					input as PendingPromptsListInput,
+				);
+			case "update":
+				return this.host.pendingPrompts(
+					"update",
+					input as PendingPromptsUpdateInput,
+				);
+			case "delete":
+				return this.host.pendingPrompts(
+					"delete",
+					input as PendingPromptsDeleteInput,
+				);
+		}
+	}
+	/**
+	 * Retrieves accumulated token and cost usage for a session.
+	 *
+	 * Returns metrics about the session's resource consumption, including tokens used
+	 * across different API providers and associated costs. Useful for monitoring and billing.
+	 *
+	 * @example
+	 * ```ts
+	 * const usage = await cline.getAccumulatedUsage(sessionId);
+	 * console.log(`Total cost: $${usage.totalCost}`);
+	 * ```
+	 */
 	getAccumulatedUsage: RuntimeHost["getAccumulatedUsage"] = (...args) =>
 		this.host.getAccumulatedUsage(...args);
+	/**
+	 * Aborts an in-flight tool execution without stopping the session.
+	 *
+	 * Interrupts the current tool operation (e.g., file read, shell command) while keeping
+	 * the session alive. The session can continue processing after the abort. Use this for
+	 * cancelling long-running operations.
+	 *
+	 * @example
+	 * ```ts
+	 * // Stop the current operation but keep the session running
+	 * await cline.abort(sessionId);
+	 * ```
+	 */
 	abort: RuntimeHost["abort"] = (...args) => this.host.abort(...args);
+	/**
+	 * Stops an active session gracefully.
+	 *
+	 * Terminates the session and cleans up associated resources. Unlike abort, this
+	 * completely ends the session. The session cannot be resumed after stopping.
+	 *
+	 * @example
+	 * ```ts
+	 * // Cleanly shutdown the session
+	 * await cline.stop(sessionId);
+	 * ```
+	 */
 	stop: RuntimeHost["stop"] = async (sessionId) => {
 		await this.host.stop(sessionId);
 		await this.disposeSessionBootstrap(sessionId);
 	};
+	/**
+	 * Disposes the ClineCore instance and all associated resources.
+	 *
+	 * Shuts down the runtime host, closes connections, and cleans up all active sessions
+	 * and bootstraps. Call this when you're done using the SDK instance, typically at
+	 * application shutdown. After calling dispose, the instance cannot be reused.
+	 *
+	 * @example
+	 * ```ts
+	 * // Clean up when done
+	 * await cline.dispose();
+	 * ```
+	 */
 	dispose: RuntimeHost["dispose"] = async (...args) => {
 		try {
+			await this.automationService?.dispose();
 			await this.host.dispose(...args);
 		} finally {
 			this.unsubscribeBootstrapCleanup();
@@ -315,9 +874,65 @@ export class ClineCore implements RuntimeHost {
 			);
 		}
 	};
+	/**
+	 * Retrieves information about a specific session by ID.
+	 *
+	 * Fetches the current metadata and state of a session, including configuration,
+	 * status, and other session details.
+	 *
+	 * @example
+	 * ```ts
+	 * const session = await cline.get(sessionId);
+	 * console.log("Session status:", session?.status);
+	 * ```
+	 */
 	get: RuntimeHost["get"] = (...args) => this.host.get(...args);
-	list: RuntimeHost["list"] = async (limit = 200) =>
-		await hydrateSessionHistory(this.host, await this.host.list(limit));
+	/**
+	 * Lists recent sessions through the shared history-listing path.
+	 */
+	listHistory = async (
+		options: ClineCoreListHistoryOptions = {},
+	): Promise<SessionHistoryRecord[]> =>
+		await listSessionHistory(this.host, options);
+	/**
+	 * Lists recent sessions with inferred history display metadata.
+	 *
+	 * Retrieves a paginated list of recent sessions, optionally limited by the
+	 * provided count.
+	 *
+	 * @param limit Maximum number of sessions to return (defaults to 200)
+	 * @returns A promise resolving to an array of session history records
+	 *
+	 * @example
+	 * ```ts
+	 * const sessions = await cline.list(50);
+	 * sessions.forEach((session) => {
+	 *   console.log(`Session ${session.sessionId}: ${session.metadata?.title}`);
+	 * });
+	 * ```
+	 */
+	list = async (
+		limit = 200,
+		options: Omit<ClineCoreListHistoryOptions, "limit"> = {},
+	): Promise<SessionHistoryRecord[]> =>
+		await this.listHistory({ ...options, limit });
+	/**
+	 * Permanently deletes a session and all its associated data.
+	 *
+	 * Removes the session from storage and cleans up any related resources. This is
+	 * a destructive operation that cannot be undone.
+	 *
+	 * @param sessionId The ID of the session to delete
+	 * @returns A promise that resolves to true if the session was deleted, false if not found
+	 *
+	 * @example
+	 * ```ts
+	 * const deleted = await cline.delete(sessionId);
+	 * if (deleted) {
+	 *   console.log("Session deleted successfully");
+	 * }
+	 * ```
+	 */
 	delete: RuntimeHost["delete"] = async (sessionId) => {
 		const deleted = await this.host.delete(sessionId);
 		if (deleted) {
@@ -325,17 +940,87 @@ export class ClineCore implements RuntimeHost {
 		}
 		return deleted;
 	};
+	/**
+	 * Updates an existing session's metadata.
+	 *
+	 * Modifies session properties like title or other mutable metadata while preserving
+	 * message history and other session data.
+	 *
+	 * @example
+	 * ```ts
+	 * await cline.update(sessionId, {
+	 *   title: "Updated session title",
+	 * });
+	 * ```
+	 */
 	update: RuntimeHost["update"] = (...args) => this.host.update(...args);
+	/**
+	 * Reads message history for a session.
+	 *
+	 * Retrieves the full message transcript for a specific session, including all
+	 * user messages, agent responses, and tool interactions.
+	 *
+	 * @example
+	 * ```ts
+	 * const messages = await cline.readMessages(sessionId);
+	 * messages.forEach((msg) => {
+	 *   console.log(`${msg.role}: ${msg.content}`);
+	 * });
+	 * ```
+	 */
 	readMessages: RuntimeHost["readMessages"] = (...args) =>
 		this.host.readMessages(...args);
+	/**
+	 * Handles hook events from the runtime environment.
+	 *
+	 * Processes system or environment events (e.g., workspace changes, external signals)
+	 * that may affect the current session. This is typically called by the host environment
+	 * rather than directly by consumer code.
+	 *
+	 * @internal
+	 */
 	handleHookEvent: RuntimeHost["handleHookEvent"] = (...args) =>
 		this.host.handleHookEvent(...args);
+	/**
+	 * Subscribes to session events.
+	 *
+	 * Registers a listener for all session events (messages, state changes, errors, etc.).
+	 * Returns an unsubscribe function to stop listening.
+	 *
+	 * @param listener Callback function invoked for each event
+	 * @param options Optional configuration for the subscription
+	 * @returns An unsubscribe function
+	 *
+	 * @example
+	 * ```ts
+	 * const unsubscribe = cline.subscribe((event) => {
+	 *   if (event.type === "message") {
+	 *     console.log("New message:", event.payload.message);
+	 *   }
+	 * });
+	 *
+	 * // Later, stop listening
+	 * unsubscribe();
+	 * ```
+	 */
 	subscribe(
 		listener: (event: CoreSessionEvent) => void,
 		options?: RuntimeHostSubscribeOptions,
 	): () => void {
 		return this.host.subscribe(listener, options);
 	}
+	/**
+	 * Updates the AI model used by an active session.
+	 *
+	 * Switches the session to use a different AI model while maintaining the session state
+	 * and message history. This allows you to continue a conversation with a different model.
+	 *
+	 * @example
+	 * ```ts
+	 * // Switch to a different model mid-session
+	 * await cline.updateSessionModel(sessionId, "claude-opus-4-1");
+	 * ```
+	 */
 	updateSessionModel: RuntimeHost["updateSessionModel"] = (...args) =>
 		this.host.updateSessionModel?.(...args) ?? Promise.resolve();
 }