@clinebot/core 0.0.7 → 0.0.10

package/src/session/utils/helpers.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig, AgentEvent, AgentResult } from "@clinebot/agents";
-import type { providers as LlmsProviders } from "@clinebot/llms";
+import type { LlmsProviders } from "@clinebot/llms";
 import type { SessionSource } from "../../types/common";
 import type { SessionRecord } from "../../types/sessions";
 import { nowIso } from "../session-artifacts";

package/src/session/utils/types.ts

@@ -1,5 +1,5 @@
 import type { Agent } from "@clinebot/agents";
-import type { providers as LlmsProviders } from "@clinebot/llms";
+import type { LlmsProviders } from "@clinebot/llms";
 import type { BuiltRuntime } from "../../runtime/session-runtime";
 import type { SessionSource } from "../../types/common";
 import type { CoreSessionConfig } from "../../types/config";

package/src/storage/provider-settings-legacy-migration.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { models, providers } from "@clinebot/llms";
+import { LlmsModels, LlmsProviders } from "@clinebot/llms";
 import { resolveClineDataDir } from "@clinebot/shared/storage";
 import type { ProviderSettings } from "../types/provider-settings";
 import { emptyStoredProviderSettings } from "../types/provider-settings";
@@ -373,7 +373,7 @@ function resolveLegacyCodexAuth(
 }
 
 function getDefaultModelForProvider(providerId: string): string | undefined {
-	const builtInModels = models.getGeneratedModelsForProvider(providerId);
+	const builtInModels = LlmsModels.getGeneratedModelsForProvider(providerId);
 	const firstModelId = Object.keys(builtInModels)[0];
 	return firstModelId ?? undefined;
 }
@@ -568,7 +568,7 @@ function buildLegacyProviderSettings(
 		...(timeout ? { timeout } : {}),
 		...providerSpecific,
 	};
-	const parsed = providers.ProviderSettingsSchema.safeParse(settings);
+	const parsed = LlmsProviders.ProviderSettingsSchema.safeParse(settings);
 	if (!parsed.success) {
 		return undefined;
 	}

package/src/telemetry/core-events.ts

@@ -0,0 +1,344 @@
+import type { ITelemetryService, TelemetryProperties } from "@clinebot/shared";
+
+const MAX_ERROR_MESSAGE_LENGTH = 500;
+
+export const LegacyTelemetryEvents = {
+	USER: {
+		AUTH_STARTED: "user.auth_started",
+		AUTH_SUCCEEDED: "user.auth_succeeded",
+		AUTH_FAILED: "user.auth_failed",
+		AUTH_LOGGED_OUT: "user.auth_logged_out",
+	},
+	TASK: {
+		CREATED: "task.created",
+		RESTARTED: "task.restarted",
+		COMPLETED: "task.completed",
+		CONVERSATION_TURN: "task.conversation_turn",
+		TOKEN_USAGE: "task.tokens",
+		MODE_SWITCH: "task.mode",
+		TOOL_USED: "task.tool_used",
+		SKILL_USED: "task.skill_used",
+		DIFF_EDIT_FAILED: "task.diff_edit_failed",
+		PROVIDER_API_ERROR: "task.provider_api_error",
+		MENTION_USED: "task.mention_used",
+		MENTION_FAILED: "task.mention_failed",
+		MENTION_SEARCH_RESULTS: "task.mention_search_results",
+		SUBAGENT_STARTED: "task.subagent_started",
+		SUBAGENT_COMPLETED: "task.subagent_completed",
+	},
+	HOOKS: {
+		DISCOVERY_COMPLETED: "hooks.discovery_completed",
+	},
+} as const;
+
+function emit(
+	telemetry: ITelemetryService | undefined,
+	event: string,
+	properties?: TelemetryProperties,
+): void {
+	telemetry?.capture({ event, properties });
+}
+
+function truncateErrorMessage(errorMessage?: string): string | undefined {
+	if (!errorMessage) {
+		return undefined;
+	}
+	return errorMessage.substring(0, MAX_ERROR_MESSAGE_LENGTH);
+}
+
+export function captureAuthStarted(
+	telemetry: ITelemetryService | undefined,
+	provider?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.USER.AUTH_STARTED, { provider });
+}
+
+export function captureAuthSucceeded(
+	telemetry: ITelemetryService | undefined,
+	provider?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.USER.AUTH_SUCCEEDED, { provider });
+}
+
+export function captureAuthFailed(
+	telemetry: ITelemetryService | undefined,
+	provider?: string,
+	errorMessage?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.USER.AUTH_FAILED, {
+		provider,
+		errorMessage: truncateErrorMessage(errorMessage),
+	});
+}
+
+export function captureAuthLoggedOut(
+	telemetry: ITelemetryService | undefined,
+	provider?: string,
+	reason?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.USER.AUTH_LOGGED_OUT, {
+		provider,
+		reason,
+	});
+}
+
+export function identifyAccount(
+	telemetry: ITelemetryService | undefined,
+	account: {
+		id?: string;
+		email?: string;
+		provider?: string;
+		organizationId?: string;
+		organizationName?: string;
+		memberId?: string;
+	},
+): void {
+	const distinctId = account.id?.trim();
+	if (distinctId) {
+		telemetry?.setDistinctId(distinctId);
+	}
+	telemetry?.updateCommonProperties({
+		account_id: account.id,
+		account_email: account.email,
+		provider: account.provider,
+		organization_id: account.organizationId,
+		organization_name: account.organizationName,
+		member_id: account.memberId,
+	});
+}
+
+export function captureTaskCreated(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		apiProvider?: string;
+		openAiCompatibleDomain?: string;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.CREATED, properties);
+}
+
+export function captureTaskRestarted(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		apiProvider?: string;
+		openAiCompatibleDomain?: string;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.RESTARTED, properties);
+}
+
+export function captureTaskCompleted(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		provider?: string;
+		modelId?: string;
+		mode?: string;
+		durationMs?: number;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.COMPLETED, properties);
+}
+
+export function captureConversationTurnEvent(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		provider?: string;
+		model?: string;
+		source: "user" | "assistant";
+		mode?: string;
+		tokensIn?: number;
+		tokensOut?: number;
+		cacheWriteTokens?: number;
+		cacheReadTokens?: number;
+		totalCost?: number;
+		isNativeToolCall?: boolean;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.CONVERSATION_TURN, {
+		...properties,
+		timestamp: new Date().toISOString(),
+	});
+}
+
+export function captureTokenUsage(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		tokensIn: number;
+		tokensOut: number;
+		model: string;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.TOKEN_USAGE, properties);
+}
+
+export function captureModeSwitch(
+	telemetry: ITelemetryService | undefined,
+	ulid: string,
+	mode?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.MODE_SWITCH, { ulid, mode });
+}
+
+export function captureToolUsage(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		tool: string;
+		modelId?: string;
+		provider?: string;
+		autoApproved?: boolean;
+		success: boolean;
+		isNativeToolCall?: boolean;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.TOOL_USED, properties);
+}
+
+export function captureSkillUsed(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		skillName: string;
+		skillSource: "global" | "project";
+		skillsAvailableGlobal: number;
+		skillsAvailableProject: number;
+		provider?: string;
+		modelId?: string;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.SKILL_USED, properties);
+}
+
+export function captureDiffEditFailure(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		modelId?: string;
+		provider?: string;
+		errorType?: string;
+		isNativeToolCall?: boolean;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.DIFF_EDIT_FAILED, properties);
+}
+
+export function captureProviderApiError(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		model: string;
+		errorMessage: string;
+		provider?: string;
+		errorStatus?: number;
+		requestId?: string;
+		isNativeToolCall?: boolean;
+	},
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.PROVIDER_API_ERROR, {
+		...properties,
+		errorMessage: truncateErrorMessage(properties.errorMessage) ?? "unknown",
+		timestamp: new Date().toISOString(),
+	});
+}
+
+export function captureMentionUsed(
+	telemetry: ITelemetryService | undefined,
+	mentionType:
+		| "file"
+		| "folder"
+		| "url"
+		| "problems"
+		| "terminal"
+		| "git-changes"
+		| "commit",
+	contentLength?: number,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.MENTION_USED, {
+		mentionType,
+		contentLength,
+		timestamp: new Date().toISOString(),
+	});
+}
+
+export function captureMentionFailed(
+	telemetry: ITelemetryService | undefined,
+	mentionType:
+		| "file"
+		| "folder"
+		| "url"
+		| "problems"
+		| "terminal"
+		| "git-changes"
+		| "commit",
+	errorType:
+		| "not_found"
+		| "permission_denied"
+		| "network_error"
+		| "parse_error"
+		| "unknown",
+	errorMessage?: string,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.MENTION_FAILED, {
+		mentionType,
+		errorType,
+		errorMessage: truncateErrorMessage(errorMessage),
+		timestamp: new Date().toISOString(),
+	});
+}
+
+export function captureMentionSearchResults(
+	telemetry: ITelemetryService | undefined,
+	query: string,
+	resultCount: number,
+	searchType: "file" | "folder" | "all",
+	isEmpty: boolean,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.TASK.MENTION_SEARCH_RESULTS, {
+		queryLength: query.length,
+		resultCount,
+		searchType,
+		isEmpty,
+		timestamp: new Date().toISOString(),
+	});
+}
+
+export function captureSubagentExecution(
+	telemetry: ITelemetryService | undefined,
+	properties: {
+		ulid: string;
+		durationMs: number;
+		outputLines: number;
+		success: boolean;
+	},
+): void {
+	emit(
+		telemetry,
+		properties.success
+			? LegacyTelemetryEvents.TASK.SUBAGENT_COMPLETED
+			: LegacyTelemetryEvents.TASK.SUBAGENT_STARTED,
+		{
+			...properties,
+			timestamp: new Date().toISOString(),
+		},
+	);
+}
+
+export function captureHookDiscovery(
+	telemetry: ITelemetryService | undefined,
+	hookName: string,
+	globalCount: number,
+	workspaceCount: number,
+): void {
+	emit(telemetry, LegacyTelemetryEvents.HOOKS.DISCOVERY_COMPLETED, {
+		hookName,
+		globalCount,
+		workspaceCount,
+		totalCount: globalCount + workspaceCount,
+		timestamp: new Date().toISOString(),
+	});
+}

package/src/tools/definitions.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
-import { createDefaultTools, createReadFilesTool } from "./definitions.js";
+import {
+	createBashTool,
+	createDefaultTools,
+	createReadFilesTool,
+} from "./definitions.js";
 
 describe("default skills tool", () => {
 	it("is included only when enabled with a skills executor", () => {
@@ -213,23 +217,133 @@ describe("default apply_patch tool", () => {
 	});
 });
 
+describe("default run_commands tool", () => {
+	it("accepts object input with commands as a single string", async () => {
+		const execute = vi.fn(async (command: string) => `ran:${command}`);
+		const tool = createBashTool(execute);
+
+		const result = await tool.execute({ commands: "ls" } as never, {
+			agentId: "agent-1",
+			conversationId: "conv-1",
+			iteration: 1,
+		});
+
+		expect(result).toEqual([
+			{
+				query: "ls",
+				result: "ran:ls",
+				success: true,
+			},
+		]);
+		expect(execute).toHaveBeenCalledTimes(1);
+		expect(execute).toHaveBeenCalledWith(
+			"ls",
+			process.cwd(),
+			expect.objectContaining({
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			}),
+		);
+	});
+});
+
+describe("default read_files tool", () => {
+	it("normalizes ranged file requests and passes them to the executor", async () => {
+		const execute = vi.fn(async () => "selected lines");
+		const tool = createReadFilesTool(execute);
+
+		const result = await tool.execute(
+			{
+				files: [
+					{
+						path: "/tmp/example.ts",
+						start_line: 3,
+						end_line: 5,
+					},
+				],
+			},
+			{
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			},
+		);
+
+		expect(result).toEqual([
+			{
+				query: "/tmp/example.ts:3-5",
+				result: "selected lines",
+				success: true,
+			},
+		]);
+		expect(execute).toHaveBeenCalledWith(
+			{
+				path: "/tmp/example.ts",
+				start_line: 3,
+				end_line: 5,
+			},
+			expect.objectContaining({
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			}),
+		);
+	});
+
+	it("keeps legacy string inputs reading full file content", async () => {
+		const execute = vi.fn(async () => "full file");
+		const tool = createReadFilesTool(execute);
+
+		await tool.execute("/tmp/example.ts" as never, {
+			agentId: "agent-1",
+			conversationId: "conv-1",
+			iteration: 1,
+		});
+
+		expect(execute).toHaveBeenCalledWith(
+			{ path: "/tmp/example.ts" },
+			expect.objectContaining({
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			}),
+		);
+	});
+});
+
 describe("zod schema conversion", () => {
 	it("preserves read_files required properties in generated JSON schema", () => {
 		const tool = createReadFilesTool(async () => "ok");
 		const inputSchema = tool.inputSchema as Record<string, unknown>;
 		const properties = inputSchema.properties as Record<string, unknown>;
 		expect(inputSchema.type).toBe("object");
-		expect(properties.file_paths).toEqual({
+		expect(properties.files).toMatchObject({
 			type: "array",
 			items: {
-				type: "string",
-				description:
-					"The absolute file path of a text file to read content from",
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description:
+							"The absolute file path of a text file to read content from",
+					},
+					start_line: {
+						type: "integer",
+						description: "Optional one-based starting line number to read from",
+					},
+					end_line: {
+						type: "integer",
+						description:
+							"Optional one-based ending line number to read through",
+					},
+				},
+				required: ["path"],
 			},
 			description:
-				"Array of absolute file paths to get full content from. Prefer this tool over running terminal command to get file content for better performance and reliability.",
+				"Array of file read requests. Omit start_line and end_line to return the full file content; provide them to return only that inclusive one-based line range. Prefer this tool over running terminal command to get file content for better performance and reliability.",
 		});
-		expect(inputSchema.required).toEqual(["file_paths"]);
+		expect(inputSchema.required).toEqual(["files"]);
 	});
 
 	it("exposes skills args as optional nullable in tool schemas", () => {

package/src/tools/definitions.ts

@@ -16,6 +16,7 @@ import {
 	EditFileInputSchema,
 	type FetchWebContentInput,
 	FetchWebContentInputSchema,
+	type ReadFileRequest,
 	type ReadFilesInput,
 	ReadFilesInputSchema,
 	ReadFilesInputUnionSchema,
@@ -72,6 +73,46 @@ function withTimeout<T>(
 	]);
 }
 
+function normalizeReadFileRequests(input: unknown): ReadFileRequest[] {
+	const validate = validateWithZod(ReadFilesInputUnionSchema, input);
+
+	if (typeof validate === "string") {
+		return [{ path: validate }];
+	}
+
+	if (Array.isArray(validate)) {
+		return validate.map((value) =>
+			typeof value === "string" ? { path: value } : value,
+		);
+	}
+
+	if ("files" in validate) {
+		const files = Array.isArray(validate.files)
+			? validate.files
+			: [validate.files];
+		return files;
+	}
+
+	if ("file_paths" in validate) {
+		const filePaths = Array.isArray(validate.file_paths)
+			? validate.file_paths
+			: [validate.file_paths];
+		return filePaths.map((filePath) => ({ path: filePath }));
+	}
+
+	return [validate];
+}
+
+function formatReadFileQuery(request: ReadFileRequest): string {
+	const { path, start_line, end_line } = request;
+	if (start_line === undefined && end_line === undefined) {
+		return path;
+	}
+	const start = start_line ?? 1;
+	const end = end_line ?? "EOF";
+	return `${path}:${start}-${end}`;
+}
+
 const APPLY_PATCH_TOOL_DESC = `This is a custom utility that makes it more convenient to add, remove, move, or edit code in a single file. \`apply_patch\` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the \`apply_patch\` command, you should pass a message of the following structure as "input":
 
 %%bash
@@ -147,38 +188,32 @@ export function createReadFilesTool(
 	return createTool<ReadFilesInput, ToolOperationResult[]>({
 		name: "read_files",
 		description:
-			"Read the FULL content of text file at the provided absolute paths. " +
-			"Returns file contents or error messages for each path. ",
+			"Read the full content of text files at the provided absolute paths, or return only an inclusive one-based line range when start_line/end_line are provided. " +
+			"Returns file contents or error messages for each path.",
 		inputSchema: zodToJsonSchema(ReadFilesInputSchema),
 		timeoutMs: timeoutMs * 2, // Account for multiple files
 		retryable: true,
 		maxRetries: 1,
 		execute: async (input, context) => {
-			// Validate input with Zod schema
-			const validate = validateWithZod(ReadFilesInputUnionSchema, input);
-			const filePaths = Array.isArray(validate)
-				? validate
-				: typeof validate === "object"
-					? validate.file_paths
-					: [validate];
+			const requests = normalizeReadFileRequests(input);
 
 			return Promise.all(
-				filePaths.map(async (filePath): Promise<ToolOperationResult> => {
+				requests.map(async (request): Promise<ToolOperationResult> => {
 					try {
 						const content = await withTimeout(
-							executor(filePath, context),
+							executor(request, context),
 							timeoutMs,
 							`File read timed out after ${timeoutMs}ms`,
 						);
 						return {
-							query: filePath,
+							query: formatReadFileQuery(request),
 							result: content,
 							success: true,
 						};
 					} catch (error) {
 						const msg = formatError(error);
 						return {
-							query: filePath,
+							query: formatReadFileQuery(request),
 							result: "",
 							error: `Error reading file: ${msg}`,
 							success: false,
@@ -214,15 +249,14 @@ export function createSearchTool(
 		maxRetries: 1,
 		execute: async (input, context) => {
 			// Validate input with Zod schema
-			const validatedInput = validateWithZod(
-				SearchCodebaseUnionInputSchema,
-				input,
-			);
-			const queries = Array.isArray(validatedInput)
-				? validatedInput
-				: typeof validatedInput === "object"
-					? validatedInput.queries
-					: [validatedInput];
+			const validate = validateWithZod(SearchCodebaseUnionInputSchema, input);
+			const queries = Array.isArray(validate)
+				? validate
+				: typeof validate === "object"
+					? Array.isArray(validate.queries)
+						? validate.queries
+						: [validate.queries]
+					: [validate];
 
 			return Promise.all(
 				queries.map(async (query): Promise<ToolOperationResult> => {
@@ -282,7 +316,9 @@ export function createBashTool(
 			const commands = Array.isArray(validate)
 				? validate
 				: typeof validate === "object"
-					? validate.commands
+					? Array.isArray(validate.commands)
+						? validate.commands
+						: [validate.commands]
 					: [validate];
 
 			return Promise.all(
@@ -562,7 +598,7 @@ export function createAskQuestionTool(
  *
  * const tools = createDefaultTools({
  *   executors: {
- *     readFile: async (path) => fs.readFile(path, "utf-8"),
+ *     readFile: async ({ path }) => fs.readFile(path, "utf-8"),
  *     bash: async (cmd, cwd) => {
  *       return new Promise((resolve, reject) => {
  *         exec(cmd, { cwd }, (err, stdout, stderr) => {