@clinebot/core 0.0.34 → 0.0.35

package/src/runtime/runtime-host.ts

@@ -0,0 +1,178 @@
+import type * as LlmsProviders from "@clinebot/llms";
+import type {
+	AgentResult,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+} from "@clinebot/shared";
+import type { HookEventPayload } from "../hooks";
+import type { SessionManifest } from "../session/session-manifest";
+import type { SessionSource } from "../types/common";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { SessionRecord } from "../types/sessions";
+
+export interface RuntimeSessionConfig {
+	sessionId?: string;
+	providerId: string;
+	modelId: string;
+	apiKey?: string;
+	cwd: string;
+	workspaceRoot?: string;
+	systemPrompt: string;
+	mode: CoreSessionConfig["mode"];
+	rules?: CoreSessionConfig["rules"];
+	maxIterations?: CoreSessionConfig["maxIterations"];
+	enableTools: boolean;
+	enableSpawnAgent: boolean;
+	enableAgentTeams: boolean;
+	disableMcpSettingsTools?: boolean;
+	teamName?: string;
+	missionLogIntervalSteps?: number;
+	missionLogIntervalMs?: number;
+}
+
+export type LocalRuntimeConfigOverrides = Omit<
+	CoreSessionConfig,
+	keyof RuntimeSessionConfig
+>;
+
+export interface LocalRuntimeStartOptions {
+	configOverrides?: Partial<LocalRuntimeConfigOverrides>;
+	userInstructionWatcher?: import("../extensions/config").UserInstructionConfigWatcher;
+	onTeamRestored?: () => void;
+}
+
+export interface StartSessionInput {
+	config: RuntimeSessionConfig;
+	source?: SessionSource;
+	prompt?: string;
+	interactive?: boolean;
+	sessionMetadata?: Record<string, unknown>;
+	initialMessages?: LlmsProviders.Message[];
+	userImages?: string[];
+	userFiles?: string[];
+	/**
+	 * Local runtime bootstrap options. These are intentionally isolated under a
+	 * local-only bag so the transport-facing host contract stays transport-safe.
+	 */
+	localRuntime?: LocalRuntimeStartOptions;
+	toolPolicies?: import("@clinebot/shared").AgentConfig["toolPolicies"];
+	requestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult>;
+}
+
+export function splitCoreSessionConfig(config: CoreSessionConfig): {
+	config: RuntimeSessionConfig;
+	localRuntime?: LocalRuntimeStartOptions;
+} {
+	const {
+		sessionId,
+		providerId,
+		modelId,
+		apiKey,
+		cwd,
+		workspaceRoot,
+		systemPrompt,
+		mode,
+		rules,
+		maxIterations,
+		enableTools,
+		enableSpawnAgent,
+		enableAgentTeams,
+		disableMcpSettingsTools,
+		teamName,
+		missionLogIntervalSteps,
+		missionLogIntervalMs,
+		...localConfigOverrides
+	} = config;
+
+	const localRuntime =
+		Object.keys(localConfigOverrides).length > 0
+			? {
+					configOverrides:
+						localConfigOverrides as Partial<LocalRuntimeConfigOverrides>,
+				}
+			: undefined;
+
+	return {
+		config: {
+			...(sessionId ? { sessionId } : {}),
+			providerId,
+			modelId,
+			...(apiKey ? { apiKey } : {}),
+			cwd,
+			...(workspaceRoot ? { workspaceRoot } : {}),
+			systemPrompt,
+			mode,
+			rules,
+			maxIterations,
+			enableTools,
+			enableSpawnAgent,
+			enableAgentTeams,
+			disableMcpSettingsTools,
+			teamName,
+			missionLogIntervalSteps,
+			missionLogIntervalMs,
+		},
+		...(localRuntime ? { localRuntime } : {}),
+	};
+}
+
+export interface StartSessionResult {
+	sessionId: string;
+	manifest: SessionManifest;
+	manifestPath: string;
+	messagesPath: string;
+	result?: AgentResult;
+}
+
+export interface SendSessionInput {
+	sessionId: string;
+	prompt: string;
+	userImages?: string[];
+	userFiles?: string[];
+	delivery?: "queue" | "steer";
+}
+
+export interface SessionAccumulatedUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	totalCost: number;
+}
+
+/**
+ * RuntimeHost is the transport/runtime boundary for core session execution.
+ * Callers must normalize broad local config into `RuntimeSessionConfig`
+ * plus optional `localRuntime` overrides before invoking a host.
+ */
+export interface RuntimeHost {
+	readonly runtimeAddress?: string;
+	start(input: StartSessionInput): Promise<StartSessionResult>;
+	send(input: SendSessionInput): Promise<AgentResult | undefined>;
+	getAccumulatedUsage(
+		sessionId: string,
+	): Promise<SessionAccumulatedUsage | undefined>;
+	abort(sessionId: string, reason?: unknown): Promise<void>;
+	stop(sessionId: string): Promise<void>;
+	dispose(reason?: string): Promise<void>;
+	get(sessionId: string): Promise<SessionRecord | undefined>;
+	list(limit?: number): Promise<SessionRecord[]>;
+	delete(sessionId: string): Promise<boolean>;
+	update(
+		sessionId: string,
+		updates: {
+			prompt?: string | null;
+			metadata?: Record<string, unknown> | null;
+			title?: string | null;
+		},
+	): Promise<{ updated: boolean }>;
+	readMessages(sessionId: string): Promise<LlmsProviders.Message[]>;
+	handleHookEvent(payload: HookEventPayload): Promise<void>;
+	subscribe(listener: (event: CoreSessionEvent) => void): () => void;
+	updateSessionModel?(sessionId: string, modelId: string): Promise<void>;
+}
+
+export type RuntimeHostMode = "auto" | "rpc" | "local";

package/src/{session → runtime}/runtime-oauth-token-manager.ts

@@ -11,7 +11,7 @@ import {
 import { getValidOpenAICodexCredentials } from "../auth/codex";
 import { getValidOcaCredentials } from "../auth/oca";
 import { decodeJwtPayload } from "../auth/utils";
-import { ProviderSettingsManager } from "../storage/provider-settings-manager";
+import { ProviderSettingsManager } from "../services/storage/provider-settings-manager";
 
 const DEFAULT_CLINE_API_BASE_URL = "https://api.cline.bot";
 const WORKOS_TOKEN_PREFIX = "workos:";

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

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Tool } from "@clinebot/shared";
 import { describe, expect, it } from "vitest";
-import { createBuiltinTools } from "../tools";
+import { createBuiltinTools } from "../extensions/tools";
 import { DefaultRuntimeBuilder } from "./runtime-builder";
 
 type LegacyConfig = {

package/src/runtime/session-runtime.ts

@@ -9,12 +9,12 @@ import type {
 	Tool,
 } from "@clinebot/shared";
 import type { UserInstructionConfigWatcher } from "../extensions/config";
+import type { ToolExecutors } from "../extensions/tools";
 import type {
 	AgentTeamsRuntime,
 	DelegatedAgentConfigProvider,
 	TeamEvent,
-} from "../team";
-import type { ToolExecutors } from "../tools";
+} from "../extensions/tools/team";
 import type { CoreSessionConfig } from "../types/config";
 
 export interface BuiltRuntime {

package/src/{session/session-agent-events.ts → services/agent-events.ts}

@@ -1,4 +1,9 @@
 import type { AgentEvent } from "@clinebot/shared";
+import type { SessionAccumulatedUsage } from "../runtime/runtime-host";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { ActiveSession } from "../types/session";
+import { serializeAgentEvent } from "./session-data";
 import {
 	captureConversationTurnEvent,
 	captureDiffEditFailure,
@@ -7,13 +12,8 @@ import {
 	captureTokenUsage,
 	captureToolUsage,
 	type TelemetryAgentIdentityProperties,
-} from "../telemetry/core-events";
-import type { CoreSessionConfig } from "../types/config";
-import type { CoreSessionEvent } from "../types/events";
-import type { SessionAccumulatedUsage } from "./session-manager";
-import { serializeAgentEvent } from "./utils/helpers";
-import type { ActiveSession } from "./utils/types";
-import { accumulateUsageTotals } from "./utils/usage";
+} from "./telemetry/core-events";
+import { accumulateUsageTotals } from "./usage";
 
 export function extractSkillNameFromToolInput(
 	input: unknown,

package/src/services/config.ts

@@ -0,0 +1,5 @@
+import type { CoreSessionConfig } from "../types/config";
+
+export function resolveWorkspacePath(config: CoreSessionConfig): string {
+	return config.workspaceRoot ?? config.cwd;
+}

package/src/services/local-runtime-bootstrap.ts

@@ -0,0 +1,280 @@
+import type {
+	AgentConfig,
+	AgentHooks,
+	ITelemetryService,
+	Tool,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+} from "@clinebot/shared";
+import { resolveAndLoadAgentPlugins } from "../extensions/plugin/plugin-config-loader";
+import type {
+	PluginInitializationFailure,
+	PluginInitializationWarning,
+} from "../extensions/plugin/plugin-load-report";
+import type { ToolExecutors } from "../extensions/tools";
+import type { TeamEvent } from "../extensions/tools/team";
+import { createCheckpointHooks } from "../hooks/checkpoint-hooks";
+import {
+	createHookAuditHooks,
+	createHookConfigFileHooks,
+	mergeAgentHooks,
+} from "../hooks/hook-file-hooks";
+import type {
+	LocalRuntimeConfigOverrides,
+	LocalRuntimeStartOptions,
+	StartSessionInput,
+} from "../runtime/runtime-host";
+import type {
+	RuntimeBuilderInput,
+	TeamToolsFactory,
+} from "../runtime/session-runtime";
+import type { CoreSessionConfig } from "../types/config";
+import {
+	type ProviderConfig,
+	type ProviderSettings,
+	toProviderConfig,
+} from "../types/provider-settings";
+import { resolveWorkspacePath } from "./config";
+import { hasRuntimeHooks, mergeAgentExtensions } from "./session-data";
+import type { ProviderSettingsManager } from "./storage/provider-settings-manager";
+import { buildWorkspaceMetadata } from "./workspace-manifest";
+
+function formatPluginFailure(failure: PluginInitializationFailure): string {
+	const label = failure.pluginName ?? failure.pluginPath;
+	return `${label}: ${failure.message}`;
+}
+
+function logPluginDiagnostics(
+	failures: PluginInitializationFailure[],
+	warnings: PluginInitializationWarning[],
+	logger: CoreSessionConfig["logger"],
+): void {
+	if (warnings.length > 0) {
+		for (const warning of warnings) {
+			logger?.log(warning.message, { severity: "warn" });
+		}
+	}
+	if (failures.length === 0) {
+		return;
+	}
+	const preview = failures.slice(0, 3).map(formatPluginFailure).join("; ");
+	const suffix = failures.length > 3 ? `; and ${failures.length - 3} more` : "";
+	logger?.log(
+		`Some plugins failed to initialize. ${preview}${suffix}. Use --verbose for more details.`,
+		{ severity: "warn" },
+	);
+	for (const failure of failures) {
+		logger?.log(
+			`Plugin initialization failed (${failure.phase}) for ${failure.pluginPath}`,
+			{
+				severity: "warn",
+				stack: failure.stack,
+				pluginPath: failure.pluginPath,
+				pluginName: failure.pluginName,
+			},
+		);
+	}
+}
+
+function resolveReasoningSettings(
+	config: CoreSessionConfig,
+	storedReasoning: ProviderSettings["reasoning"],
+): ProviderSettings["reasoning"] {
+	const hasThinking = typeof config.thinking === "boolean";
+	const hasEffort = typeof config.reasoningEffort === "string";
+	if (!hasThinking && !hasEffort) return storedReasoning;
+	return {
+		...(storedReasoning ?? {}),
+		...(hasThinking ? { enabled: config.thinking } : {}),
+		...(hasEffort ? { effort: config.reasoningEffort } : {}),
+	};
+}
+
+function buildProviderConfig(
+	config: CoreSessionConfig,
+	providerSettingsManager: ProviderSettingsManager,
+): ProviderConfig {
+	const stored = providerSettingsManager.getProviderSettings(config.providerId);
+	const settings: ProviderSettings = {
+		...(stored ?? {}),
+		provider: config.providerId,
+		model: config.modelId,
+		apiKey: config.apiKey ?? stored?.apiKey,
+		baseUrl: config.baseUrl ?? stored?.baseUrl,
+		headers: config.headers ?? stored?.headers,
+		reasoning: resolveReasoningSettings(config, stored?.reasoning),
+	};
+	const providerConfig = toProviderConfig(settings);
+	if (config.knownModels) {
+		providerConfig.knownModels = config.knownModels;
+	}
+	if (config.extensionContext) {
+		providerConfig.extensionContext = config.extensionContext;
+	}
+	return providerConfig;
+}
+
+export interface PrepareLocalRuntimeBootstrapOptions {
+	input: StartSessionInput;
+	localRuntime?: LocalRuntimeStartOptions;
+	sessionId: string;
+	providerSettingsManager: ProviderSettingsManager;
+	defaultTelemetry?: ITelemetryService;
+	defaultToolExecutors?: Partial<ToolExecutors>;
+	teamToolsFactory?: TeamToolsFactory;
+	defaultToolPolicies?: AgentConfig["toolPolicies"];
+	defaultRequestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult>;
+	onPluginEvent: (event: { name: string; payload?: unknown }) => void;
+	onTeamEvent: (event: TeamEvent) => void;
+	createSpawnTool: () => Tool;
+	readSessionMetadata: () => Promise<Record<string, unknown> | undefined>;
+	writeSessionMetadata: (
+		metadata: Record<string, unknown>,
+	) => Promise<void> | void;
+}
+
+export interface LocalRuntimeBootstrap {
+	effectiveInput: StartSessionInput;
+	config: CoreSessionConfig;
+	providerConfig: ProviderConfig;
+	workspaceMetadata: string;
+	extensions: AgentConfig["extensions"];
+	hooks: AgentHooks | undefined;
+	toolPolicies: AgentConfig["toolPolicies"];
+	requestToolApproval?: (
+		request: ToolApprovalRequest,
+	) => Promise<ToolApprovalResult>;
+	pluginSandboxShutdown?: () => Promise<void>;
+	runtimeBuilderInput: RuntimeBuilderInput;
+}
+
+export async function prepareLocalRuntimeBootstrap(
+	options: PrepareLocalRuntimeBootstrapOptions,
+): Promise<LocalRuntimeBootstrap> {
+	const {
+		input,
+		sessionId,
+		providerSettingsManager,
+		defaultTelemetry,
+		defaultToolExecutors,
+		teamToolsFactory,
+		defaultToolPolicies,
+		defaultRequestToolApproval,
+		onPluginEvent,
+		onTeamEvent,
+		createSpawnTool,
+		localRuntime,
+		readSessionMetadata,
+		writeSessionMetadata,
+	} = options;
+	const workspacePath = resolveWorkspacePath(input.config);
+	const configOverrides = localRuntime?.configOverrides as
+		| Partial<LocalRuntimeConfigOverrides>
+		| undefined;
+
+	const fileHooks = createHookConfigFileHooks({
+		cwd: input.config.cwd,
+		workspacePath,
+		rootSessionId: sessionId,
+		logger: configOverrides?.logger,
+	});
+	const auditHooks = hasRuntimeHooks(configOverrides?.hooks)
+		? undefined
+		: createHookAuditHooks({
+				rootSessionId: sessionId,
+				workspacePath,
+			});
+	const baseHooks = mergeAgentHooks([
+		configOverrides?.hooks,
+		fileHooks,
+		auditHooks,
+	]);
+
+	let loadedPlugins:
+		| Awaited<ReturnType<typeof resolveAndLoadAgentPlugins>>
+		| undefined;
+	try {
+		loadedPlugins = await resolveAndLoadAgentPlugins({
+			pluginPaths: configOverrides?.pluginPaths,
+			workspacePath,
+			cwd: input.config.cwd,
+			onEvent: onPluginEvent,
+		});
+		logPluginDiagnostics(
+			loadedPlugins.failures,
+			loadedPlugins.warnings,
+			configOverrides?.logger,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		configOverrides?.logger?.log?.(
+			`plugin loading failed; continuing without plugins (${message})`,
+		);
+	}
+
+	const extensions = mergeAgentExtensions(
+		configOverrides?.extensions,
+		loadedPlugins?.extensions,
+	);
+	const workspaceMetadata = await buildWorkspaceMetadata(input.config.cwd);
+	const baseConfig: CoreSessionConfig = {
+		...input.config,
+		...(configOverrides ?? {}),
+		hooks: baseHooks,
+		extensions,
+		telemetry: configOverrides?.telemetry ?? defaultTelemetry,
+	};
+	const providerConfig = buildProviderConfig(
+		baseConfig,
+		providerSettingsManager,
+	);
+	const hooks = mergeAgentHooks([
+		baseConfig.hooks,
+		baseConfig.checkpoint?.enabled === true
+			? createCheckpointHooks({
+					cwd: baseConfig.cwd,
+					sessionId,
+					logger: baseConfig.logger,
+					createCheckpoint: baseConfig.checkpoint?.createCheckpoint,
+					readSessionMetadata,
+					writeSessionMetadata,
+				})
+			: undefined,
+	]);
+	const config: CoreSessionConfig = {
+		...baseConfig,
+		providerConfig,
+		workspaceMetadata,
+		hooks,
+	};
+	const toolPolicies = input.toolPolicies ?? defaultToolPolicies;
+	const requestToolApproval =
+		input.requestToolApproval ?? defaultRequestToolApproval;
+
+	return {
+		effectiveInput: input,
+		config,
+		providerConfig,
+		workspaceMetadata,
+		extensions,
+		hooks,
+		toolPolicies,
+		requestToolApproval,
+		pluginSandboxShutdown: loadedPlugins?.shutdown,
+		runtimeBuilderInput: {
+			config,
+			hooks,
+			extensions,
+			onTeamEvent,
+			createSpawnTool,
+			onTeamRestored: localRuntime?.onTeamRestored,
+			userInstructionWatcher: localRuntime?.userInstructionWatcher,
+			defaultToolExecutors,
+			logger: config.logger,
+			telemetry: config.telemetry,
+			teamToolsFactory,
+		},
+	};
+}

package/src/{providers → services/providers}/local-provider-service.ts

@@ -8,10 +8,10 @@ import type {
 	RpcProviderModel,
 	RpcSaveProviderSettingsActionRequest,
 } from "@clinebot/shared";
-import { createOAuthClientCallbacks } from "../auth/client";
-import { loginClineOAuth } from "../auth/cline";
-import { loginOpenAICodex } from "../auth/codex";
-import { loginOcaOAuth } from "../auth/oca";
+import { createOAuthClientCallbacks } from "../../auth/client";
+import { loginClineOAuth } from "../../auth/cline";
+import { loginOpenAICodex } from "../../auth/codex";
+import { loginOcaOAuth } from "../../auth/oca";
 import type { ProviderSettingsManager } from "../storage/provider-settings-manager";
 import {
 	readModelsFile,

package/src/{session → services}/session-artifacts.ts

@@ -7,7 +7,10 @@ import {
 	unlinkSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { parseSubSessionId, parseTeamTaskSubSessionId } from "./session-graph";
+import {
+	parseSubSessionId,
+	parseTeamTaskSubSessionId,
+} from "../session/session-graph";
 
 export function nowIso(): string {
 	return new Date().toISOString();
@@ -25,8 +28,6 @@ export function unlinkIfExists(path: string | null | undefined): void {
 }
 
 export interface SessionArtifactPaths {
-	transcriptPath: string;
-	hookPath: string;
 	messagesPath: string;
 }
 
@@ -71,25 +72,14 @@ export class SessionArtifacts {
 		return dir;
 	}
 
-	public sessionTranscriptPath(sessionId: string): string {
-		return join(this.ensureSessionArtifactsDir(sessionId), `${sessionId}.log`);
-	}
-
-	public sessionHookPath(sessionId: string): string {
-		return join(
-			this.ensureSessionArtifactsDir(sessionId),
-			`${sessionId}.hooks.jsonl`,
-		);
-	}
-
 	public sessionMessagesPath(sessionId: string): string {
 		return join(
-			this.ensureSessionArtifactsDir(sessionId),
+			this.sessionArtifactsDir(sessionId),
 			`${sessionId}.messages.json`,
 		);
 	}
 
-	public sessionManifestPath(sessionId: string, ensureDir = true): string {
+	public sessionManifestPath(sessionId: string, ensureDir = false): string {
 		const base = ensureDir
 			? this.ensureSessionArtifactsDir(sessionId)
 			: this.sessionArtifactsDir(sessionId);
@@ -140,10 +130,8 @@ export class SessionArtifacts {
 		void subAgentId;
 		void activeTeamTaskSessionId;
 		const { rootSessionId, fileStem } = childArtifactFileStem(sessionId);
-		const dir = this.ensureSessionArtifactsDir(rootSessionId);
+		const dir = this.sessionArtifactsDir(rootSessionId);
 		return {
-			transcriptPath: join(dir, `${fileStem}.log`),
-			hookPath: join(dir, `${fileStem}.hooks.jsonl`),
 			messagesPath: join(dir, `${fileStem}.messages.json`),
 		};
 	}

package/src/{session/utils/helpers.test.ts → services/session-data.test.ts}

@@ -1,7 +1,7 @@
 import type { MessageWithMetadata } from "@clinebot/llms";
 import type { AgentResult } from "@clinebot/shared";
 import { describe, expect, it } from "vitest";
-import { withLatestAssistantTurnMetadata } from "./helpers";
+import { withLatestAssistantTurnMetadata } from "./session-data";
 
 type LegacyStoredMessage = MessageWithMetadata & {
 	providerId?: string;