@clinebot/core 0.0.6 → 0.0.10

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", () => {
@@ -261,7 +375,7 @@ describe("zod schema conversion", () => {
 });
 
 describe("default editor tool", () => {
-	it("accepts null for unused optional fields on str_replace", async () => {
+	it("accepts replacement edits without insert fields", async () => {
 		const execute = vi.fn(async () => "patched");
 		const tools = createDefaultTools({
 			executors: {
@@ -284,12 +398,9 @@ describe("default editor tool", () => {
 
 		const result = await editorTool.execute(
 			{
-				command: "str_replace",
 				path: "/tmp/example.ts",
-				old_str: "before",
-				new_str: "after",
-				file_text: null,
-				insert_line: null,
+				old_text: "before",
+				new_text: "after",
 			},
 			{
 				agentId: "agent-1",
@@ -299,18 +410,15 @@ describe("default editor tool", () => {
 		);
 
 		expect(result).toEqual({
-			query: "str_replace:/tmp/example.ts",
+			query: "edit:/tmp/example.ts",
 			result: "patched",
 			success: true,
 		});
 		expect(execute).toHaveBeenCalledWith(
 			expect.objectContaining({
-				command: "str_replace",
 				path: "/tmp/example.ts",
-				old_str: "before",
-				new_str: "after",
-				file_text: null,
-				insert_line: null,
+				old_text: "before",
+				new_text: "after",
 			}),
 			process.cwd(),
 			expect.objectContaining({
@@ -321,7 +429,7 @@ describe("default editor tool", () => {
 		);
 	});
 
-	it("still rejects null for required insert fields", async () => {
+	it("allows edit without old_text so missing files can be created", async () => {
 		const execute = vi.fn(async () => "patched");
 		const tools = createDefaultTools({
 			executors: {
@@ -342,21 +450,80 @@ describe("default editor tool", () => {
 			throw new Error("Expected editor tool to be defined.");
 		}
 
-		await expect(
-			editorTool.execute(
-				{
-					command: "insert",
-					path: "/tmp/example.ts",
-					new_str: "after",
-					insert_line: null,
-				},
-				{
-					agentId: "agent-1",
-					conversationId: "conv-1",
-					iteration: 1,
-				},
-			),
-		).rejects.toThrow(/insert_line is required for command=insert/);
-		expect(execute).not.toHaveBeenCalled();
+		const result = await editorTool.execute(
+			{
+				path: "/tmp/example.ts",
+				new_text: "created",
+			},
+			{
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			},
+		);
+
+		expect(result).toEqual({
+			query: "edit:/tmp/example.ts",
+			result: "patched",
+			success: true,
+		});
+		expect(execute).toHaveBeenCalledWith(
+			expect.objectContaining({
+				path: "/tmp/example.ts",
+				new_text: "created",
+			}),
+			process.cwd(),
+			expect.anything(),
+		);
+	});
+
+	it("treats insert_line as an insert operation", async () => {
+		const execute = vi.fn(async () => "patched");
+		const tools = createDefaultTools({
+			executors: {
+				editor: execute,
+			},
+			enableReadFiles: false,
+			enableSearch: false,
+			enableBash: false,
+			enableWebFetch: false,
+			enableSkills: false,
+			enableAskQuestion: false,
+			enableApplyPatch: false,
+			enableEditor: true,
+		});
+		const editorTool = tools.find((tool) => tool.name === "editor");
+		expect(editorTool).toBeDefined();
+		if (!editorTool) {
+			throw new Error("Expected editor tool to be defined.");
+		}
+
+		const result = await editorTool.execute(
+			{
+				path: "/tmp/example.ts",
+				new_text: "after",
+				insert_line: 3,
+			},
+			{
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			},
+		);
+
+		expect(result).toEqual({
+			query: "insert:/tmp/example.ts",
+			result: "patched",
+			success: true,
+		});
+		expect(execute).toHaveBeenCalledWith(
+			expect.objectContaining({
+				path: "/tmp/example.ts",
+				new_text: "after",
+				insert_line: 3,
+			}),
+			process.cwd(),
+			expect.anything(),
+		);
 	});
 });

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(
@@ -432,14 +468,16 @@ export function createEditorTool(
 	return createTool<EditFileInput, ToolOperationResult>({
 		name: "editor",
 		description:
-			"Edit file using absolute path with create, string replacement, and line insert operations. " +
-			"Supported commands: create, str_replace, insert.",
+			"An editor for controlled filesystem edits on the text file at the provided path. " +
+			"Provide `insert_line` to insert `new_text` at a specific line number. " +
+			"Otherwise, the tool replaces `old_text` with `new_text`, or creates the file with `new_text` if it does not exist.",
 		inputSchema: zodToJsonSchema(EditFileInputSchema),
 		timeoutMs,
 		retryable: false, // Editing operations are stateful and should not auto-retry
 		maxRetries: 0,
 		execute: async (input, context) => {
 			const validatedInput = validateWithZod(EditFileInputSchema, input);
+			const operation = validatedInput.insert_line == null ? "edit" : "insert";
 
 			try {
 				const result = await withTimeout(
@@ -449,14 +487,14 @@ export function createEditorTool(
 				);
 
 				return {
-					query: `${validatedInput.command}:${validatedInput.path}`,
+					query: `${operation}:${validatedInput.path}`,
 					result,
 					success: true,
 				};
 			} catch (error) {
 				const msg = formatError(error);
 				return {
-					query: `${validatedInput.command}:${validatedInput.path}`,
+					query: `${operation}:${validatedInput.path}`,
 					result: "",
 					error: `Editor operation failed: ${msg}`,
 					success: false,
@@ -560,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) => {

package/src/tools/executors/editor.test.ts

@@ -0,0 +1,35 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import { createEditorExecutor } from "./editor.js";
+
+describe("createEditorExecutor", () => {
+	it("creates a missing file when edit is used", async () => {
+		const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agents-editor-"));
+		const filePath = path.join(dir, "example.txt");
+
+		try {
+			const editor = createEditorExecutor();
+			const result = await editor(
+				{
+					path: filePath,
+					new_text: "created with edit",
+				},
+				dir,
+				{
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					iteration: 1,
+				},
+			);
+
+			expect(result).toBe(`File created successfully at: ${filePath}`);
+			await expect(fs.readFile(filePath, "utf-8")).resolves.toBe(
+				"created with edit",
+			);
+		} finally {
+			await fs.rm(dir, { recursive: true, force: true });
+		}
+	});
+});

package/src/tools/executors/editor.ts

@@ -113,6 +113,15 @@ async function createFile(
 	return `File created successfully at: ${filePath}`;
 }
 
+async function fileExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 async function replaceInFile(
 	filePath: string,
 	oldStr: string,
@@ -181,52 +190,30 @@ export function createEditorExecutor(
 	): Promise<string> => {
 		const filePath = resolveFilePath(cwd, input.path, restrictToCwd);
 
-		switch (input.command) {
-			case "create":
-				if (input.file_text == null) {
-					throw new Error(
-						"Parameter `file_text` is required for command: create",
-					);
-				}
-				return createFile(filePath, input.file_text, encoding);
-
-			case "str_replace":
-				if (input.old_str == null) {
-					throw new Error(
-						"Parameter `old_str` is required for command: str_replace",
-					);
-				}
-				return replaceInFile(
-					filePath,
-					input.old_str,
-					input.new_str,
-					encoding,
-					maxDiffLines,
-				);
-
-			case "insert":
-				if (input.insert_line == null) {
-					throw new Error(
-						"Parameter `insert_line` is required for insert command.",
-					);
-				}
-				if (input.new_str == null) {
-					throw new Error(
-						"Parameter `new_str` is required for insert command.",
-					);
-				}
-				return insertInFile(
-					filePath,
-					input.insert_line, // One-based index
-					input.new_str,
-					encoding,
-				);
-
-			default:
-				throw new Error(
-					`Unrecognized command ${(input as { command: string }).command}. ` +
-						"Allowed commands are: create, str_replace, insert",
-				);
+		if (input.insert_line != null) {
+			return insertInFile(
+				filePath,
+				input.insert_line, // One-based index
+				input.new_text,
+				encoding,
+			);
+		}
+
+		if (!(await fileExists(filePath))) {
+			return createFile(filePath, input.new_text, encoding);
+		}
+		if (input.old_text == null) {
+			throw new Error(
+				"Parameter `old_text` is required when editing an existing file without `insert_line`",
+			);
 		}
+
+		return replaceInFile(
+			filePath,
+			input.old_text,
+			input.new_text,
+			encoding,
+			maxDiffLines,
+		);
 	};
 }

package/src/tools/executors/file-read.test.ts

@@ -12,14 +12,38 @@ describe("createFileReadExecutor", () => {
 
 		try {
 			const readFile = createFileReadExecutor();
-			const result = await readFile(filePath, {
-				agentId: "agent-1",
-				conversationId: "conv-1",
-				iteration: 1,
-			});
+			const result = await readFile(
+				{ path: filePath },
+				{
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					iteration: 1,
+				},
+			);
 			expect(result).toBe("1 | hello absolute path");
 		} finally {
 			await fs.rm(dir, { recursive: true, force: true });
 		}
 	});
+
+	it("returns only the requested inclusive line range", async () => {
+		const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agents-file-read-"));
+		const filePath = path.join(dir, "example.txt");
+		await fs.writeFile(filePath, "alpha\nbeta\ngamma\ndelta", "utf-8");
+
+		try {
+			const readFile = createFileReadExecutor();
+			const result = await readFile(
+				{ path: filePath, start_line: 2, end_line: 3 },
+				{
+					agentId: "agent-1",
+					conversationId: "conv-1",
+					iteration: 1,
+				},
+			);
+			expect(result).toBe("2 | beta\n3 | gamma");
+		} finally {
+			await fs.rm(dir, { recursive: true, force: true });
+		}
+	});
 });