@clinebot/core 0.0.0

package/src/account/rpc.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	type ClineAccountOperations,
+	executeRpcClineAccountAction,
+	RpcClineAccountService,
+} from "./rpc";
+
+describe("executeRpcClineAccountAction", () => {
+	it("dispatches fetchMe", async () => {
+		const service: ClineAccountOperations = {
+			fetchMe: vi.fn(async () => ({
+				id: "u1",
+				email: "user1@example.com",
+				displayName: "User 1",
+				photoUrl: "",
+				createdAt: "2025-01-01T00:00:00Z",
+				updatedAt: "2025-01-01T00:00:00Z",
+				organizations: [],
+			})),
+			fetchBalance: vi.fn(async () => ({ balance: 1, userId: "u1" })),
+			fetchUsageTransactions: vi.fn(async () => []),
+			fetchPaymentTransactions: vi.fn(async () => []),
+			fetchUserOrganizations: vi.fn(async () => []),
+			fetchOrganizationBalance: vi.fn(async () => ({
+				balance: 1,
+				organizationId: "org-1",
+			})),
+			fetchOrganizationUsageTransactions: vi.fn(async () => []),
+			switchAccount: vi.fn(async () => {}),
+		};
+
+		const result = await executeRpcClineAccountAction(
+			{ action: "clineAccount", operation: "fetchMe" },
+			service,
+		);
+		expect(service.fetchMe).toHaveBeenCalledTimes(1);
+		expect(result).toMatchObject({ id: "u1" });
+	});
+});
+
+describe("RpcClineAccountService", () => {
+	it("sends provider action payload and parses response", async () => {
+		const runProviderAction = vi.fn(async (request: unknown) => {
+			const parsed = request as {
+				action: string;
+				operation: string;
+			};
+			expect(parsed).toEqual({
+				action: "clineAccount",
+				operation: "fetchMe",
+			});
+			return {
+				result: { id: "u2", email: "u2@example.com" },
+			};
+		});
+		const service = new RpcClineAccountService({ runProviderAction });
+
+		const me = await service.fetchMe();
+		expect(runProviderAction).toHaveBeenCalledTimes(1);
+		expect(me).toEqual({ id: "u2", email: "u2@example.com" });
+	});
+});

package/src/account/rpc.ts

@@ -0,0 +1,172 @@
+import type {
+	RpcClineAccountActionRequest,
+	RpcProviderActionRequest,
+} from "@clinebot/shared";
+import type {
+	ClineAccountBalance,
+	ClineAccountOrganization,
+	ClineAccountOrganizationBalance,
+	ClineAccountOrganizationUsageTransaction,
+	ClineAccountPaymentTransaction,
+	ClineAccountUsageTransaction,
+	ClineAccountUser,
+} from "./types";
+
+export interface ClineAccountOperations {
+	fetchMe(): Promise<ClineAccountUser>;
+	fetchBalance(userId?: string): Promise<ClineAccountBalance>;
+	fetchUsageTransactions(
+		userId?: string,
+	): Promise<ClineAccountUsageTransaction[]>;
+	fetchPaymentTransactions(
+		userId?: string,
+	): Promise<ClineAccountPaymentTransaction[]>;
+	fetchUserOrganizations(): Promise<ClineAccountOrganization[]>;
+	fetchOrganizationBalance(
+		organizationId: string,
+	): Promise<ClineAccountOrganizationBalance>;
+	fetchOrganizationUsageTransactions(input: {
+		organizationId: string;
+		memberId?: string;
+	}): Promise<ClineAccountOrganizationUsageTransaction[]>;
+	switchAccount(organizationId?: string | null): Promise<void>;
+}
+
+export function isRpcClineAccountActionRequest(
+	request: RpcProviderActionRequest,
+): request is RpcClineAccountActionRequest {
+	return request.action === "clineAccount";
+}
+
+export async function executeRpcClineAccountAction(
+	request: RpcClineAccountActionRequest,
+	service: ClineAccountOperations,
+): Promise<unknown> {
+	switch (request.operation) {
+		case "fetchMe":
+			return service.fetchMe();
+		case "fetchBalance":
+			return service.fetchBalance(request.userId);
+		case "fetchUsageTransactions":
+			return service.fetchUsageTransactions(request.userId);
+		case "fetchPaymentTransactions":
+			return service.fetchPaymentTransactions(request.userId);
+		case "fetchUserOrganizations":
+			return service.fetchUserOrganizations();
+		case "fetchOrganizationBalance":
+			return service.fetchOrganizationBalance(request.organizationId);
+		case "fetchOrganizationUsageTransactions":
+			return service.fetchOrganizationUsageTransactions({
+				organizationId: request.organizationId,
+				memberId: request.memberId,
+			});
+		case "switchAccount":
+			await service.switchAccount(request.organizationId);
+			return { updated: true };
+		default: {
+			const exhaustive: never = request;
+			throw new Error(
+				`Unsupported Cline account operation: ${String(exhaustive)}`,
+			);
+		}
+	}
+}
+
+export interface RpcProviderActionExecutor {
+	runProviderAction(request: RpcProviderActionRequest): Promise<{
+		result: unknown;
+	}>;
+}
+
+export class RpcClineAccountService implements ClineAccountOperations {
+	private readonly executor: RpcProviderActionExecutor;
+
+	constructor(executor: RpcProviderActionExecutor) {
+		this.executor = executor;
+	}
+
+	public async fetchMe(): Promise<ClineAccountUser> {
+		return this.request<ClineAccountUser>({
+			action: "clineAccount",
+			operation: "fetchMe",
+		});
+	}
+
+	public async fetchBalance(userId?: string): Promise<ClineAccountBalance> {
+		return this.request<ClineAccountBalance>({
+			action: "clineAccount",
+			operation: "fetchBalance",
+			...(userId?.trim() ? { userId: userId.trim() } : {}),
+		});
+	}
+
+	public async fetchUsageTransactions(
+		userId?: string,
+	): Promise<ClineAccountUsageTransaction[]> {
+		return this.request<ClineAccountUsageTransaction[]>({
+			action: "clineAccount",
+			operation: "fetchUsageTransactions",
+			...(userId?.trim() ? { userId: userId.trim() } : {}),
+		});
+	}
+
+	public async fetchPaymentTransactions(
+		userId?: string,
+	): Promise<ClineAccountPaymentTransaction[]> {
+		return this.request<ClineAccountPaymentTransaction[]>({
+			action: "clineAccount",
+			operation: "fetchPaymentTransactions",
+			...(userId?.trim() ? { userId: userId.trim() } : {}),
+		});
+	}
+
+	public async fetchUserOrganizations(): Promise<ClineAccountOrganization[]> {
+		return this.request<ClineAccountOrganization[]>({
+			action: "clineAccount",
+			operation: "fetchUserOrganizations",
+		});
+	}
+
+	public async fetchOrganizationBalance(
+		organizationId: string,
+	): Promise<ClineAccountOrganizationBalance> {
+		const orgId = organizationId.trim();
+		if (!orgId) {
+			throw new Error("organizationId is required");
+		}
+		return this.request<ClineAccountOrganizationBalance>({
+			action: "clineAccount",
+			operation: "fetchOrganizationBalance",
+			organizationId: orgId,
+		});
+	}
+
+	public async fetchOrganizationUsageTransactions(input: {
+		organizationId: string;
+		memberId?: string;
+	}): Promise<ClineAccountOrganizationUsageTransaction[]> {
+		const orgId = input.organizationId.trim();
+		if (!orgId) {
+			throw new Error("organizationId is required");
+		}
+		return this.request<ClineAccountOrganizationUsageTransaction[]>({
+			action: "clineAccount",
+			operation: "fetchOrganizationUsageTransactions",
+			organizationId: orgId,
+			...(input.memberId?.trim() ? { memberId: input.memberId.trim() } : {}),
+		});
+	}
+
+	public async switchAccount(organizationId?: string | null): Promise<void> {
+		await this.request<{ updated: boolean }>({
+			action: "clineAccount",
+			operation: "switchAccount",
+			organizationId: organizationId?.trim() || null,
+		});
+	}
+
+	private async request<T>(request: RpcClineAccountActionRequest): Promise<T> {
+		const response = await this.executor.runProviderAction(request);
+		return response.result as T;
+	}
+}

package/src/account/types.ts

@@ -0,0 +1,80 @@
+export interface ClineAccountOrganization {
+	active: boolean;
+	memberId: string;
+	name: string;
+	organizationId: string;
+	roles: Array<"admin" | "member" | "owner">;
+}
+
+export interface ClineAccountUser {
+	id: string;
+	email: string;
+	displayName: string;
+	photoUrl: string;
+	createdAt: string;
+	updatedAt: string;
+	organizations: ClineAccountOrganization[];
+}
+
+export interface ClineAccountBalance {
+	balance: number;
+	userId: string;
+}
+
+export interface ClineAccountUsageTransaction {
+	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 ClineAccountPaymentTransaction {
+	paidAt: string;
+	creatorId: string;
+	amountCents: number;
+	credits: number;
+}
+
+export interface ClineAccountOrganizationBalance {
+	balance: number;
+	organizationId: string;
+}
+
+export interface ClineAccountOrganizationUsageTransaction {
+	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;
+}

package/src/agents/agent-config-loader.test.ts

@@ -0,0 +1,234 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Tool, ToolContext } from "@clinebot/agents";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	createAgentConfigDefinition,
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	readAgentConfigsFromDisk,
+	resolveAgentConfigSearchPaths,
+	resolveAgentsConfigDirPath,
+	resolveAgentTools,
+	resolveDocumentsAgentConfigDirectoryPath,
+	toPartialAgentConfig,
+} from "./agent-config-loader";
+
+function createMockTool(name: string): Tool {
+	return {
+		name,
+		description: `${name} tool`,
+		inputSchema: {
+			type: "object",
+			properties: {},
+		},
+		execute: async (_input: unknown, _context: ToolContext) => null,
+	};
+}
+
+describe("agent config YAML loader", () => {
+	const envSnapshot = {
+		CLINE_DATA_DIR: process.env.CLINE_DATA_DIR,
+	};
+	afterEach(() => {
+		process.env.CLINE_DATA_DIR = envSnapshot.CLINE_DATA_DIR;
+	});
+
+	it("resolves default agents settings directory from CLINE_DATA_DIR", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		expect(resolveAgentsConfigDirPath()).toBe(
+			`/tmp/cline-data/settings/${AGENT_CONFIG_DIRECTORY_NAME}`,
+		);
+	});
+
+	it("includes documents and settings search paths", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		expect(resolveAgentConfigSearchPaths()).toEqual([
+			resolveDocumentsAgentConfigDirectoryPath(),
+			`/tmp/cline-data/settings/${AGENT_CONFIG_DIRECTORY_NAME}`,
+		]);
+	});
+
+	it("builds a reusable unified watcher definition with expected defaults", () => {
+		process.env.CLINE_DATA_DIR = "/tmp/cline-data";
+		const definition = createAgentConfigDefinition();
+		expect(definition.type).toBe("agent");
+		expect(definition.directories).toEqual([
+			resolveDocumentsAgentConfigDirectoryPath(),
+			`/tmp/cline-data/settings/${AGENT_CONFIG_DIRECTORY_NAME}`,
+		]);
+		expect(definition.includeFile?.("agent.yaml", "/tmp/agent.yaml")).toBe(
+			true,
+		);
+		expect(definition.includeFile?.("agent.md", "/tmp/agent.md")).toBe(false);
+	});
+
+	it("parses yaml frontmatter and prompt body", () => {
+		const content = `---
+name: Researcher
+description: Focus on repository analysis
+modelId: claude-sonnet-4-6
+tools:
+  - read_files
+  - search_codebase
+skills:
+  - context-gathering
+---
+You are a focused codebase researcher.`;
+
+		const parsed = parseAgentConfigFromYaml(content);
+
+		expect(parsed).toEqual({
+			name: "Researcher",
+			description: "Focus on repository analysis",
+			modelId: "claude-sonnet-4-6",
+			tools: ["read_files", "search_codebase"],
+			skills: ["context-gathering"],
+			systemPrompt: "You are a focused codebase researcher.",
+		});
+	});
+
+	it("supports comma-separated tool and skill values", () => {
+		const parsed = parseAgentConfigFromYaml(`---
+name: Reviewer
+description: Reviews diffs
+tools: read_files,search_codebase,read_files
+skills: quality, quality,architecture
+---
+Review every patch for regressions.`);
+
+		expect(parsed.tools).toEqual(["read_files", "search_codebase"]);
+		expect(parsed.skills).toEqual(["quality", "architecture"]);
+	});
+
+	it("throws when frontmatter is missing", () => {
+		expect(() => parseAgentConfigFromYaml("No frontmatter")).toThrow(
+			"Missing YAML frontmatter block in agent config file.",
+		);
+	});
+
+	it("throws for unknown tools", () => {
+		expect(() =>
+			parseAgentConfigFromYaml(`---
+name: UnknownTool
+description: test
+tools: invalid_tool
+---
+prompt`),
+		).toThrow("Unknown tool 'invalid_tool'.");
+	});
+
+	it("resolves configured tool names from available tools", () => {
+		const readFiles = createMockTool("read_files");
+		const searchCodebase = createMockTool("search_codebase");
+
+		expect(
+			resolveAgentTools(
+				["read_files", "search_codebase"],
+				[searchCodebase, readFiles],
+			),
+		).toEqual([readFiles, searchCodebase]);
+	});
+
+	it("converts parsed config to partial AgentConfig", () => {
+		const readFiles = createMockTool("read_files");
+		const config = parseAgentConfigFromYaml(`---
+name: Reader
+description: Reads files
+modelId: claude-sonnet-4-6
+tools: read_files
+---
+Be precise.`);
+
+		const partial = toPartialAgentConfig(config, {
+			availableTools: [readFiles],
+		});
+
+		expect(partial.modelId).toBe("claude-sonnet-4-6");
+		expect(partial.systemPrompt).toBe("Be precise.");
+		expect(partial.tools).toEqual([readFiles]);
+	});
+
+	it("throws when tool overrides are configured without available tools", () => {
+		expect(() =>
+			parsePartialAgentConfigFromYaml(`---
+name: Reader
+description: Reads files
+tools: read_files
+---
+Be precise.`),
+		).toThrow(
+			"Configured tools cannot be converted into AgentConfig.tools without availableTools.",
+		);
+	});
+
+	it("reads agent configs from ~/.cline/data/settings/agents-compatible directory", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-agent-config-loader-"));
+		const agentsDir = join(tempRoot, "settings", AGENT_CONFIG_DIRECTORY_NAME);
+		await mkdir(agentsDir, { recursive: true });
+		try {
+			await writeFile(
+				join(agentsDir, "reviewer.yaml"),
+				`---
+name: Reviewer
+description: Reviews patches
+tools: read_files
+---
+Review code for regressions.`,
+			);
+			await writeFile(
+				join(agentsDir, "invalid.yaml"),
+				`---
+name:
+---
+`,
+			);
+
+			const loaded = await readAgentConfigsFromDisk(agentsDir);
+			expect([...loaded.keys()]).toEqual(["reviewer"]);
+			expect(loaded.get("reviewer")?.systemPrompt).toBe(
+				"Review code for regressions.",
+			);
+		} finally {
+			await rm(tempRoot, { recursive: true, force: true });
+		}
+	});
+
+	it("reads from both documents and settings directories", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-agent-config-loader-"));
+		const documentsDir = join(tempRoot, "Documents", "Cline", "Agents");
+		const settingsDir = join(tempRoot, "settings", AGENT_CONFIG_DIRECTORY_NAME);
+		await mkdir(documentsDir, { recursive: true });
+		await mkdir(settingsDir, { recursive: true });
+		try {
+			await writeFile(
+				join(documentsDir, "legacy.yaml"),
+				`---
+name: LegacyAgent
+description: legacy
+---
+legacy prompt`,
+			);
+			await writeFile(
+				join(settingsDir, "new.yaml"),
+				`---
+name: NewAgent
+description: new
+---
+new prompt`,
+			);
+
+			const loaded = await readAgentConfigsFromDisk([
+				documentsDir,
+				settingsDir,
+			]);
+			expect([...loaded.keys()].sort()).toEqual(["legacyagent", "newagent"]);
+			expect(loaded.get("legacyagent")?.systemPrompt).toBe("legacy prompt");
+			expect(loaded.get("newagent")?.systemPrompt).toBe("new prompt");
+		} finally {
+			await rm(tempRoot, { recursive: true, force: true });
+		}
+	});
+});

package/src/agents/agent-config-loader.ts

@@ -0,0 +1,107 @@
+import {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	resolveAgentConfigSearchPaths as resolveAgentConfigSearchPathsFromShared,
+	resolveAgentsConfigDirPath as resolveAgentsConfigDirPathFromShared,
+	resolveDocumentsAgentConfigDirectoryPath,
+} from "@clinebot/shared/storage";
+import {
+	type AgentYamlConfig,
+	isAgentConfigYamlFile,
+	normalizeAgentConfigName,
+	parseAgentConfigFromYaml,
+} from "./agent-config-parser";
+import {
+	type UnifiedConfigDefinition,
+	UnifiedConfigFileWatcher,
+	type UnifiedConfigWatcherEvent,
+} from "./unified-config-file-watcher";
+
+export type {
+	AgentYamlConfig,
+	BuildAgentConfigOverridesOptions,
+	ParseYamlFrontmatterResult,
+} from "./agent-config-parser";
+export {
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	resolveAgentTools,
+	toPartialAgentConfig,
+} from "./agent-config-parser";
+
+export type AgentConfigWatcher = UnifiedConfigFileWatcher<
+	"agent",
+	AgentYamlConfig
+>;
+export type AgentConfigWatcherEvent = UnifiedConfigWatcherEvent<
+	"agent",
+	AgentYamlConfig
+>;
+
+export {
+	AGENT_CONFIG_DIRECTORY_NAME,
+	resolveDocumentsAgentConfigDirectoryPath,
+};
+
+export function resolveAgentsConfigDirPath(): string {
+	return resolveAgentsConfigDirPathFromShared();
+}
+
+export function resolveAgentConfigSearchPaths(): string[] {
+	// Documents path first, then settings path so settings location takes precedence.
+	return resolveAgentConfigSearchPathsFromShared();
+}
+
+export interface CreateAgentConfigWatcherOptions {
+	directoryPathOrPaths?: string | ReadonlyArray<string>;
+	debounceMs?: number;
+	emitParseErrors?: boolean;
+}
+
+function toDirectoryPaths(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): string[] {
+	if (Array.isArray(directoryPathOrPaths)) {
+		return [...directoryPathOrPaths];
+	}
+	if (typeof directoryPathOrPaths === "string") {
+		return [directoryPathOrPaths];
+	}
+	return resolveAgentConfigSearchPaths();
+}
+
+export function createAgentConfigDefinition(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): UnifiedConfigDefinition<"agent", AgentYamlConfig> {
+	return {
+		type: "agent",
+		directories: toDirectoryPaths(directoryPathOrPaths),
+		includeFile: (fileName) => isAgentConfigYamlFile(fileName),
+		parseFile: (context) => parseAgentConfigFromYaml(context.content),
+		resolveId: (config) => normalizeAgentConfigName(config.name),
+	};
+}
+
+export function createAgentConfigWatcher(
+	options?: CreateAgentConfigWatcherOptions,
+): AgentConfigWatcher {
+	return new UnifiedConfigFileWatcher(
+		[createAgentConfigDefinition(options?.directoryPathOrPaths)],
+		{
+			debounceMs: options?.debounceMs,
+			emitParseErrors: options?.emitParseErrors,
+		},
+	);
+}
+
+export async function readAgentConfigsFromDisk(
+	directoryPathOrPaths?: string | ReadonlyArray<string>,
+): Promise<Map<string, AgentYamlConfig>> {
+	const watcher = new UnifiedConfigFileWatcher([
+		createAgentConfigDefinition(directoryPathOrPaths),
+	]);
+	await watcher.refreshAll();
+	const snapshot = watcher.getSnapshot("agent");
+	return new Map(
+		[...snapshot.entries()].map(([id, record]) => [id, record.item]),
+	);
+}