@clinebot/core 0.0.33 → 0.0.35

package/dist/types.d.ts

@@ -1,21 +1,22 @@
 export type { WorkspaceInfo, WorkspaceManifest } from "@clinebot/shared";
-export { ClineCore, type ClineCoreOptions, type RpcOptions, } from "./ClineCore";
-export type { ChatMessage, ChatSessionConfig, ChatSessionStatus, ChatSummary, ChatViewState, } from "./chat/chat-schema";
+export { ClineCore, type ClineCoreOptions, type ClineCoreStartInput, type RpcOptions, } from "./ClineCore";
 export type { LoadAgentPluginFromPathOptions, ResolveAgentPluginPathsOptions, } from "./extensions";
 export { discoverPluginModulePaths, loadAgentPluginFromPath, loadAgentPluginsFromPaths, resolveAgentPluginPaths, resolveAndLoadAgentPlugins, resolvePluginConfigSearchPaths, } from "./extensions";
 export type { AgentConfigWatcher, AgentConfigWatcherEvent, AgentYamlConfig, BuildAgentConfigOverridesOptions, CreateAgentConfigWatcherOptions, CreateInstructionWatcherOptions, CreateRulesConfigDefinitionOptions, CreateSkillsConfigDefinitionOptions, CreateUserInstructionConfigWatcherOptions, CreateWorkflowsConfigDefinitionOptions, ParseMarkdownFrontmatterResult, ParseYamlFrontmatterResult, RuleConfig, SkillConfig, UnifiedConfigDefinition, UnifiedConfigFileCandidate, UnifiedConfigFileContext, UnifiedConfigRecord, UnifiedConfigWatcherEvent, UnifiedConfigWatcherOptions, UserInstructionConfig, UserInstructionConfigType, UserInstructionConfigWatcher, UserInstructionConfigWatcherEvent, WorkflowConfig, } from "./extensions/config";
-export { createAgentConfigDefinition, createAgentConfigWatcher, createRulesConfigDefinition, createSkillsConfigDefinition, createUserInstructionConfigWatcher, createWorkflowsConfigDefinition, parseAgentConfigFromYaml, parsePartialAgentConfigFromYaml, parseRuleConfigFromMarkdown, parseSkillConfigFromMarkdown, parseWorkflowConfigFromMarkdown, RULES_CONFIG_DIRECTORY_NAME, resolveAgentTools, resolveDocumentsRulesDirectoryPath, resolveDocumentsWorkflowsDirectoryPath, resolveRulesConfigSearchPaths, resolveSkillsConfigSearchPaths, resolveWorkflowsConfigSearchPaths, SKILLS_CONFIG_DIRECTORY_NAME, toPartialAgentConfig, UnifiedConfigFileWatcher, WORKFLOWS_CONFIG_DIRECTORY_NAME, } from "./extensions/config";
+export { createAgentConfigDefinition, createAgentConfigWatcher, createRulesConfigDefinition, createSkillsConfigDefinition, createUserInstructionConfigWatcher, createWorkflowsConfigDefinition, parseAgentConfigFromYaml, parsePartialAgentConfigFromYaml, parseRuleConfigFromMarkdown, parseSkillConfigFromMarkdown, parseWorkflowConfigFromMarkdown, RULES_CONFIG_DIRECTORY_NAME, resolveAgentTools, resolveRulesConfigSearchPaths, resolveSkillsConfigSearchPaths, resolveWorkflowsConfigSearchPaths, SKILLS_CONFIG_DIRECTORY_NAME, toPartialAgentConfig, UnifiedConfigFileWatcher, WORKFLOWS_CONFIG_DIRECTORY_NAME, } from "./extensions/config";
+export type { SessionBackend } from "./runtime/host";
+export type { RuntimeHost, RuntimeHost as SessionHost, RuntimeHostMode, SendSessionInput, SessionAccumulatedUsage, StartSessionInput, StartSessionResult, } from "./runtime/runtime-host";
 export type { BuiltRuntime as RuntimeEnvironment, RuntimeBuilder, RuntimeBuilderInput, SessionRuntime, } from "./runtime/session-runtime";
 export type { SandboxCallOptions, SubprocessSandboxOptions, } from "./runtime/subprocess-sandbox";
 export { SubprocessSandbox } from "./runtime/subprocess-sandbox";
-export type { SessionHost } from "./session/session-host";
-export type { SendSessionInput, SessionAccumulatedUsage, SessionManager, StartSessionInput, StartSessionResult, } from "./session/session-manager";
 export type { SessionManifest } from "./session/session-manifest";
 export type { CreateRootSessionWithArtifactsInput, RootSessionArtifacts, } from "./session/session-service";
 export type { WorkspaceManager, WorkspaceManagerEvent, } from "./session/workspace-manager";
+export type { ChatMessage, ChatSessionConfig, ChatSessionStatus, ChatSummary, ChatViewState, } from "./types/chat-schema";
 export type { SessionSource, SessionStatus } from "./types/common";
 export type { CoreAgentMode, CoreModelConfig, CoreRuntimeFeatures, CoreSessionConfig, } from "./types/config";
 export type { CoreSessionEvent, SessionChunkEvent, SessionEndedEvent, SessionTeamProgressEvent, SessionToolEvent, } from "./types/events";
-export type { SessionRecord, SessionRef } from "./types/sessions";
+export type { SessionMessagesArtifactUploader } from "./types/session";
+export type { SessionHistoryMetadata, SessionHistoryRecord, SessionRecord, SessionRef, } from "./types/sessions";
 export type { ArtifactStore, SessionStore, TeamStore } from "./types/storage";
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACN,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,UAAU,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACX,8BAA8B,EAC9B,8BAA8B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,GAC9B,MAAM,cAAc,CAAC;AACtB,YAAY,EACX,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,gCAAgC,EAChC,+BAA+B,EAC/B,+BAA+B,EAC/B,kCAAkC,EAClC,mCAAmC,EACnC,yCAAyC,EACzC,sCAAsC,EACtC,8BAA8B,EAC9B,0BAA0B,EAC1B,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,iCAAiC,EACjC,cAAc,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,EAClC,+BAA+B,EAC/B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,2BAA2B,EAC3B,iBAAiB,EACjB,kCAAkC,EAClC,sCAAsC,EACtC,6BAA6B,EAC7B,8BAA8B,EAC9B,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,+BAA+B,GAC/B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACX,YAAY,IAAI,kBAAkB,EAClC,cAAc,EACd,mBAAmB,EACnB,cAAc,GACd,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACX,kBAAkB,EAClB,wBAAwB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACX,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,YAAY,EACX,mCAAmC,EACnC,oBAAoB,GACpB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACX,gBAAgB,EAChB,qBAAqB,GACrB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EACX,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACN,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,UAAU,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,8BAA8B,EAC9B,8BAA8B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,GAC9B,MAAM,cAAc,CAAC;AACtB,YAAY,EACX,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,gCAAgC,EAChC,+BAA+B,EAC/B,+BAA+B,EAC/B,kCAAkC,EAClC,mCAAmC,EACnC,yCAAyC,EACzC,sCAAsC,EACtC,8BAA8B,EAC9B,0BAA0B,EAC1B,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,iCAAiC,EACjC,cAAc,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,EAC5B,kCAAkC,EAClC,+BAA+B,EAC/B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,8BAA8B,EAC9B,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,wBAAwB,EACxB,+BAA+B,GAC/B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACX,WAAW,EACX,WAAW,IAAI,WAAW,EAC1B,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACX,YAAY,IAAI,kBAAkB,EAClC,cAAc,EACd,mBAAmB,EACnB,cAAc,GACd,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACX,kBAAkB,EAClB,wBAAwB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,YAAY,EACX,mCAAmC,EACnC,oBAAoB,GACpB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACX,gBAAgB,EAChB,qBAAqB,GACrB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACX,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EACX,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AACvE,YAAY,EACX,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,EACb,UAAU,GACV,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@clinebot/core",
 	"description": "Cline Core SDK for Node Runtime",
-	"version": "0.0.33",
+	"version": "0.0.35",
 	"type": "module",
 	"types": "./dist/index.d.ts",
 	"main": "./dist/index.js",
@@ -15,15 +15,10 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
 		},
-		"./node": {
-			"development": "./src/index.ts",
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
 		"./telemetry": {
-			"development": "./src/telemetry/index.ts",
-			"types": "./dist/telemetry/index.d.ts",
-			"import": "./dist/telemetry/index.js"
+			"development": "./src/services/telemetry/index.ts",
+			"types": "./dist/services/telemetry/index.d.ts",
+			"import": "./dist/services/telemetry/index.js"
 		}
 	},
 	"scripts": {
@@ -36,8 +31,8 @@
 		"test:watch": "vitest --config vitest.config.ts"
 	},
 	"dependencies": {
-		"@clinebot/agents": "0.0.33",
-		"@clinebot/llms": "0.0.33",
+		"@clinebot/agents": "0.0.35",
+		"@clinebot/llms": "0.0.35",
 		"@opentelemetry/api": "^1.9.0",
 		"@opentelemetry/api-logs": "^0.214.0",
 		"@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
@@ -58,7 +53,7 @@
 	},
 	"devDependencies": {
 		"@clinebot/rpc": "0.0.28",
-		"@clinebot/shared": "0.0.33"
+		"@clinebot/shared": "0.0.35"
 	},
 	"engines": {
 		"node": ">=22"

package/src/ClineCore.test.ts

@@ -1,20 +1,21 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClineCoreStartInput } from "./ClineCore";
 import type {
 	StartSessionInput,
 	StartSessionResult,
-} from "./session/session-manager";
+} from "./runtime/runtime-host";
 
-const { createSessionHostMock } = vi.hoisted(() => ({
-	createSessionHostMock: vi.fn(),
+const { createRuntimeHostMock } = vi.hoisted(() => ({
+	createRuntimeHostMock: vi.fn(),
 }));
 
-vi.mock("./session/session-host", () => ({
-	createSessionHost: createSessionHostMock,
+vi.mock("./runtime/host", () => ({
+	createRuntimeHost: createRuntimeHostMock,
 }));
 
 import { ClineCore } from "./ClineCore";
 
-function createStartInput(): StartSessionInput {
+function createStartInput(): ClineCoreStartInput {
 	return {
 		config: {
 			providerId: "anthropic",
@@ -23,6 +24,7 @@ function createStartInput(): StartSessionInput {
 			cwd: "/tmp/workspace",
 			workspaceRoot: "/tmp/workspace",
 			systemPrompt: "You are concise.",
+			mode: "act",
 			enableTools: true,
 			enableSpawnAgent: false,
 			enableAgentTeams: false,
@@ -37,15 +39,13 @@ function createStartResult(sessionId: string): StartSessionResult {
 		sessionId,
 		manifest: {} as StartSessionResult["manifest"],
 		manifestPath: `/tmp/${sessionId}.json`,
-		transcriptPath: `/tmp/${sessionId}.log`,
-		hookPath: `/tmp/${sessionId}.hooks.jsonl`,
 		messagesPath: `/tmp/${sessionId}.messages.json`,
 	};
 }
 
 describe("ClineCore", () => {
 	beforeEach(() => {
-		createSessionHostMock.mockReset();
+		createRuntimeHostMock.mockReset();
 	});
 
 	it("applies start-session bootstraps before delegating to the host", async () => {
@@ -53,9 +53,12 @@ describe("ClineCore", () => {
 			(event: { type: string; payload: { sessionId: string } }) => void
 		> = [];
 		const host = {
+			runtimeAddress: undefined,
 			start: vi.fn(async (input: StartSessionInput) => {
 				expect(input.config.systemPrompt).toBe("Bootstrapped prompt");
-				expect(input.config.extensions).toEqual([{ name: "enterprise" }]);
+				expect(input.localRuntime?.configOverrides?.extensions).toEqual([
+					expect.objectContaining({ name: "enterprise" }),
+				]);
 				return createStartResult("session-1");
 			}),
 			send: vi.fn(),
@@ -67,26 +70,28 @@ describe("ClineCore", () => {
 			list: vi.fn(),
 			delete: vi.fn(),
 			readMessages: vi.fn(),
-			readTranscript: vi.fn(),
-			readHooks: vi.fn(),
 			subscribe: vi.fn((listener) => {
 				listeners.push(listener);
 				return () => {};
 			}),
 			updateSessionModel: vi.fn(),
 		};
-		createSessionHostMock.mockResolvedValue(host);
+		createRuntimeHostMock.mockResolvedValue(host);
 
 		const dispose = vi.fn(async () => {});
 		const applyToStartSessionInput = vi.fn(
-			async (input: StartSessionInput) => ({
+			async (input: ClineCoreStartInput) => ({
 				...input,
 				config: {
 					...input.config,
 					systemPrompt: "Bootstrapped prompt",
 					extensions: [
-						{ name: "enterprise" },
-					] as StartSessionInput["config"]["extensions"],
+						{
+							name: "enterprise",
+							manifest: { capabilities: [] },
+							setup: vi.fn(),
+						},
+					],
 				},
 			}),
 		);
@@ -111,6 +116,7 @@ describe("ClineCore", () => {
 			| ((event: { type: string; payload: { sessionId: string } }) => void)
 			| undefined;
 		const host = {
+			runtimeAddress: "127.0.0.1:5317",
 			start: vi.fn(async () => createStartResult("session-2")),
 			send: vi.fn(),
 			getAccumulatedUsage: vi.fn(),
@@ -121,15 +127,13 @@ describe("ClineCore", () => {
 			list: vi.fn(),
 			delete: vi.fn(),
 			readMessages: vi.fn(),
-			readTranscript: vi.fn(),
-			readHooks: vi.fn(),
 			subscribe: vi.fn((nextListener) => {
 				listener = nextListener;
 				return () => {};
 			}),
 			updateSessionModel: vi.fn(),
 		};
-		createSessionHostMock.mockResolvedValue(host);
+		createRuntimeHostMock.mockResolvedValue(host);
 
 		const dispose = vi.fn(async () => {});
 		const core = await ClineCore.create({
@@ -138,6 +142,7 @@ describe("ClineCore", () => {
 				dispose,
 			}),
 		});
+		expect(core.runtimeAddress).toBe("127.0.0.1:5317");
 
 		await core.start(createStartInput());
 		expect(dispose).not.toHaveBeenCalled();
@@ -147,4 +152,75 @@ describe("ClineCore", () => {
 
 		expect(dispose).toHaveBeenCalledTimes(1);
 	});
+
+	it("hydrates list rows through the core API", async () => {
+		const host = {
+			runtimeAddress: undefined,
+			start: vi.fn(),
+			send: vi.fn(),
+			getAccumulatedUsage: vi.fn(),
+			abort: vi.fn(),
+			stop: vi.fn(),
+			dispose: vi.fn(),
+			get: vi.fn(async () => undefined),
+			list: vi.fn(async () => [
+				{
+					sessionId: "session-3",
+					source: "cli",
+					pid: 1,
+					startedAt: "2026-04-21T02:17:46.169Z",
+					status: "completed",
+					interactive: false,
+					provider: "",
+					model: "",
+					cwd: "/tmp/workspace",
+					workspaceRoot: "/tmp/workspace",
+					enableTools: true,
+					enableSpawn: false,
+					enableTeams: false,
+					prompt: "hello",
+					metadata: {},
+					updatedAt: "2026-04-21T02:17:46.169Z",
+				},
+			]),
+			delete: vi.fn(),
+			update: vi.fn(),
+			readMessages: vi.fn(async () => [
+				{
+					role: "user",
+					content: [{ type: "text", text: "hello" }],
+				},
+				{
+					role: "assistant",
+					content: [{ type: "text", text: "hi" }],
+					modelInfo: {
+						provider: "cline",
+						id: "anthropic/claude-sonnet-4.6",
+					},
+					metrics: {
+						cost: 0.02,
+					},
+				},
+			]),
+			handleHookEvent: vi.fn(),
+			subscribe: vi.fn(() => () => {}),
+			updateSessionModel: vi.fn(),
+		};
+		createRuntimeHostMock.mockResolvedValue(host);
+
+		const core = await ClineCore.create();
+		const [row] = await core.list(10);
+
+		expect(host.list).toHaveBeenCalledWith(10);
+		expect(host.readMessages).toHaveBeenCalledWith("session-3");
+		expect(row).toMatchObject({
+			sessionId: "session-3",
+			provider: "cline",
+			model: "anthropic/claude-sonnet-4.6",
+			metadata: {
+				title: "hello",
+				totalCost: 0.02,
+			},
+		});
+	});
 });

package/src/ClineCore.ts

@@ -1,17 +1,25 @@
 import type {
 	AgentConfig,
+	BasicLogger,
 	ITelemetryService,
 	ToolApprovalRequest,
 	ToolApprovalResult,
 } from "@clinebot/shared";
+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,
+	StartSessionInput,
+	StartSessionResult,
+} from "./runtime/runtime-host";
+import { splitCoreSessionConfig } from "./runtime/runtime-host";
 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 { CoreSessionConfig } from "./types/config";
+import type { SessionMessagesArtifactUploader } from "./types/session";
 
 /** Advanced options for connecting to or spawning the Cline RPC server. */
 export interface RpcOptions {
@@ -36,6 +44,14 @@ export interface RpcOptions {
 	connectDelayMs?: number;
 }
 
+export type { RuntimeHostMode };
+
+export interface ClineCoreStartInput
+	extends Omit<StartSessionInput, "config" | "localRuntime"> {
+	config: CoreSessionConfig;
+	localRuntime?: LocalRuntimeStartOptions;
+}
+
 export interface ClineCoreOptions {
 	/**
 	 * A human-readable name for this SDK client (e.g. `"my-app"`, `"acme-bot"`).
@@ -49,13 +65,13 @@ export interface ClineCoreOptions {
 	 */
 	distinctId?: string;
 	/**
-	 * Controls how the session backend is selected:
+	 * Controls how the runtime host 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.
+	 *   background if `rpc.autoStart` is true, and falls back to local in-process execution.
+	 * - `"rpc"` — requires an RPC runtime server; throws if one is not reachable.
+	 * - `"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"`.
 	 */
@@ -70,6 +86,11 @@ export interface ClineCoreOptions {
 	 * If omitted, telemetry is a no-op.
 	 */
 	telemetry?: ITelemetryService;
+	/**
+	 * Optional structured logger for core-side operational diagnostics such as
+	 * RPC backend startup, reuse, and fallback decisions.
+	 */
+	logger?: BasicLogger;
 	/**
 	 * Per-tool approval policies that control whether a tool runs automatically,
 	 * requires user confirmation, or is blocked entirely.
@@ -83,6 +104,11 @@ 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;
 	/**
 	 * An already-constructed session backend to use instead of resolving one automatically.
 	 * Intended for testing or embedding a custom persistence layer.
@@ -101,11 +127,10 @@ export interface ClineCoreOptions {
 	/**
 	 * 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 +139,8 @@ export interface ClineCoreOptions {
 
 export interface StartSessionBootstrap {
 	applyToStartSessionInput(
-		input: StartSessionInput,
-	): Promise<StartSessionInput> | StartSessionInput;
+		input: ClineCoreStartInput,
+	): Promise<ClineCoreStartInput> | ClineCoreStartInput;
 	dispose?(): Promise<void> | void;
 }
 
@@ -130,11 +155,11 @@ 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 activeSessionBootstraps = new Map<
 		string,
 		StartSessionBootstrap
@@ -142,15 +167,15 @@ 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,
 	) {
 		this.clientName = clientName;
+		this.runtimeAddress = runtimeAddress;
 		this.host = host;
 		this.prepare = prepare;
-		this.teamToolsFactory = teamToolsFactory;
 		this.unsubscribeBootstrapCleanup = this.host.subscribe((event) => {
 			if (event.type !== "ended") {
 				return;
@@ -160,12 +185,12 @@ 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,
 		);
 	}
 
@@ -178,16 +203,61 @@ 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
+				? {
+						...(split.localRuntime ?? {}),
+						...(input.localRuntime ?? {}),
+						configOverrides: {
+							...(split.localRuntime?.configOverrides ?? {}),
+							...(input.localRuntime?.configOverrides ?? {}),
+						},
+					}
+				: 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 +271,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 +291,23 @@ 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) =>
+	handleHookEvent: RuntimeHost["handleHookEvent"] = (...args) =>
+		this.host.handleHookEvent(...args);
+	subscribe: RuntimeHost["subscribe"] = (...args) =>
 		this.host.subscribe(...args);
-	updateSessionModel: SessionHost["updateSessionModel"] = (...args) =>
+	updateSessionModel: RuntimeHost["updateSessionModel"] = (...args) =>
 		this.host.updateSessionModel?.(...args) ?? Promise.resolve();
 }

package/src/auth/client.test.ts

@@ -37,4 +37,33 @@ describe("auth/client createOAuthClientCallbacks", () => {
 			url: "https://example.com/auth",
 		});
 	});
+
+	it("forwards onServerListening to the returned callbacks", () => {
+		const onServerListening = vi.fn();
+		const callbacks = createOAuthClientCallbacks({
+			onPrompt: vi.fn().mockResolvedValue(""),
+			onServerListening,
+		});
+
+		expect(callbacks.onServerListening).toBe(onServerListening);
+	});
+
+	it("forwards onServerClose to the returned callbacks", () => {
+		const onServerClose = vi.fn();
+		const callbacks = createOAuthClientCallbacks({
+			onPrompt: vi.fn().mockResolvedValue(""),
+			onServerClose,
+		});
+
+		expect(callbacks.onServerClose).toBe(onServerClose);
+	});
+
+	it("leaves onServerListening and onServerClose undefined when not provided", () => {
+		const callbacks = createOAuthClientCallbacks({
+			onPrompt: vi.fn().mockResolvedValue(""),
+		});
+
+		expect(callbacks.onServerListening).toBeUndefined();
+		expect(callbacks.onServerClose).toBeUndefined();
+	});
 });

package/src/auth/client.ts

@@ -1,3 +1,4 @@
+import type { OAuthServerCloseInfo, OAuthServerListeningInfo } from "./server";
 import type { OAuthLoginCallbacks, OAuthPrompt } from "./types";
 
 export interface OAuthClientCallbacksOptions {
@@ -5,6 +6,24 @@ export interface OAuthClientCallbacksOptions {
 	onOutput?: (message: string) => void;
 	openUrl?: (url: string) => void | Promise<void>;
 	onOpenUrlError?: (context: { url: string; error: unknown }) => void;
+	/**
+	 * Called when the local OAuth redirect server successfully binds to a port
+	 * and is ready to receive the browser callback.
+	 *
+	 * Forwarded directly from `OAuthLoginCallbacks.onServerListening`.
+	 * Use this to show a "waiting for OAuth callback on :::1 port N" status
+	 * message or, in remote-development environments (e.g. JetBrains Gateway),
+	 * to set up a port-forward from the remote machine to the local one.
+	 */
+	onServerListening?: (info: OAuthServerListeningInfo) => void | Promise<void>;
+	/**
+	 * Called when the local OAuth redirect server closes.
+	 *
+	 * Forwarded directly from `OAuthLoginCallbacks.onServerClose`.
+	 * Use this to tear down port-forwards and clear any status UI set up in
+	 * `onServerListening`.
+	 */
+	onServerClose?: (info: OAuthServerCloseInfo) => void | Promise<void>;
 }
 
 export function createOAuthClientCallbacks(
@@ -21,5 +40,7 @@ export function createOAuthClientCallbacks(
 			options.onOutput?.(url);
 		},
 		onPrompt: options.onPrompt,
+		onServerListening: options.onServerListening,
+		onServerClose: options.onServerClose,
 	};
 }