@clinebot/core 0.0.36 → 0.0.37

package/src/hub/session-client.ts

@@ -1,3 +1,4 @@
+import type * as LlmsProviders from "@clinebot/llms";
 import type {
 	ChatRunTurnRequest,
 	ChatStartSessionRequest,
@@ -75,12 +76,31 @@ function extractSessionRow(
 	};
 }
 
+function hubReplyErrorMessage(
+	reply: { error?: { message?: string } },
+	command: string,
+): string {
+	return reply.error?.message ?? `hub command failed: ${command}`;
+}
+
 function mapHubEvent(event: HubEventEnvelope): HubStreamEvent | undefined {
 	const sessionId = event.sessionId?.trim();
 	if (!sessionId) {
 		return undefined;
 	}
 	switch (event.event) {
+		case "iteration.started":
+			return {
+				sessionId,
+				eventType: "runtime.chat.iteration_start",
+				payload: cloneRecord(event.payload),
+			};
+		case "iteration.finished":
+			return {
+				sessionId,
+				eventType: "runtime.chat.iteration_end",
+				payload: cloneRecord(event.payload),
+			};
 		case "assistant.delta":
 			return {
 				sessionId,
@@ -159,6 +179,10 @@ export class HubSessionClient {
 		this.client.close();
 	}
 
+	async dispose(): Promise<void> {
+		await this.client.dispose();
+	}
+
 	async startRuntimeSession(
 		request: ChatStartSessionRequest,
 	): Promise<ChatStartSessionResponse> {
@@ -201,6 +225,7 @@ export class HubSessionClient {
 				enableSpawn: request.enableSpawn,
 				enableTeams: request.enableTeams,
 				autoApproveTools: request.autoApproveTools,
+				configExtensions: request.configExtensions,
 			},
 			modelSelection: {
 				provider: request.provider,
@@ -208,7 +233,6 @@ export class HubSessionClient {
 				apiKey: request.apiKey,
 			},
 			toolPolicies: request.toolPolicies,
-			initialMessages: request.initialMessages,
 		});
 		const row = extractSessionRow(reply.payload);
 		if (!row?.sessionId) {
@@ -281,6 +305,24 @@ export class HubSessionClient {
 		return extractSessionRow(reply.payload);
 	}
 
+	async readMessages(sessionId: string): Promise<LlmsProviders.Message[]> {
+		const target = sessionId.trim();
+		if (!target) {
+			return [];
+		}
+		await this.ensureMetadataApplied();
+		const reply = await this.client.command(
+			"session.messages",
+			{ sessionId: target },
+			target,
+		);
+		if (!reply.ok) {
+			throw new Error(hubReplyErrorMessage(reply, "session.messages"));
+		}
+		const messages = reply.payload?.messages;
+		return Array.isArray(messages) ? (messages as LlmsProviders.Message[]) : [];
+	}
+
 	async listSessions(input?: { limit?: number }): Promise<HubSessionRow[]> {
 		await this.ensureMetadataApplied();
 		const reply = await this.client.command("session.list", {

package/src/hub/start-shared-server.ts

@@ -45,6 +45,8 @@ export async function startHubServer(
 export async function ensureHubServer(
 	options: EnsureHubServerOptions,
 ): Promise<EnsureHubServerResult> {
+	const hasExplicitPort =
+		options.port !== undefined || !!process.env.CLINE_HUB_PORT?.trim();
 	const endpoint = resolveHubEndpointOptions({
 		host: options.host,
 		port: options.port,
@@ -53,6 +55,7 @@ export async function ensureHubServer(
 	return await ensureHubWebSocketServer({
 		...options,
 		...endpoint,
+		allowPortFallback: options.allowPortFallback ?? !hasExplicitPort,
 		owner: resolveSharedHubOwnerContext(),
 	});
 }

package/src/hub/ui-client.ts

@@ -39,6 +39,10 @@ export class HubUIClient {
 		this.client.close();
 	}
 
+	async dispose(): Promise<void> {
+		await this.client.dispose();
+	}
+
 	getClientId(): string {
 		return this.client.getClientId();
 	}

package/src/index.ts

@@ -11,10 +11,15 @@ export type {
 	AgentConfig,
 	AgentEvent,
 	AgentExtension,
+	AgentExtension as AgentPlugin, // Public-facing alias for extensions
 	AgentExtensionCommand,
+	AgentExtensionCommand as AgentPluginCommand,
 	AgentHooks,
 	AgentMode,
 	AgentResult,
+	AgentRunResult,
+	AgentRunStatus,
+	AutomationEventEnvelope,
 	BasicLogger,
 	ChatRunTurnRequest,
 	ChatRuntimeConfig,
@@ -23,6 +28,7 @@ export type {
 	ChatTurnResult,
 	ClineAccountActionRequest,
 	ConnectorHookEvent,
+	ContentBlock,
 	EnterpriseAuthenticateRequest,
 	EnterpriseAuthenticateResponse,
 	EnterpriseStatusRequest,
@@ -30,10 +36,14 @@ export type {
 	EnterpriseSyncRequest,
 	EnterpriseSyncResponse,
 	emptyWorkspaceManifest,
+	FileContent,
 	GetProviderModelsActionRequest,
 	HookSessionContext,
+	ImageContent,
 	ITelemetryService,
 	ListProvidersActionRequest,
+	Message,
+	MessageWithMetadata,
 	OAuthProviderId,
 	ProviderActionRequest,
 	ProviderCatalogResponse,
@@ -52,11 +62,15 @@ export type {
 	TelemetryPrimitive,
 	TelemetryProperties,
 	TelemetryValue,
+	TextContent,
+	ThinkingContent,
 	Tool,
 	ToolApprovalRequest,
 	ToolApprovalResult,
 	ToolContext,
 	ToolPolicy,
+	ToolResultContent,
+	ToolUseContent,
 	WorkspaceInfo,
 	WorkspaceInfoSchema,
 	WorkspaceManifest,
@@ -151,13 +165,24 @@ export type {
 	OcaTokenResolution,
 } from "./auth/types";
 export {
+	type ClineAutomationEventIngressResult,
+	type ClineAutomationEventLog,
+	type ClineAutomationEventSuppression,
+	type ClineAutomationListEventsOptions,
+	type ClineAutomationListRunsOptions,
+	type ClineAutomationListSpecsOptions,
+	type ClineAutomationRun,
+	type ClineAutomationRunStatus,
+	type ClineAutomationSpec,
 	ClineCore,
+	type ClineCoreAutomationApi,
+	type ClineCoreAutomationOptions,
+	type ClineCoreListHistoryOptions,
 	type ClineCoreOptions,
 	type ClineCoreStartInput,
 	type HubOptions,
 	type RemoteOptions,
 } from "./ClineCore";
-export * from "./cron";
 export type {
 	LoadAgentPluginFromPathOptions,
 	PluginInitializationFailure,
@@ -336,6 +361,11 @@ export {
 	DefaultRuntimeBuilder,
 } from "./runtime/runtime-builder";
 export type {
+	PendingPromptMutationResult,
+	PendingPromptsAction,
+	PendingPromptsDeleteInput,
+	PendingPromptsListInput,
+	PendingPromptsUpdateInput,
 	RuntimeHost,
 	RuntimeHost as SessionHost,
 	RuntimeHostMode,
@@ -504,6 +534,7 @@ export { CORE_BUILD_VERSION } from "./version";
 export async function loadOpenTelemetryAdapter() {
 	return import("./services/telemetry/index.js");
 }
+export { Agent, createAgentRuntime } from "@clinebot/agents";
 export { createContextCompactionPrepareTurn } from "./extensions/context/compaction";
 export {
 	ALL_DEFAULT_TOOL_NAMES,
@@ -532,6 +563,13 @@ export {
 	type ToolPresetName,
 	ToolPresets,
 } from "./extensions/tools";
+export {
+	type ClineRecommendedModel,
+	type ClineRecommendedModelsData,
+	FALLBACK_CLINE_RECOMMENDED_MODELS,
+	type FetchClineRecommendedModelsOptions,
+	fetchClineRecommendedModels,
+} from "./llms/cline-recommended-models";
 export {
 	clearLiveModelsCatalogCache,
 	clearPrivateModelsCatalogCache,
@@ -551,9 +589,11 @@ export type {
 	ModelCatalogSettings,
 	OcaSettings,
 	ProviderCapability,
+	ProviderClient,
 	ProviderConfig,
 	ProviderDefaultsConfig,
 	ProviderId,
+	ProviderProtocol,
 	ProviderSettings,
 	ReasoningSettings,
 	SapSettings,
@@ -570,7 +610,9 @@ export {
 	ModelCatalogSettingsSchema,
 	normalizeProviderId,
 	OcaSettingsSchema,
+	ProviderClientSchema,
 	ProviderIdSchema,
+	ProviderProtocolSchema,
 	ProviderSettingsSchema,
 	parseSettings,
 	ReasoningSettingsSchema,
@@ -621,6 +663,9 @@ export type {
 	CoreSessionEvent,
 	SessionChunkEvent,
 	SessionEndedEvent,
+	SessionPendingPrompt,
+	SessionPendingPromptSubmittedEvent,
+	SessionPendingPromptsEvent,
 	SessionTeamProgressEvent,
 	SessionToolEvent,
 } from "./types/events";

package/src/llms/cline-recommended-models.ts

@@ -0,0 +1,167 @@
+import { ProviderSettingsManager } from "../services/storage/provider-settings-manager";
+
+export interface ClineRecommendedModel {
+	id: string;
+	name: string;
+	description: string;
+	tags: string[];
+}
+
+export interface ClineRecommendedModelsData {
+	recommended: ClineRecommendedModel[];
+	free: ClineRecommendedModel[];
+}
+
+export interface FetchClineRecommendedModelsOptions {
+	baseUrl?: string;
+	fetchImpl?: typeof fetch;
+	providerSettingsManager?: Pick<
+		ProviderSettingsManager,
+		"getProviderSettings"
+	>;
+	timeoutMs?: number;
+}
+
+const DEFAULT_API_BASE_URL = "https://api.cline.bot";
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+
+export const FALLBACK_CLINE_RECOMMENDED_MODELS: ClineRecommendedModelsData = {
+	recommended: [
+		{
+			id: "anthropic/claude-opus-4.6",
+			name: "Claude Opus 4.6",
+			description: "Most intelligent model for agents and coding",
+			tags: ["BEST"],
+		},
+		{
+			id: "anthropic/claude-sonnet-4.6",
+			name: "Claude Sonnet 4.6",
+			description: "Strong coding and agent performance",
+			tags: ["NEW"],
+		},
+		{
+			id: "google/gemini-3.1-pro-preview",
+			name: "Gemini 3.1 Pro Preview",
+			description: "1M context window, strong coding performance",
+			tags: ["NEW"],
+		},
+		{
+			id: "openai/gpt-5.3-codex",
+			name: "GPT-5.3 Codex",
+			description: "OpenAI's latest with strong coding abilities",
+			tags: ["NEW"],
+		},
+	],
+	free: [
+		{
+			id: "kwaipilot/kat-coder-pro",
+			name: "KwaiKAT Kat Coder Pro",
+			description: "Advanced agentic coding model",
+			tags: ["FREE"],
+		},
+		{
+			id: "arcee-ai/trinity-large-preview:free",
+			name: "Arcee AI Trinity Large Preview",
+			description: "Advanced large preview model",
+			tags: ["FREE"],
+		},
+	],
+};
+
+function cloneRecommendedModels(
+	data: ClineRecommendedModelsData,
+): ClineRecommendedModelsData {
+	return {
+		recommended: data.recommended.map((model) => ({
+			...model,
+			tags: [...model.tags],
+		})),
+		free: data.free.map((model) => ({ ...model, tags: [...model.tags] })),
+	};
+}
+
+function normalizeModel(raw: unknown): ClineRecommendedModel | null {
+	if (!raw || typeof raw !== "object") return null;
+	const data = raw as Record<string, unknown>;
+	if (typeof data.id !== "string" || data.id.length === 0) return null;
+	return {
+		id: data.id,
+		name:
+			typeof data.name === "string" && data.name.length > 0
+				? data.name
+				: data.id,
+		description: typeof data.description === "string" ? data.description : "",
+		tags: Array.isArray(data.tags)
+			? data.tags.filter((tag): tag is string => typeof tag === "string")
+			: [],
+	};
+}
+
+function normalizeResponse(raw: unknown): ClineRecommendedModelsData | null {
+	if (!raw || typeof raw !== "object") return null;
+	const data = raw as Record<string, unknown>;
+	const recommendedRaw = Array.isArray(data.recommended)
+		? data.recommended
+		: [];
+	const freeRaw = Array.isArray(data.free) ? data.free : [];
+	const recommended = recommendedRaw
+		.map(normalizeModel)
+		.filter((model): model is ClineRecommendedModel => model !== null);
+	const free = freeRaw
+		.map(normalizeModel)
+		.filter((model): model is ClineRecommendedModel => model !== null);
+	if (recommended.length === 0 && free.length === 0) return null;
+	return { recommended, free };
+}
+
+function getConfiguredApiBaseUrl(
+	options: FetchClineRecommendedModelsOptions,
+): string {
+	const explicitBaseUrl = options.baseUrl?.trim();
+	if (explicitBaseUrl) return explicitBaseUrl;
+
+	try {
+		const manager =
+			options.providerSettingsManager ?? new ProviderSettingsManager();
+		const settings = manager.getProviderSettings("cline");
+		return settings?.baseUrl?.trim() || DEFAULT_API_BASE_URL;
+	} catch {
+		return DEFAULT_API_BASE_URL;
+	}
+}
+
+async function fetchWithTimeout(
+	fetchImpl: typeof fetch,
+	input: string,
+	timeoutMs: number,
+): Promise<Response> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetchImpl(input, { signal: controller.signal });
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+export async function fetchClineRecommendedModels(
+	options: FetchClineRecommendedModelsOptions = {},
+): Promise<ClineRecommendedModelsData> {
+	try {
+		const base = getConfiguredApiBaseUrl(options);
+		const fetchImpl = options.fetchImpl ?? fetch;
+		const resp = await fetchWithTimeout(
+			fetchImpl,
+			`${base}/api/v1/ai/cline/recommended-models`,
+			options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+		);
+		if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+		const json: unknown = await resp.json();
+		const data = normalizeResponse(json);
+		if (data) return data;
+	} catch {
+		// Fall back to the bundled list when the remote source is unavailable.
+	}
+
+	return cloneRecommendedModels(FALLBACK_CLINE_RECOMMENDED_MODELS);
+}

package/src/llms/handler-factory.ts

@@ -0,0 +1,56 @@
+/**
+ * Build a concrete `LlmsProviders.ApiHandler` from an `AgentConfig`.
+ *
+ * @see PLAN.md §3.1 — moved from `packages/agents/src/utils/config-helpers.ts` lines 15–55.
+ * @see PLAN.md §3.2.1 — `AgentConfig → AgentRuntimeConfig` mapping for
+ *                      the `model` field.
+ *
+ * Pure port. Core calls this once per session (and again on
+ * `updateConnection`) to produce the `AgentModel` adapter handed to
+ * `new AgentRuntime({ model, ... })`.
+ */
+
+import * as LlmsProviders from "@clinebot/llms";
+import type { AgentConfig, BasicLogger } from "@clinebot/shared";
+
+export function resolveKnownModelsFromConfig(
+	config: AgentConfig,
+): Record<string, LlmsProviders.ModelInfo> | undefined {
+	const pc = config.providerConfig as LlmsProviders.ProviderConfig | undefined;
+	if (pc?.knownModels) {
+		return pc.knownModels;
+	}
+	if (config.knownModels) {
+		return config.knownModels;
+	}
+	return (
+		LlmsProviders.MODEL_COLLECTIONS_BY_PROVIDER_ID[config.providerId]?.models ??
+		undefined
+	);
+}
+
+export function createHandlerFromConfig(
+	config: AgentConfig,
+	logger: BasicLogger | undefined,
+): LlmsProviders.ApiHandler {
+	const pc = config.providerConfig as LlmsProviders.ProviderConfig | undefined;
+	const baseProviderConfig =
+		pc?.providerId === config.providerId ? pc : undefined;
+	const normalizedProviderConfig: LlmsProviders.ProviderConfig = {
+		...(baseProviderConfig ?? {}),
+		providerId: config.providerId,
+		modelId: config.modelId,
+		apiKey: config.apiKey ?? baseProviderConfig?.apiKey,
+		baseUrl: config.baseUrl ?? baseProviderConfig?.baseUrl,
+		headers: config.headers ?? baseProviderConfig?.headers,
+		knownModels: resolveKnownModelsFromConfig(config),
+		maxOutputTokens: config.maxTokensPerTurn,
+		reasoningEffort: config.reasoningEffort,
+		thinkingBudgetTokens: config.thinkingBudgetTokens,
+		thinking: config.thinking,
+		abortSignal: config.abortSignal,
+		logger,
+		extensionContext: config.extensionContext,
+	};
+	return LlmsProviders.createHandler(normalizedProviderConfig);
+}

package/src/llms/provider-defaults.ts

@@ -159,6 +159,20 @@ async function mergeKnownModels(
 	});
 }
 
+function resolveCatalogModels(
+	providerId: string,
+	modelsByProviderId: Record<string, Record<string, ModelInfo>>,
+): Record<string, ModelInfo> {
+	// Runtime provider ids do not always match catalog keys. For example,
+	// Cline uses OpenRouter-backed catalog models, so live catalog lookups must
+	// apply the same key mapping as generated catalog lookups.
+	const catalogKeys = Llms.resolveProviderModelCatalogKeys(providerId);
+	return Object.assign(
+		{},
+		...catalogKeys.map((catalogKey) => modelsByProviderId[catalogKey] ?? {}),
+	);
+}
+
 function normalizeBaseUrl(baseUrl: string | undefined): string {
 	const value = baseUrl?.trim();
 	return value && value.length > 0 ? value : "";
@@ -611,7 +625,9 @@ export async function resolveProviderConfig(
 		const liveCatalog = modelCatalog?.loadLatestOnInit
 			? await getLiveModelsCatalog(modelCatalog)
 			: undefined;
-		const liveModels = liveCatalog?.[providerId] ?? {};
+		const liveModels = liveCatalog
+			? resolveCatalogModels(providerId, liveCatalog)
+			: {};
 		const privateModels =
 			config && shouldLoadPrivateModels(providerId, modelCatalog, config)
 				? await getPrivateProviderModels(providerId, modelCatalog, config)

package/src/llms/provider-settings.ts

@@ -29,6 +29,29 @@ export const ProviderIdSchema = z
 	.min(1)
 	.regex(/^[a-z0-9][a-z0-9-]*$/i);
 
+export const ProviderProtocolSchema = z.enum([
+	"anthropic",
+	"gemini",
+	"openai-chat",
+	"openai-responses",
+	"openai-r1",
+	"ai-sdk",
+]);
+
+export const ProviderClientSchema = z.enum([
+	"anthropic",
+	"ai-sdk",
+	"ai-sdk-community",
+	"openai",
+	"openai-compatible",
+	"openai-r1",
+	"gemini",
+	"bedrock",
+	"custom",
+	"fetch",
+	"vertex",
+]);
+
 export const AuthSettingsSchema = z.object({
 	apiKey: z.string().optional(),
 	accessToken: z.string().optional(),
@@ -115,6 +138,9 @@ export const ProviderSettingsSchema = z.object({
 	apiKey: z.string().optional(),
 	auth: AuthSettingsSchema.optional(),
 	model: z.string().optional(),
+	protocol: ProviderProtocolSchema.optional(),
+	client: ProviderClientSchema.optional(),
+	routingProviderId: ProviderIdSchema.optional(),
 	maxTokens: z.number().int().positive().optional(),
 	contextWindow: z.number().int().positive().optional(),
 	baseUrl: z.string().url().optional(),
@@ -156,6 +182,14 @@ export function safeParseSettings(
 	return ProviderSettingsSchema.safeParse(input);
 }
 
+function shouldRouteThroughOpenAIResponses(
+	settings: ProviderSettings,
+): boolean {
+	return (
+		settings.protocol === "openai-responses" || settings.client === "openai"
+	);
+}
+
 export function toProviderConfig(settings: ProviderSettings): ProviderConfig {
 	const providerId = settings.provider as ProviderId;
 	const normalizedProviderId = normalizeProviderId(providerId);
@@ -170,6 +204,7 @@ export function toProviderConfig(settings: ProviderSettings): ProviderConfig {
 			(catalogKey) => Llms.getGeneratedModelsForProvider(catalogKey),
 		),
 	);
+	const generatedDefaultModelId = Object.keys(generatedKnownModels)[0];
 
 	const apiKey =
 		settings.auth?.accessToken ?? settings.apiKey ?? settings.auth?.apiKey;
@@ -180,10 +215,22 @@ export function toProviderConfig(settings: ProviderSettings): ProviderConfig {
 				? DEFAULT_INTERNAL_OCA_BASE_URL
 				: DEFAULT_EXTERNAL_OCA_BASE_URL
 			: providerDefaults?.baseUrl);
+	const routingProviderId =
+		settings.routingProviderId ??
+		(shouldRouteThroughOpenAIResponses(settings) &&
+		normalizedProviderId !== BUILT_IN_PROVIDER.OPENAI_NATIVE
+			? BUILT_IN_PROVIDER.OPENAI_NATIVE
+			: undefined);
 
 	const config: ProviderConfig = {
 		providerId,
-		modelId: settings.model ?? providerDefaults?.modelId ?? "default",
+		clientType: settings.client,
+		routingProviderId,
+		modelId:
+			settings.model ??
+			providerDefaults?.modelId ??
+			generatedDefaultModelId ??
+			"default",
 		knownModels:
 			providerDefaults?.knownModels ??
 			(Object.keys(generatedKnownModels).length > 0

package/src/llms/runtime-registry.ts

@@ -86,6 +86,7 @@ export class DefaultLlmsSdk implements LlmsSdk {
 				client: input.client ?? "openai-compatible",
 				capabilities: input.capabilities,
 				env: input.env,
+				source: "system",
 			},
 			models: input.models,
 		});