@clinebot/core 0.0.37 → 0.0.38

package/src/extensions/tools/definitions.ts

@@ -1,738 +0,0 @@
-/**
- * Default Tool Definitions
- *
- * Factory functions for creating the default tools.
- */
-
-import {
-	createTool,
-	type Tool,
-	validateWithZod,
-	zodToJsonSchema,
-} from "@clinebot/shared";
-import {
-	formatError,
-	formatReadFileQuery,
-	formatRunCommandQuery,
-	getEditorSizeError,
-	getReadFileRangeError,
-	normalizeReadFileRequests,
-	normalizeRunCommandsInput,
-	withTimeout,
-} from "./helpers";
-import {
-	type ApplyPatchInput,
-	ApplyPatchInputSchema,
-	ApplyPatchInputUnionSchema,
-	type AskQuestionInput,
-	AskQuestionInputSchema,
-	type EditFileInput,
-	EditFileInputSchema,
-	type FetchWebContentInput,
-	FetchWebContentInputSchema,
-	type ReadFilesInput,
-	ReadFilesInputSchema,
-	type RunCommandsInput,
-	RunCommandsInputSchema,
-	RunCommandsInputUnionSchema,
-	type SearchCodebaseInput,
-	SearchCodebaseInputSchema,
-	SearchCodebaseUnionInputSchema,
-	type SkillsInput,
-	SkillsInputSchema,
-	type StructuredCommandInput,
-	StructuredCommandsInputUnionSchema,
-	type SubmitInput,
-	SubmitInputSchema,
-} from "./schemas";
-import type {
-	ApplyPatchExecutor,
-	AskQuestionExecutor,
-	BashExecutor,
-	CreateDefaultToolsOptions,
-	DefaultToolsConfig,
-	EditorExecutor,
-	FileReadExecutor,
-	SearchExecutor,
-	SkillsExecutorWithMetadata,
-	ToolOperationResult,
-	VerifySubmitExecutor,
-	WebFetchExecutor,
-} from "./types";
-
-// =============================================================================
-// Helper Functions
-// =============================================================================
-
-// =============================================================================
-// Tool Factory Functions
-// =============================================================================
-
-/**
- * Create the read_files tool
- *
- * Reads the content of one or more files from the filesystem.
- */
-export function createReadFilesTool(
-	executor: FileReadExecutor,
-	config: Pick<DefaultToolsConfig, "fileReadTimeoutMs"> = {},
-): Tool<ReadFilesInput, ToolOperationResult[]> {
-	const timeoutMs = config.fileReadTimeoutMs ?? 10000;
-
-	return createTool<ReadFilesInput, ToolOperationResult[]>({
-		name: "read_files",
-		description:
-			"Read the full content of text or image 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) => {
-			const requests = normalizeReadFileRequests(input);
-
-			return Promise.all(
-				requests.map(async (request): Promise<ToolOperationResult> => {
-					const rangeError = getReadFileRangeError(request);
-					if (rangeError) {
-						return {
-							query: formatReadFileQuery(request),
-							result: "",
-							error: `Invalid file range: ${rangeError}`,
-							success: false,
-						};
-					}
-
-					try {
-						const content = await withTimeout(
-							executor(request, context),
-							timeoutMs,
-							`File read timed out after ${timeoutMs}ms`,
-						);
-						return {
-							query: formatReadFileQuery(request),
-							result: content,
-							success: true,
-						};
-					} catch (error) {
-						const msg = formatError(error);
-						return {
-							query: formatReadFileQuery(request),
-							result: "",
-							error: `Error reading file: ${msg}`,
-							success: false,
-						};
-					}
-				}),
-			);
-		},
-	});
-}
-
-/**
- * Create the search_codebase tool
- *
- * Performs regex pattern searches across the codebase.
- */
-export function createSearchTool(
-	executor: SearchExecutor,
-	config: Pick<DefaultToolsConfig, "cwd" | "searchTimeoutMs"> = {},
-): Tool<SearchCodebaseInput, ToolOperationResult[]> {
-	const timeoutMs = config.searchTimeoutMs ?? 30000;
-	const cwd = config.cwd ?? process.cwd();
-
-	return createTool<SearchCodebaseInput, ToolOperationResult[]>({
-		name: "search_codebase",
-		description:
-			"Perform regex pattern searches across the codebase. " +
-			"Supports multiple parallel searches. " +
-			"Use for finding code patterns, function definitions, class names, imports, etc.",
-		inputSchema: zodToJsonSchema(SearchCodebaseInputSchema),
-		timeoutMs: timeoutMs * 2,
-		retryable: true,
-		maxRetries: 1,
-		execute: async (input, context) => {
-			// Validate input with Zod schema
-			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> => {
-					try {
-						const results = await withTimeout(
-							executor(query, cwd, context),
-							timeoutMs,
-							`Search timed out after ${timeoutMs}ms`,
-						);
-						// Check if results contain matches
-						const hasResults =
-							results.length > 0 && !results.includes("No results found");
-						return {
-							query,
-							result: results,
-							success: hasResults,
-						};
-					} catch (error) {
-						const msg = formatError(error);
-						return {
-							query,
-							result: "",
-							error: `Search failed: ${msg}`,
-							success: false,
-						};
-					}
-				}),
-			);
-		},
-	});
-}
-
-/**
- * Create the run_commands tool
- *
- * Executes shell commands in the project directory.
- */
-export function createBashTool(
-	executor: BashExecutor,
-	config: Pick<DefaultToolsConfig, "cwd" | "bashTimeoutMs"> = {},
-): Tool<RunCommandsInput, ToolOperationResult[]> {
-	const timeoutMs = config.bashTimeoutMs ?? 30000;
-	const cwd = config.cwd ?? process.cwd();
-
-	return createTool<RunCommandsInput, ToolOperationResult[]>({
-		name: "run_commands",
-		description:
-			"Run shell commands from the root of the workspace. " +
-			"Use for listing files, checking git status, running builds, executing tests, etc. " +
-			"Commands should be properly shell-escaped.",
-		inputSchema: zodToJsonSchema(RunCommandsInputSchema),
-		timeoutMs: timeoutMs * 2,
-		retryable: false, // Shell commands often have side effects
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const validate = validateWithZod(RunCommandsInputUnionSchema, input);
-			let commands: string[];
-			if (typeof validate === "string") {
-				commands = [validate];
-			} else if (Array.isArray(validate)) {
-				commands = validate;
-			} else if ("commands" in validate) {
-				commands = Array.isArray(validate.commands)
-					? validate.commands
-					: [validate.commands];
-			} else if ("command" in validate) {
-				commands = [validate.command];
-			} else {
-				commands = [validate.cmd];
-			}
-
-			return Promise.all(
-				commands.map(async (command: string): Promise<ToolOperationResult> => {
-					try {
-						const output = await withTimeout(
-							executor(command, cwd, context),
-							timeoutMs,
-							`Command timed out after ${timeoutMs}ms`,
-						);
-						return {
-							query: command,
-							result: output,
-							success: true,
-						};
-					} catch (error) {
-						const msg = formatError(error);
-						return {
-							query: command,
-							result: "",
-							error: `Command failed: ${msg}`,
-							success: false,
-						};
-					}
-				}),
-			);
-		},
-	});
-}
-
-/**
- * Create the run_commands tool
- *
- * Executes shell commands in the project directory.
- */
-export function createWindowsShellTool(
-	executor: BashExecutor,
-	config: Pick<DefaultToolsConfig, "cwd" | "bashTimeoutMs"> = {},
-): Tool<StructuredCommandInput, ToolOperationResult[]> {
-	const timeoutMs = config.bashTimeoutMs ?? 30000;
-	const cwd = config.cwd ?? process.cwd();
-
-	return createTool<StructuredCommandInput, ToolOperationResult[]>({
-		name: "run_commands",
-		description:
-			"Run shell commands from the root of the workspacein Windows environment. " +
-			"Use for listing files, checking git status, running builds, executing tests, etc. " +
-			"Prefer structured { command, args } entries for portability; plain string commands should be properly shell-escaped.",
-		inputSchema: zodToJsonSchema(StructuredCommandsInputUnionSchema),
-		timeoutMs: timeoutMs * 2,
-		retryable: false, // Shell commands often have side effects
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const commands = normalizeRunCommandsInput(input);
-
-			return Promise.all(
-				commands.map(async (command): Promise<ToolOperationResult> => {
-					try {
-						const output = await withTimeout(
-							executor(command, cwd, context),
-							timeoutMs,
-							`Command timed out after ${timeoutMs}ms`,
-						);
-						return {
-							query: formatRunCommandQuery(command),
-							result: output,
-							success: true,
-						};
-					} catch (error) {
-						const msg = formatError(error);
-						return {
-							query: formatRunCommandQuery(command),
-							result: "",
-							error: `Command failed: ${msg}`,
-							success: false,
-						};
-					}
-				}),
-			);
-		},
-	});
-}
-
-/**
- * Create the fetch_web_content tool
- *
- * Fetches content from URLs and analyzes them using provided prompts.
- */
-export function createWebFetchTool(
-	executor: WebFetchExecutor,
-	config: Pick<DefaultToolsConfig, "webFetchTimeoutMs"> = {},
-): Tool<FetchWebContentInput, ToolOperationResult[]> {
-	const timeoutMs = config.webFetchTimeoutMs ?? 30000;
-
-	return createTool<FetchWebContentInput, ToolOperationResult[]>({
-		name: "fetch_web_content",
-		description:
-			"Fetch content from URLs and analyze them using the provided prompts. " +
-			"Use for retrieving documentation, API references, or any web content. " +
-			"Each request includes a URL and a prompt describing what information to extract.",
-		inputSchema: zodToJsonSchema(FetchWebContentInputSchema),
-		timeoutMs: timeoutMs * 2,
-		retryable: true,
-		maxRetries: 2,
-		execute: async (input, context) => {
-			// Validate input with Zod schema
-			const validatedInput = validateWithZod(FetchWebContentInputSchema, input);
-
-			return Promise.all(
-				validatedInput.requests.map(
-					async (request): Promise<ToolOperationResult> => {
-						try {
-							const content = await withTimeout(
-								executor(request.url, request.prompt, context),
-								timeoutMs,
-								`Web fetch timed out after ${timeoutMs}ms`,
-							);
-							return {
-								query: request.url,
-								result: content,
-								success: true,
-							};
-						} catch (error) {
-							const msg = formatError(error);
-							return {
-								query: request.url,
-								result: "",
-								error: `Error fetching web content: ${msg}`,
-								success: false,
-							};
-						}
-					},
-				),
-			);
-		},
-	});
-}
-
-const APPLY_PATCH_TOOL_DESC = `Use \`apply_patch\` to edit files with the canonical freeform patch grammar. Pass the patch text directly as the \`input\` string. Prefer the exact format below:
-
-*** Begin Patch
-*** Update File: path/to/file.ts
-@@ optional section marker
- [context before]
--[old line]
-+[new line]
- [context after]
-*** End Patch
-
-Supported actions:
-- \`*** Add File: <path>\`
-- \`*** Update File: <path>\`
-- \`*** Delete File: <path>\`
-- optional \`*** Move to: <new path>\` immediately after an Update File header
-
-Rules:
-- In an Add File section, every file-content line must start with \`+\`.
-- In an Update section, use context lines plus \`-\` and \`+\` lines to describe the change.
-- Use \`@@\` markers when extra context is needed to disambiguate repeated code blocks.
-- Do not use line numbers; this format is context-based.
-- Prefer sending the patch body directly. Legacy shell wrappers such as \`%%bash\` and \`apply_patch <<"EOF"\` are accepted for compatibility but are not preferred.
-
-Example:
-
-*** Begin Patch
-*** Update File: src/page.tsx
-@@
-   return (
-     <div>
-       <button onClick={() => console.log("clicked")}>Click me</button>
-+      <button onClick={() => console.log("cancel clicked")}>Cancel</button>
-     </div>
-   );
- }
-*** End Patch`;
-
-/**
- * Create the apply_patch tool
- *
- * Applies the canonical apply_patch format to one or more files.
- */
-export function createApplyPatchTool(
-	executor: ApplyPatchExecutor,
-	config: Pick<DefaultToolsConfig, "cwd" | "applyPatchTimeoutMs"> = {},
-): Tool<ApplyPatchInput, ToolOperationResult> {
-	const timeoutMs = config.applyPatchTimeoutMs ?? 30000;
-	const cwd = config.cwd ?? process.cwd();
-
-	return createTool<ApplyPatchInput, ToolOperationResult>({
-		name: "apply_patch",
-		description: APPLY_PATCH_TOOL_DESC,
-		inputSchema: zodToJsonSchema(ApplyPatchInputSchema),
-		timeoutMs,
-		retryable: false,
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const validate = validateWithZod(ApplyPatchInputUnionSchema, input);
-			const patchInput =
-				typeof validate === "string" ? validate : validate.input;
-
-			try {
-				const result = await withTimeout(
-					executor({ input: patchInput }, cwd, context),
-					timeoutMs,
-					`apply_patch timed out after ${timeoutMs}ms`,
-				);
-
-				return {
-					query: "apply_patch",
-					result,
-					success: true,
-				};
-			} catch (error) {
-				const msg = formatError(error);
-				return {
-					query: "apply_patch",
-					result: "",
-					error: `apply_patch failed: ${msg}`,
-					success: false,
-				};
-			}
-		},
-	});
-}
-
-/**
- * Create the editor tool
- *
- * Supports controlled filesystem edits with create, replace, and insert commands.
- */
-export function createEditorTool(
-	executor: EditorExecutor,
-	config: Pick<DefaultToolsConfig, "cwd" | "editorTimeoutMs"> = {},
-): Tool<EditFileInput, ToolOperationResult> {
-	const timeoutMs = config.editorTimeoutMs ?? 30000;
-	const cwd = config.cwd ?? process.cwd();
-
-	return createTool<EditFileInput, ToolOperationResult>({
-		name: "editor",
-		description:
-			"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 file does not exist. " +
-			"Use this tools for making small, precise edits to existing files or creating new files over shell commands.",
-
-		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";
-			const sizeError = getEditorSizeError(validatedInput);
-
-			if (sizeError) {
-				return {
-					query: `${operation}:${validatedInput.path}`,
-					result: "",
-					error: sizeError,
-					success: false,
-				};
-			}
-
-			try {
-				const result = await withTimeout(
-					executor(validatedInput, cwd, context),
-					timeoutMs,
-					`Editor operation timed out after ${timeoutMs}ms`,
-				);
-
-				return {
-					query: `${operation}:${validatedInput.path}`,
-					result,
-					success: true,
-				};
-			} catch (error) {
-				const msg = formatError(error);
-				return {
-					query: `${operation}:${validatedInput.path}`,
-					result: "",
-					error: `Editor operation failed: ${msg}`,
-					success: false,
-				};
-			}
-		},
-	});
-}
-
-/**
- * Create the skills tool
- *
- * Invokes a configured skill by name and optional arguments.
- */
-export function createSkillsTool(
-	executor: SkillsExecutorWithMetadata,
-	config: Pick<DefaultToolsConfig, "skillsTimeoutMs"> = {},
-): Tool<SkillsInput, string> {
-	const timeoutMs = config.skillsTimeoutMs ?? 15000;
-
-	const baseDescription =
-		"Execute a skill within the main conversation. " +
-		"When users ask you to perform tasks, check if any available skills match. " +
-		"When users reference a slash command, invoke it with this tool. " +
-		'Input: `skill` (required) and optional `args`. Example: `skill: "pdf"`, `skill: "commit", args: "-m \\"Fix bug\\""`, `skill: "review-pr", args: "123"`, `skill: "ms-office-suite:pdf"`. ' +
-		"When a skill matches the user's request, invoking this tool is a blocking requirement before any other response. " +
-		"Never mention a skill without invoking this tool.";
-
-	const tool = createTool<SkillsInput, string>({
-		name: "skills",
-		description: baseDescription,
-		inputSchema: zodToJsonSchema(SkillsInputSchema),
-		timeoutMs,
-		retryable: false,
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const validatedInput = validateWithZod(SkillsInputSchema, input);
-			return withTimeout(
-				executor(
-					validatedInput.skill,
-					validatedInput.args || undefined,
-					context,
-				),
-				timeoutMs,
-				`Skills operation timed out after ${timeoutMs}ms`,
-			);
-		},
-	});
-
-	Object.defineProperty(tool, "description", {
-		get() {
-			const skills = executor.configuredSkills
-				?.filter((s) => !s.disabled)
-				.map((s) => s.name);
-			if (skills && skills.length > 0) {
-				return `${baseDescription} Available skills: ${skills.join(", ")}.`;
-			}
-			return baseDescription;
-		},
-		enumerable: true,
-		configurable: true,
-	});
-
-	return tool;
-}
-
-/**
- * Create the ask_question tool
- *
- * Asks the user a single clarifying question with 2-5 selectable options.
- */
-export function createAskQuestionTool(
-	executor: AskQuestionExecutor,
-): Tool<AskQuestionInput, string> {
-	return {
-		name: "ask_question",
-		description:
-			"Ask user a question for clarifying or gathering information needed to complete the task. " +
-			"For example, ask the user clarifying questions about a key implementation decision. " +
-			"You should only ask one question. " +
-			"Provide an array of 2-5 options for the user to choose from. " +
-			"Never include an option to toggle to Act mode.",
-		inputSchema: zodToJsonSchema(AskQuestionInputSchema),
-		retryable: false,
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const validatedInput = validateWithZod(AskQuestionInputSchema, input);
-			return executor(validatedInput.question, validatedInput.options, context);
-		},
-	};
-}
-
-export function createSubmitAndExitTool(
-	executor: VerifySubmitExecutor,
-	config: Pick<DefaultToolsConfig, "submitTimeoutMs"> = {},
-): Tool<SubmitInput, string> {
-	const timeoutMs = config.submitTimeoutMs ?? 15000;
-
-	return createTool<SubmitInput, string>({
-		name: "submit_and_exit",
-		description:
-			"Submit the final answer and exit the conversation. " +
-			"For example, submit a summary of the investigation and confirm the issue is resolved. " +
-			"You should only submit once all necessary steps are completed. " +
-			"Provide a summary of the investigation and confirm the issue is resolved.",
-		inputSchema: zodToJsonSchema(SubmitInputSchema),
-		timeoutMs,
-		retryable: false,
-		maxRetries: 0,
-		execute: async (input, context) => {
-			const validatedInput = validateWithZod(SubmitInputSchema, input);
-			return withTimeout(
-				executor(validatedInput.summary, validatedInput.verified, context),
-				timeoutMs,
-				`submit_and_exit timed out after ${timeoutMs}ms`,
-			);
-		},
-	});
-}
-
-// =============================================================================
-// Default Tools Factory
-// =============================================================================
-
-/**
- * Create a set of default tools for an agent
- *
- * This function creates the default tools based on the provided configuration
- * and executors. Only tools that are enabled AND have an executor provided
- * will be included in the returned array.
- *
- * @example
- * ```typescript
- * import { Agent, createDefaultTools } from "@clinebot/core"
- * import * as fs from "fs/promises"
- * import { exec } from "child_process"
- *
- * const tools = createDefaultTools({
- *   executors: {
- *     readFile: async ({ path }) => fs.readFile(path, "utf-8"),
- *     bash: async (cmd, cwd) => {
- *       return new Promise((resolve, reject) => {
- *         exec(cmd, { cwd }, (err, stdout, stderr) => {
- *           if (err) reject(new Error(stderr || err.message))
- *           else resolve(stdout)
- *         })
- *       })
- *     },
- *   },
- *   enableReadFiles: true,
- *   enableBash: true,
- *   enableSearch: false, // Disabled
- *   enableWebFetch: false, // Disabled
- *   cwd: "/path/to/project",
- * })
- *
- * const agent = new Agent({
- *   // ... provider config
- *   tools,
- * })
- * ```
- */
-export function createDefaultTools(options: CreateDefaultToolsOptions): Tool[] {
-	const {
-		executors,
-		enableReadFiles = true,
-		enableSearch = true,
-		enableBash = true,
-		enableWebFetch = true,
-		enableApplyPatch = false,
-		enableEditor = true,
-		enableSkills = true,
-		enableAskQuestion = true,
-		enableSubmitAndExit = false,
-		...config
-	} = options;
-
-	const tools: Tool<any>[] = [];
-
-	// Add read_files tool if enabled and executor provided
-	if (enableReadFiles && executors.readFile) {
-		tools.push(createReadFilesTool(executors.readFile, config));
-	}
-
-	// Add search_codebase tool if enabled and executor provided
-	if (enableSearch && executors.search) {
-		tools.push(createSearchTool(executors.search, config));
-	}
-
-	// Add run_commands tool if enabled and executor provided
-	if (enableBash && executors.bash) {
-		if (process.platform === "win32") {
-			tools.push(createWindowsShellTool(executors.bash, config));
-		} else {
-			tools.push(createBashTool(executors.bash, config));
-		}
-	}
-
-	// Add fetch_web_content tool if enabled and executor provided
-	if (enableWebFetch && executors.webFetch) {
-		tools.push(createWebFetchTool(executors.webFetch, config));
-	}
-
-	// Add editor tool if enabled and executor provided,
-	// else check if apply_patch tool is enabled and executor provided
-	// NOTE: Do not enable two similar tools at the same time.
-	if (enableEditor && executors.editor) {
-		tools.push(createEditorTool(executors.editor, config));
-	} else if (enableApplyPatch && executors.applyPatch) {
-		tools.push(createApplyPatchTool(executors.applyPatch, config));
-	}
-
-	// Add skills tool if enabled and executor provided
-	if (enableSkills && executors.skills) {
-		tools.push(createSkillsTool(executors.skills, config));
-	}
-
-	// Add ask_question tool if enabled and executor provided
-	if (enableAskQuestion && executors.askQuestion) {
-		tools.push(createAskQuestionTool(executors.askQuestion));
-	} else if (enableSubmitAndExit && executors.submit) {
-		// Add submit_and_exit tool if enabled and executor provided
-		tools.push(createSubmitAndExitTool(executors.submit, config));
-	}
-
-	return tools;
-}