@clinebot/core 0.0.34 → 0.0.36

package/src/ClineCore.ts

@@ -1,39 +1,52 @@
 import type {
 	AgentConfig,
+	BasicLogger,
 	ITelemetryService,
 	ToolApprovalRequest,
 	ToolApprovalResult,
 } from "@clinebot/shared";
-import type { TeamToolsFactory } from "./runtime/session-runtime";
-import {
-	createSessionHost,
-	type SessionBackend,
-	type SessionHost,
-} from "./session/session-host";
-import type { StartSessionInput } from "./session/session-manager";
-import type { ToolExecutors } from "./tools";
+import type { ToolExecutors } from "./extensions/tools";
+import { hydrateSessionHistory } from "./runtime/history";
+import type { SessionBackend } from "./runtime/host";
+import { createRuntimeHost } from "./runtime/host";
+import type {
+	LocalRuntimeStartOptions,
+	RuntimeHost,
+	RuntimeHostMode,
+	RuntimeHostSubscribeOptions,
+	StartSessionInput,
+	StartSessionResult,
+} from "./runtime/runtime-host";
+import { splitCoreSessionConfig } from "./runtime/runtime-host";
+import type { CoreSessionConfig } from "./types/config";
+import type { CoreSessionEvent } from "./types/events";
+import type { SessionMessagesArtifactUploader } from "./types/session";
 
-/** Advanced options for connecting to or spawning the Cline RPC server. */
-export interface RpcOptions {
-	/**
-	 * The address of the Cline RPC server to connect to.
-	 * Defaults to the `CLINE_RPC_ADDRESS` env var, or the SDK default address if unset.
-	 */
-	address?: string;
-	/**
-	 * When `true` (default), automatically spawns a background RPC server process if one is
-	 * not already running.
-	 */
-	autoStart?: boolean;
-	/**
-	 * Number of connection attempts made to the RPC server after it is spawned.
-	 * Defaults to `5`.
-	 */
-	connectAttempts?: number;
-	/**
-	 * Milliseconds to wait between RPC connection attempts. Defaults to `100`.
-	 */
-	connectDelayMs?: number;
+export interface HubOptions {
+	endpoint?: string;
+	authToken?: string;
+	strategy?: "prefer-hub" | "require-hub";
+	clientType?: string;
+	displayName?: string;
+	workspaceRoot?: string;
+	cwd?: string;
+}
+
+export interface RemoteOptions {
+	endpoint: string;
+	authToken?: string;
+	clientType?: string;
+	displayName?: string;
+	workspaceRoot?: string;
+	cwd?: string;
+}
+
+export type { RuntimeHostMode };
+
+export interface ClineCoreStartInput
+	extends Omit<StartSessionInput, "config" | "localRuntime"> {
+	config: CoreSessionConfig;
+	localRuntime?: LocalRuntimeStartOptions;
 }
 
 export interface ClineCoreOptions {
@@ -49,17 +62,23 @@ export interface ClineCoreOptions {
 	 */
 	distinctId?: string;
 	/**
-	 * Controls how the session backend is selected:
-	 * - `"auto"` (default) — connects to a running RPC server if available, starts one in the
-	 *   background if `rpc.autoStart` is true, and falls back to local SQLite/file storage.
-	 * - `"rpc"` — requires an RPC server; throws if one is not reachable.
-	 * - `"local"` — always uses local SQLite (or file-based) storage; never touches RPC.
+	 * Controls how the runtime host is selected:
+	 * - `"auto"` (default) — prefers a compatible local hub when one is available and falls
+	 *   back to local in-process execution when not.
+	 * - `"hub"` — requires a compatible websocket hub runtime; throws if one is not reachable.
+	 * - `"remote"` — requires an explicit remote websocket hub endpoint.
+	 * - `"local"` — always uses local in-process execution and local SQLite/file storage.
 	 */
-	backendMode?: "auto" | "rpc" | "local";
+	backendMode?: RuntimeHostMode;
 	/**
-	 * RPC server connection options. Only relevant when `backendMode` is `"auto"` or `"rpc"`.
+	 * Hub runtime connection options. Used when `backendMode` is `"hub"` or when `"auto"`
+	 * should prefer a shared local hub if available.
 	 */
-	rpc?: RpcOptions;
+	hub?: HubOptions;
+	/**
+	 * Remote hub connection options. Only relevant when `backendMode` is `"remote"`.
+	 */
+	remote?: RemoteOptions;
 	/**
 	 * Override one or more default tool executors (e.g. file I/O, shell, browser).
 	 * Partial — only the keys you supply are replaced; the rest use built-in implementations.
@@ -70,6 +89,11 @@ export interface ClineCoreOptions {
 	 * If omitted, telemetry is a no-op.
 	 */
 	telemetry?: ITelemetryService;
+	/**
+	 * Optional structured logger for core-side operational diagnostics such as
+	 * runtime-host selection and fallback decisions.
+	 */
+	logger?: BasicLogger;
 	/**
 	 * Per-tool approval policies that control whether a tool runs automatically,
 	 * requires user confirmation, or is blocked entirely.
@@ -83,29 +107,45 @@ export interface ClineCoreOptions {
 	requestToolApproval?: (
 		request: ToolApprovalRequest,
 	) => Promise<ToolApprovalResult>;
+	/**
+	 * Optional hook invoked after `messages.json` is persisted to disk.
+	 * Consumers can use this to mirror session transcripts into remote storage.
+	 */
+	messagesArtifactUploader?: SessionMessagesArtifactUploader;
+	/**
+	 * Custom `fetch` implementation forwarded to the AI gateway providers used
+	 * by local sessions. When supplied, it is threaded into each
+	 * `ProviderConfig.fetch` built during session bootstrap, which in turn
+	 * populates `GatewayProviderSettings.fetch` (and the top-level
+	 * `GatewayConfig.fetch` fallback) so hosts can inject custom HTTP behavior
+	 * such as proxies, retries, tracing, or test doubles.
+	 *
+	 * Per-session or per-provider overrides still win: an explicit
+	 * `config.fetch` on `CoreSessionConfig` or a stored provider-level `fetch`
+	 * takes precedence over this default.
+	 *
+	 * Applies only to sessions executed in this process (local and fallback-
+	 * to-local auto mode). For hub and remote runtimes the HTTP call happens
+	 * inside the process that owns the gateway, so configure `fetch` there:
+	 *   - `startHubServer({ fetch })` / `ensureHubServer({ fetch })` from
+	 *     `@clinebot/hub`
+	 *   - `createLocalHubScheduleRuntimeHandlers({ fetch })` from
+	 *     `@clinebot/core/hub` for the scheduler
+	 */
+	fetch?: typeof fetch;
 	/**
 	 * An already-constructed session backend to use instead of resolving one automatically.
 	 * Intended for testing or embedding a custom persistence layer.
 	 * @internal
 	 */
 	sessionService?: SessionBackend;
-	/**
-	 * Factory that creates team management tools for the multi-agent team system.
-	 * When provided, team tools are registered whenever `enableAgentTeams` is `true`
-	 * on a session config.
-	 *
-	 * Consumers that depend on `@clinebot/enterprise` can pass
-	 * `bootstrapAgentTeams` here directly.
-	 */
-	teamToolsFactory?: TeamToolsFactory;
 	/**
 	 * Optional hook invoked before each session starts.
 	 * Use this to prepare workspace-scoped runtime state and then return an
-	 * adapter that mutates the `StartSessionInput` generically before core
-	 * builds the runtime.
+	 * adapter that mutates the shared session input before core starts the run.
 	 */
 	prepare?: (
-		input: StartSessionInput,
+		input: ClineCoreStartInput,
 	) =>
 		| Promise<StartSessionBootstrap | undefined>
 		| StartSessionBootstrap
@@ -114,8 +154,8 @@ export interface ClineCoreOptions {
 
 export interface StartSessionBootstrap {
 	applyToStartSessionInput(
-		input: StartSessionInput,
-	): Promise<StartSessionInput> | StartSessionInput;
+		input: ClineCoreStartInput,
+	): Promise<ClineCoreStartInput> | ClineCoreStartInput;
 	dispose?(): Promise<void> | void;
 }
 
@@ -130,11 +170,12 @@ export interface StartSessionBootstrap {
  * const session = await cline.start({ ... });
  * ```
  */
-export class ClineCore implements SessionHost {
+export class ClineCore implements RuntimeHost {
 	readonly clientName: string | undefined;
-	private readonly host: SessionHost;
+	readonly runtimeAddress: string | undefined;
+	private readonly host: RuntimeHost;
 	private readonly prepare: ClineCoreOptions["prepare"] | undefined;
-	private readonly teamToolsFactory: TeamToolsFactory | undefined;
+	private readonly defaultToolExecutors: Partial<ToolExecutors> | undefined;
 	private readonly activeSessionBootstraps = new Map<
 		string,
 		StartSessionBootstrap
@@ -142,15 +183,17 @@ export class ClineCore implements SessionHost {
 	private readonly unsubscribeBootstrapCleanup: () => void;
 
 	private constructor(
-		host: SessionHost,
+		host: RuntimeHost,
 		clientName: string | undefined,
+		runtimeAddress: string | undefined,
 		prepare: ClineCoreOptions["prepare"],
-		teamToolsFactory: TeamToolsFactory | undefined,
+		defaultToolExecutors: Partial<ToolExecutors> | undefined,
 	) {
 		this.clientName = clientName;
+		this.runtimeAddress = runtimeAddress;
 		this.host = host;
 		this.prepare = prepare;
-		this.teamToolsFactory = teamToolsFactory;
+		this.defaultToolExecutors = defaultToolExecutors;
 		this.unsubscribeBootstrapCleanup = this.host.subscribe((event) => {
 			if (event.type !== "ended") {
 				return;
@@ -160,12 +203,13 @@ export class ClineCore implements SessionHost {
 	}
 
 	static async create(options: ClineCoreOptions = {}): Promise<ClineCore> {
-		const host = await createSessionHost(options);
+		const host = await createRuntimeHost(options);
 		return new ClineCore(
 			host,
 			options.clientName,
+			host.runtimeAddress,
 			options.prepare,
-			options.teamToolsFactory,
+			options.defaultToolExecutors,
 		);
 	}
 
@@ -178,16 +222,66 @@ export class ClineCore implements SessionHost {
 		await Promise.resolve(bootstrap.dispose?.());
 	}
 
-	start: SessionHost["start"] = async (input) => {
-		const inputWithFactory: StartSessionInput = this.teamToolsFactory
-			? { teamToolsFactory: this.teamToolsFactory, ...input }
-			: input;
-		const bootstrap = await this.prepare?.(inputWithFactory);
+	private toClineCoreStartInput(
+		input: StartSessionInput | ClineCoreStartInput,
+	): ClineCoreStartInput {
+		const config = input.config as CoreSessionConfig;
+		return "providerId" in config
+			? {
+					...input,
+					config: {
+						...config,
+						...(input.localRuntime?.configOverrides ?? {}),
+					},
+					localRuntime: input.localRuntime
+						? {
+								...input.localRuntime,
+								configOverrides: input.localRuntime.configOverrides,
+							}
+						: undefined,
+				}
+			: (input as ClineCoreStartInput);
+	}
+
+	private normalizeStartInput(input: ClineCoreStartInput): StartSessionInput {
+		const split = splitCoreSessionConfig(input.config);
+		const localRuntime =
+			split.localRuntime || input.localRuntime || this.defaultToolExecutors
+				? {
+						...(split.localRuntime ?? {}),
+						...(input.localRuntime ?? {}),
+						configOverrides: {
+							...(split.localRuntime?.configOverrides ?? {}),
+							...(input.localRuntime?.configOverrides ?? {}),
+						},
+						defaultToolExecutors: {
+							...(this.defaultToolExecutors ?? {}),
+							...(split.localRuntime?.defaultToolExecutors ?? {}),
+							...(input.localRuntime?.defaultToolExecutors ?? {}),
+						},
+					}
+				: undefined;
+		return {
+			...input,
+			...split,
+			...(localRuntime ? { localRuntime } : {}),
+		};
+	}
+
+	start(input: StartSessionInput): Promise<StartSessionResult>;
+	start(input: ClineCoreStartInput): Promise<StartSessionResult>;
+	async start(
+		input: StartSessionInput | ClineCoreStartInput,
+	): Promise<StartSessionResult> {
+		const clineCoreInput = this.toClineCoreStartInput(input);
+		const bootstrap = await this.prepare?.(clineCoreInput);
 		try {
-			const effectiveInput = bootstrap
-				? await bootstrap.applyToStartSessionInput(inputWithFactory)
-				: inputWithFactory;
-			const result = await this.host.start(effectiveInput);
+			const preparedInput = bootstrap
+				? await bootstrap.applyToStartSessionInput(clineCoreInput)
+				: clineCoreInput;
+			const result = await this.host.start(
+				this.normalizeStartInput(preparedInput),
+			);
 			if (bootstrap) {
 				const activeSession = await this.host.get(result.sessionId);
 				if (activeSession) {
@@ -201,16 +295,16 @@ export class ClineCore implements SessionHost {
 			await Promise.resolve(bootstrap?.dispose?.());
 			throw error;
 		}
-	};
-	send: SessionHost["send"] = (...args) => this.host.send(...args);
-	getAccumulatedUsage: SessionHost["getAccumulatedUsage"] = (...args) =>
+	}
+	send: RuntimeHost["send"] = (...args) => this.host.send(...args);
+	getAccumulatedUsage: RuntimeHost["getAccumulatedUsage"] = (...args) =>
 		this.host.getAccumulatedUsage(...args);
-	abort: SessionHost["abort"] = (...args) => this.host.abort(...args);
-	stop: SessionHost["stop"] = async (sessionId) => {
+	abort: RuntimeHost["abort"] = (...args) => this.host.abort(...args);
+	stop: RuntimeHost["stop"] = async (sessionId) => {
 		await this.host.stop(sessionId);
 		await this.disposeSessionBootstrap(sessionId);
 	};
-	dispose: SessionHost["dispose"] = async (...args) => {
+	dispose: RuntimeHost["dispose"] = async (...args) => {
 		try {
 			await this.host.dispose(...args);
 		} finally {
@@ -221,23 +315,27 @@ export class ClineCore implements SessionHost {
 			);
 		}
 	};
-	get: SessionHost["get"] = (...args) => this.host.get(...args);
-	list: SessionHost["list"] = (...args) => this.host.list(...args);
-	delete: SessionHost["delete"] = async (sessionId) => {
+	get: RuntimeHost["get"] = (...args) => this.host.get(...args);
+	list: RuntimeHost["list"] = async (limit = 200) =>
+		await hydrateSessionHistory(this.host, await this.host.list(limit));
+	delete: RuntimeHost["delete"] = async (sessionId) => {
 		const deleted = await this.host.delete(sessionId);
 		if (deleted) {
 			await this.disposeSessionBootstrap(sessionId);
 		}
 		return deleted;
 	};
-	readMessages: SessionHost["readMessages"] = (...args) =>
+	update: RuntimeHost["update"] = (...args) => this.host.update(...args);
+	readMessages: RuntimeHost["readMessages"] = (...args) =>
 		this.host.readMessages(...args);
-	readTranscript: SessionHost["readTranscript"] = (...args) =>
-		this.host.readTranscript(...args);
-	readHooks: SessionHost["readHooks"] = (...args) =>
-		this.host.readHooks(...args);
-	subscribe: SessionHost["subscribe"] = (...args) =>
-		this.host.subscribe(...args);
-	updateSessionModel: SessionHost["updateSessionModel"] = (...args) =>
+	handleHookEvent: RuntimeHost["handleHookEvent"] = (...args) =>
+		this.host.handleHookEvent(...args);
+	subscribe(
+		listener: (event: CoreSessionEvent) => void,
+		options?: RuntimeHostSubscribeOptions,
+	): () => void {
+		return this.host.subscribe(listener, options);
+	}
+	updateSessionModel: RuntimeHost["updateSessionModel"] = (...args) =>
 		this.host.updateSessionModel?.(...args) ?? Promise.resolve();
 }

package/src/account/index.ts

@@ -4,10 +4,10 @@ export {
 } from "./cline-account-service";
 export {
 	type ClineAccountOperations,
-	executeRpcClineAccountAction,
-	isRpcClineAccountActionRequest,
+	executeClineAccountAction,
+	isClineAccountActionRequest,
+	type ProviderActionExecutor,
 	RpcClineAccountService,
-	type RpcProviderActionExecutor,
 } from "./rpc";
 export type {
 	ClineAccountBalance,

package/src/account/rpc.ts

@@ -1,6 +1,6 @@
 import type {
-	RpcClineAccountActionRequest,
-	RpcProviderActionRequest,
+	ClineAccountActionRequest,
+	ProviderActionRequest,
 } from "@clinebot/shared";
 import type {
 	ClineAccountBalance,
@@ -34,14 +34,14 @@ export interface ClineAccountOperations {
 	fetchFeaturebaseToken?(): Promise<FeaturebaseTokenResponse | undefined>;
 }
 
-export function isRpcClineAccountActionRequest(
-	request: RpcProviderActionRequest,
-): request is RpcClineAccountActionRequest {
+export function isClineAccountActionRequest(
+	request: ProviderActionRequest,
+): request is ClineAccountActionRequest {
 	return request.action === "clineAccount";
 }
 
-export async function executeRpcClineAccountAction(
-	request: RpcClineAccountActionRequest,
+export async function executeClineAccountAction(
+	request: ClineAccountActionRequest,
 	service: ClineAccountOperations,
 ): Promise<unknown> {
 	switch (request.operation) {
@@ -76,16 +76,16 @@ export async function executeRpcClineAccountAction(
 	}
 }
 
-export interface RpcProviderActionExecutor {
-	runProviderAction(request: RpcProviderActionRequest): Promise<{
+export interface ProviderActionExecutor {
+	runProviderAction(request: ProviderActionRequest): Promise<{
 		result: unknown;
 	}>;
 }
 
 export class RpcClineAccountService implements ClineAccountOperations {
-	private readonly executor: RpcProviderActionExecutor;
+	private readonly executor: ProviderActionExecutor;
 
-	constructor(executor: RpcProviderActionExecutor) {
+	constructor(executor: ProviderActionExecutor) {
 		this.executor = executor;
 	}
 
@@ -178,7 +178,7 @@ export class RpcClineAccountService implements ClineAccountOperations {
 		});
 	}
 
-	private async request<T>(request: RpcClineAccountActionRequest): Promise<T> {
+	private async request<T>(request: ClineAccountActionRequest): Promise<T> {
 		const response = await this.executor.runProviderAction(request);
 		return response.result as T;
 	}

package/src/auth/cline.ts

@@ -5,7 +5,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { startLocalOAuthServer } from "./server";
 import type {
 	OAuthCredentials,

package/src/auth/codex.ts

@@ -13,7 +13,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { startLocalOAuthServer } from "./server";
 import type {
 	OAuthCredentials,

package/src/auth/oca.ts

@@ -6,7 +6,7 @@ import {
 	captureAuthStarted,
 	captureAuthSucceeded,
 	identifyAccount,
-} from "../telemetry/core-events";
+} from "../services/telemetry/core-events";
 import { BoundedTtlCache } from "./bounded-ttl-cache";
 import { startLocalOAuthServer } from "./server";
 import type {

package/src/cron/index.ts

@@ -0,0 +1,5 @@
+export * from "./resource-limiter";
+export * from "./schedule-command-service";
+export * from "./schedule-service";
+export * from "./scheduler";
+export * from "./sqlite-schedule-store";

package/src/cron/resource-limiter.ts

@@ -0,0 +1,46 @@
+export class ResourceLimiter {
+	private readonly globalMaxConcurrency: number;
+	private readonly activeExecutions = new Map<string, Set<string>>();
+
+	constructor(globalMaxConcurrency: number) {
+		this.globalMaxConcurrency = Math.max(1, Math.floor(globalMaxConcurrency));
+	}
+
+	public acquire(
+		scheduleId: string,
+		executionId: string,
+		maxParallel: number,
+	): boolean {
+		if (this.getGlobalActiveCount() >= this.globalMaxConcurrency) {
+			return false;
+		}
+		const perScheduleLimit = Math.max(1, Math.floor(maxParallel));
+		const scheduleExecutions =
+			this.activeExecutions.get(scheduleId) ?? new Set<string>();
+		if (scheduleExecutions.size >= perScheduleLimit) {
+			return false;
+		}
+		scheduleExecutions.add(executionId);
+		this.activeExecutions.set(scheduleId, scheduleExecutions);
+		return true;
+	}
+
+	public release(scheduleId: string, executionId: string): void {
+		const executions = this.activeExecutions.get(scheduleId);
+		if (!executions) {
+			return;
+		}
+		executions.delete(executionId);
+		if (executions.size === 0) {
+			this.activeExecutions.delete(scheduleId);
+		}
+	}
+
+	public getGlobalActiveCount(): number {
+		let total = 0;
+		for (const executions of this.activeExecutions.values()) {
+			total += executions.size;
+		}
+		return total;
+	}
+}