@clinebot/shared 0.0.8 → 0.0.9

package/src/rpc/runtime.ts

@@ -0,0 +1,316 @@
+import type {
+	AgentMode,
+	SessionExecutionConfig,
+	SessionPromptConfig,
+} from "../session/runtime-config";
+
+export type RpcAgentMode = AgentMode;
+
+export interface RpcSessionStorageOptions {
+	homeDir?: string;
+}
+
+export interface RpcChatRuntimeConfigBase extends SessionPromptConfig {
+	cwd?: string;
+	apiKey: string;
+	logger?: RpcChatRuntimeLoggerConfig;
+	enableTools: boolean;
+	enableSpawn: boolean;
+	enableTeams: boolean;
+	autoApproveTools?: boolean;
+	teamName: string;
+	missionStepInterval: number;
+	missionTimeIntervalMs: number;
+	toolPolicies?: SessionExecutionConfig["toolPolicies"];
+}
+
+export interface RpcChatRuntimeLoggerConfig {
+	enabled?: boolean;
+	level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
+	destination?: string;
+	name?: string;
+	bindings?: Record<string, string | number | boolean>;
+}
+
+export interface RpcChatStartSessionRequest extends RpcChatRuntimeConfigBase {
+	sessionId?: string;
+	workspaceRoot: string;
+	provider: string;
+	model: string;
+	sessions?: RpcSessionStorageOptions;
+	initialMessages?: RpcChatMessage[];
+}
+
+export interface RpcChatStartSessionArtifacts {
+	sessionId: string;
+	manifestPath: string;
+	transcriptPath: string;
+	hookPath: string;
+	messagesPath: string;
+}
+
+export interface RpcChatStartSessionResponse {
+	sessionId: string;
+	startResult?: RpcChatStartSessionArtifacts;
+}
+
+export interface RpcChatAttachmentFile {
+	name: string;
+	content: string;
+}
+
+export interface RpcChatAttachments {
+	userImages?: string[];
+	userFiles?: RpcChatAttachmentFile[];
+}
+
+export interface RpcChatMessage {
+	role?: string;
+	content?: unknown;
+	[key: string]: unknown;
+}
+
+export interface RpcChatRunTurnRequest {
+	config: RpcChatStartSessionRequest;
+	messages?: RpcChatMessage[];
+	prompt: string;
+	attachments?: RpcChatAttachments;
+}
+
+export interface RpcChatToolCallResult {
+	name: string;
+	input?: unknown;
+	output?: unknown;
+	error?: string;
+	durationMs?: number;
+}
+
+export interface RpcChatTurnResult {
+	text: string;
+	usage: {
+		inputTokens: number;
+		outputTokens: number;
+		cacheReadTokens?: number;
+		cacheWriteTokens?: number;
+		totalCost?: number;
+	};
+	inputTokens: number;
+	outputTokens: number;
+	iterations: number;
+	finishReason: string;
+	messages: RpcChatMessage[];
+	toolCalls: RpcChatToolCallResult[];
+}
+
+export interface RpcProviderModel {
+	id: string;
+	name: string;
+	supportsAttachments?: boolean;
+	supportsVision?: boolean;
+	supportsReasoning?: boolean;
+}
+
+export interface RpcProviderListItem {
+	id: string;
+	name: string;
+	models: number | null;
+	color: string;
+	letter: string;
+	enabled: boolean;
+	apiKey?: string;
+	oauthAccessTokenPresent?: boolean;
+	baseUrl?: string;
+	defaultModelId?: string;
+	authDescription: string;
+	baseUrlDescription: string;
+	modelList?: RpcProviderModel[];
+}
+
+export interface RpcProviderCatalogResponse {
+	providers: RpcProviderListItem[];
+	settingsPath: string;
+}
+
+export interface RpcProviderModelsResponse {
+	providerId: string;
+	models: RpcProviderModel[];
+}
+
+export interface RpcClineAccountOrganization {
+	active: boolean;
+	memberId: string;
+	name: string;
+	organizationId: string;
+	roles: Array<"admin" | "member" | "owner">;
+}
+
+export interface RpcClineAccountUser {
+	id: string;
+	email: string;
+	displayName: string;
+	photoUrl: string;
+	createdAt: string;
+	updatedAt: string;
+	organizations: RpcClineAccountOrganization[];
+}
+
+export interface RpcClineAccountBalance {
+	balance: number;
+	userId: string;
+}
+
+export interface RpcClineAccountUsageTransaction {
+	aiInferenceProviderName: string;
+	aiModelName: string;
+	aiModelTypeName: string;
+	completionTokens: number;
+	costUsd: number;
+	createdAt: string;
+	creditsUsed: number;
+	generationId: string;
+	id: string;
+	metadata: {
+		additionalProp1: string;
+		additionalProp2: string;
+		additionalProp3: string;
+	};
+	operation?: string;
+	organizationId: string;
+	promptTokens: number;
+	totalTokens: number;
+	userId: string;
+}
+
+export interface RpcClineAccountPaymentTransaction {
+	paidAt: string;
+	creatorId: string;
+	amountCents: number;
+	credits: number;
+}
+
+export interface RpcClineAccountOrganizationBalance {
+	balance: number;
+	organizationId: string;
+}
+
+export interface RpcClineAccountOrganizationUsageTransaction {
+	aiInferenceProviderName: string;
+	aiModelName: string;
+	aiModelTypeName: string;
+	completionTokens: number;
+	costUsd: number;
+	createdAt: string;
+	creditsUsed: number;
+	generationId: string;
+	id: string;
+	memberDisplayName: string;
+	memberEmail: string;
+	metadata: {
+		additionalProp1: string;
+		additionalProp2: string;
+		additionalProp3: string;
+	};
+	operation?: string;
+	organizationId: string;
+	promptTokens: number;
+	totalTokens: number;
+	userId: string;
+}
+
+import type { OAuthProviderId } from "../auth/constants";
+
+export type RpcOAuthProviderId = OAuthProviderId;
+
+export type RpcProviderCapability =
+	| "reasoning"
+	| "prompt-cache"
+	| "streaming"
+	| "tools"
+	| "vision";
+
+export interface RpcListProvidersActionRequest {
+	action: "listProviders";
+}
+
+export interface RpcGetProviderModelsActionRequest {
+	action: "getProviderModels";
+	providerId: string;
+}
+
+export interface RpcSaveProviderSettingsActionRequest {
+	action: "saveProviderSettings";
+	providerId: string;
+	enabled?: boolean;
+	apiKey?: string;
+	baseUrl?: string;
+}
+
+export interface RpcAddProviderActionRequest {
+	action: "addProvider";
+	providerId: string;
+	name: string;
+	baseUrl: string;
+	apiKey?: string;
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	models?: string[];
+	defaultModelId?: string;
+	modelsSourceUrl?: string;
+	capabilities?: RpcProviderCapability[];
+}
+
+export type RpcProviderSettingsActionRequest =
+	| RpcListProvidersActionRequest
+	| RpcGetProviderModelsActionRequest
+	| RpcSaveProviderSettingsActionRequest
+	| RpcAddProviderActionRequest;
+
+export type RpcClineAccountActionRequest =
+	| {
+			action: "clineAccount";
+			operation: "fetchMe";
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchBalance";
+			userId?: string;
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchUsageTransactions";
+			userId?: string;
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchPaymentTransactions";
+			userId?: string;
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchUserOrganizations";
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchOrganizationBalance";
+			organizationId: string;
+	  }
+	| {
+			action: "clineAccount";
+			operation: "fetchOrganizationUsageTransactions";
+			organizationId: string;
+			memberId?: string;
+	  }
+	| {
+			action: "clineAccount";
+			operation: "switchAccount";
+			organizationId?: string | null;
+	  };
+
+export type RpcProviderActionRequest =
+	| RpcProviderSettingsActionRequest
+	| RpcClineAccountActionRequest;
+
+export interface RpcProviderOAuthLoginResponse {
+	provider: RpcOAuthProviderId;
+	accessToken: string;
+}

package/src/rpc/team-progress.ts

@@ -0,0 +1,71 @@
+export const RPC_TEAM_PROGRESS_EVENT_TYPE = "runtime.team.progress.v1";
+export const RPC_TEAM_LIFECYCLE_EVENT_TYPE = "runtime.team.lifecycle.v1";
+
+export type TeamProgressMemberRole = "lead" | "teammate";
+export type TeamProgressMemberStatus = "idle" | "running" | "stopped";
+export type TeamProgressTaskStatus =
+	| "pending"
+	| "in_progress"
+	| "blocked"
+	| "completed";
+export type TeamProgressRunStatus =
+	| "queued"
+	| "running"
+	| "completed"
+	| "failed"
+	| "cancelled"
+	| "interrupted";
+export type TeamProgressOutcomeStatus = "draft" | "in_review" | "finalized";
+export type TeamProgressOutcomeFragmentStatus =
+	| "draft"
+	| "reviewed"
+	| "rejected";
+
+export interface TeamProgressCounts<TStatus extends string> {
+	total: number;
+	byStatus: Record<TStatus, number>;
+}
+
+export interface TeamProgressSummary {
+	teamName: string;
+	updatedAt: string;
+	members: TeamProgressCounts<TeamProgressMemberStatus> & {
+		leadCount: number;
+		teammateCount: number;
+	};
+	tasks: TeamProgressCounts<TeamProgressTaskStatus> & {
+		blockedTaskIds: string[];
+		readyTaskIds: string[];
+		completionPct: number;
+	};
+	runs: TeamProgressCounts<TeamProgressRunStatus> & {
+		activeRunIds: string[];
+		latestRunId?: string;
+	};
+	outcomes: TeamProgressCounts<TeamProgressOutcomeStatus> & {
+		finalizedPct: number;
+		missingRequiredSections: string[];
+	};
+	fragments: TeamProgressCounts<TeamProgressOutcomeFragmentStatus>;
+}
+
+export interface TeamProgressLifecycleEvent {
+	teamName: string;
+	sessionId: string;
+	eventType: string;
+	ts: string;
+	agentId?: string;
+	taskId?: string;
+	runId?: string;
+	outcomeId?: string;
+	fragmentId?: string;
+	message?: string;
+}
+
+export interface TeamProgressProjectionEvent {
+	type: "team_progress_projection";
+	version: 1;
+	sessionId: string;
+	summary: TeamProgressSummary;
+	lastEvent: TeamProgressLifecycleEvent;
+}

package/src/services/telemetry-config.ts

@@ -0,0 +1,55 @@
+import type { OpenTelemetryClientConfig, TelemetryMetadata } from "./telemetry";
+
+export interface ClineTelemetryServiceConfig extends OpenTelemetryClientConfig {
+	metadata: TelemetryMetadata;
+}
+
+function getTelemetryBuildTimeConfig(): OpenTelemetryClientConfig {
+	return {
+		enabled:
+			process?.env?.OTEL_TELEMETRY_ENABLED === "1" ||
+			process?.env?.OTEL_TELEMETRY_ENABLED === "true",
+		metricsExporter: process?.env?.OTEL_METRICS_EXPORTER || "otlp",
+		logsExporter: process?.env?.OTEL_LOGS_EXPORTER || "otlp",
+		otlpProtocol: process?.env?.OTEL_EXPORTER_OTLP_PROTOCOL || "http/json",
+		otlpEndpoint: process?.env?.OTEL_EXPORTER_OTLP_ENDPOINT,
+		metricExportInterval: process?.env?.OTEL_METRIC_EXPORT_INTERVAL
+			? Number.parseInt(process?.env?.OTEL_METRIC_EXPORT_INTERVAL, 10)
+			: undefined,
+		otlpHeaders: process?.env?.OTEL_EXPORTER_OTLP_HEADERS
+			? Object.fromEntries(
+					process?.env?.OTEL_EXPORTER_OTLP_HEADERS.split(",").map((header) => {
+						const [key, value] = header.split("=");
+						return [key.trim(), value.trim()];
+					}),
+				)
+			: undefined,
+	};
+}
+
+export function createClineTelemetryServiceMetadata(
+	overrides: Partial<TelemetryMetadata> = {},
+): TelemetryMetadata {
+	return {
+		extension_version: "unknown",
+		cline_type: "unknown",
+		platform: "terminal",
+		platform_version: process?.version || "unknown",
+		os_type: process?.platform || "unknown",
+		os_version:
+			process?.platform === "win32"
+				? (process?.env?.OS ?? "unknown")
+				: "unknown",
+		...overrides,
+	};
+}
+
+export function createClineTelemetryServiceConfig(
+	configOverrides: Partial<ClineTelemetryServiceConfig> = {},
+): ClineTelemetryServiceConfig {
+	return {
+		...getTelemetryBuildTimeConfig(),
+		...configOverrides,
+		metadata: createClineTelemetryServiceMetadata(configOverrides.metadata),
+	};
+}

package/src/services/telemetry.ts

@@ -0,0 +1,141 @@
+export type TelemetryPrimitive = string | number | boolean | null | undefined;
+
+export type TelemetryValue =
+	| TelemetryPrimitive
+	| TelemetryObject
+	| TelemetryArray;
+
+export type TelemetryObject = { [key: string]: TelemetryValue };
+
+export type TelemetryArray = Array<TelemetryValue>;
+
+export type TelemetryProperties = TelemetryObject;
+
+export interface TelemetryMetadata {
+	extension_version: string;
+	cline_type: string;
+	platform: string;
+	platform_version: string;
+	os_type: string;
+	os_version: string;
+	is_dev?: string;
+}
+
+export interface ITelemetryService {
+	setDistinctId(distinctId?: string): void;
+	setMetadata(metadata: Partial<TelemetryMetadata>): void;
+	updateMetadata(metadata: Partial<TelemetryMetadata>): void;
+	setCommonProperties(properties: TelemetryProperties): void;
+	updateCommonProperties(properties: TelemetryProperties): void;
+	isEnabled(): boolean;
+	capture(input: { event: string; properties?: TelemetryProperties }): void;
+	captureRequired(event: string, properties?: TelemetryProperties): void;
+	recordCounter(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+	recordHistogram(
+		name: string,
+		value: number,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+	recordGauge(
+		name: string,
+		value: number | null,
+		attributes?: TelemetryProperties,
+		description?: string,
+		required?: boolean,
+	): void;
+	flush(): Promise<void>;
+	dispose(): Promise<void>;
+}
+
+export interface OpenTelemetryClientConfig {
+	/**
+	 * Whether telemetry is enabled via OTEL_TELEMETRY_ENABLED
+	 */
+	enabled: boolean;
+
+	/**
+	 * Metrics exporter type(s) - can be comma-separated for multiple exporters
+	 * Examples: "console", "otlp", "prometheus", "console,otlp"
+	 */
+	metricsExporter?: string;
+
+	/**
+	 * Logs/events exporter type(s) - can be comma-separated for multiple exporters
+	 * Examples: "console", "otlp"
+	 */
+	logsExporter?: string;
+
+	/**
+	 * Protocol for OTLP exporters. SDK support is currently limited to "http/json".
+	 */
+	otlpProtocol?: string;
+
+	/**
+	 * General OTLP endpoint (used if specific endpoints not set)
+	 */
+	otlpEndpoint?: string;
+
+	/**
+	 * General OTLP headers
+	 */
+	otlpHeaders?: Record<string, string>;
+
+	/**
+	 * Metrics-specific OTLP protocol
+	 */
+	otlpMetricsProtocol?: string;
+
+	/**
+	 * Metrics-specific OTLP endpoint
+	 */
+	otlpMetricsEndpoint?: string;
+
+	otlpMetricsHeaders?: Record<string, string>;
+
+	/**
+	 * Logs-specific OTLP protocol
+	 */
+	otlpLogsProtocol?: string;
+
+	/**
+	 * Logs-specific OTLP endpoint
+	 */
+	otlpLogsEndpoint?: string;
+
+	otlpLogsHeaders?: Record<string, string>;
+
+	/**
+	 * Metric export interval in milliseconds (for console exporter)
+	 */
+	metricExportInterval?: number;
+
+	/**
+	 * Whether to use insecure (non-TLS) connections for gRPC OTLP exporters
+	 * Set to "true" for local development without TLS
+	 * Default: false (uses TLS)
+	 */
+	otlpInsecure?: boolean;
+
+	/**
+	 * Maximum batch size for log records (default: 512)
+	 */
+	logBatchSize?: number;
+
+	/**
+	 * Maximum time to wait before exporting logs in milliseconds (default: 5000)
+	 */
+	logBatchTimeout?: number;
+
+	/**
+	 * Maximum queue size for log records (default: 2048)
+	 */
+	logMaxQueueSize?: number;
+}

package/src/session/hook-context.ts

@@ -0,0 +1,54 @@
+export interface HookSessionContext {
+	rootSessionId?: string;
+	hookLogPath?: string;
+}
+
+export interface HookSessionContextLookup {
+	hookName?: string;
+	conversationId?: string;
+	agentId?: string;
+	parentAgentId?: string | null;
+}
+
+export type HookSessionContextProvider =
+	| HookSessionContext
+	| ((input?: HookSessionContextLookup) => HookSessionContext | undefined);
+
+function normalized(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+export function resolveHookSessionContext(
+	provider?: HookSessionContextProvider,
+	input?: HookSessionContextLookup,
+): HookSessionContext | undefined {
+	if (!provider) {
+		return undefined;
+	}
+	const context = typeof provider === "function" ? provider(input) : provider;
+	if (!context) {
+		return undefined;
+	}
+	const rootSessionId = normalized(context.rootSessionId);
+	const hookLogPath = normalized(context.hookLogPath);
+	if (!rootSessionId && !hookLogPath) {
+		return undefined;
+	}
+	return {
+		rootSessionId,
+		hookLogPath,
+	};
+}
+
+export function resolveRootSessionId(
+	context: HookSessionContext | undefined,
+): string | undefined {
+	return normalized(context?.rootSessionId);
+}
+
+export function resolveHookLogPath(
+	context: HookSessionContext | undefined,
+): string | undefined {
+	return normalized(context?.hookLogPath);
+}

package/src/session/records.ts

@@ -0,0 +1,40 @@
+export const SESSION_STATUS_VALUES = [
+	"running",
+	"completed",
+	"failed",
+	"cancelled",
+] as const;
+
+export type SharedSessionStatus = (typeof SESSION_STATUS_VALUES)[number];
+
+export interface SessionLineage {
+	parentSessionId?: string;
+	agentId?: string;
+	parentAgentId?: string;
+	conversationId?: string;
+	isSubagent: boolean;
+}
+
+export interface SessionRuntimeRecordShape extends SessionLineage {
+	source: string;
+	pid?: number;
+	startedAt: string;
+	endedAt?: string | null;
+	exitCode?: number | null;
+	status: SharedSessionStatus;
+	interactive: boolean;
+	provider: string;
+	model: string;
+	cwd: string;
+	workspaceRoot: string;
+	teamName?: string;
+	enableTools: boolean;
+	enableSpawn: boolean;
+	enableTeams: boolean;
+	prompt?: string;
+	metadata?: Record<string, unknown>;
+	transcriptPath?: string;
+	hookPath?: string;
+	messagesPath?: string;
+	updatedAt: string;
+}

package/src/session/runtime-config.ts

@@ -0,0 +1,24 @@
+import type { ToolPolicy } from "../llms/tools";
+
+export type AgentMode = "act" | "plan";
+
+export interface SessionPromptConfig {
+	mode?: AgentMode;
+	systemPrompt?: string;
+	rules?: string;
+	maxIterations?: number;
+}
+
+export interface SessionWorkspaceConfig {
+	cwd: string;
+	workspaceRoot?: string;
+}
+
+export interface SessionExecutionConfig {
+	enableTools: boolean;
+	teamName?: string;
+	missionLogIntervalSteps?: number;
+	missionLogIntervalMs?: number;
+	maxConsecutiveMistakes?: number;
+	toolPolicies?: Record<string, ToolPolicy>;
+}

package/src/session/runtime-env.ts

@@ -0,0 +1,8 @@
+export interface RuntimeEnv {
+	name: string;
+	version: string;
+	platform: string;
+	platform_version: string;
+	os_type: string;
+	os_version: string;
+}