@clinebot/core 0.0.22 → 0.0.24

package/src/tools/schemas.ts

@@ -0,0 +1,327 @@
+/**
+ * Zod Schemas for Default Tool Inputs
+ *
+ * These schemas define the input structure for each default tool
+ * and are used for both validation and JSON Schema generation.
+ */
+
+import { z } from "zod";
+
+export const INPUT_ARG_CHAR_LIMIT = 6000;
+
+/**
+ * Schema for read tool input
+ */
+const AbsolutePath = z
+	.string()
+	.describe("The absolute file path of a text file to read content from");
+
+export const ReadFileLineRangeSchema = z
+	.object({
+		start_line: z
+			.number()
+			.int()
+			.positive()
+			.nullable()
+			.optional()
+			.describe(
+				"Optional one-based starting line number to read from; use null or omit for the start of the file",
+			),
+		end_line: z
+			.number()
+			.int()
+			.positive()
+			.nullable()
+			.optional()
+			.describe(
+				"Optional one-based ending line number to read through; use null or omit for the end of the file",
+			),
+	})
+	.refine(
+		({ start_line, end_line }) =>
+			start_line == null || end_line == null || start_line <= end_line,
+		{
+			message: "start_line must be less than or equal to end_line",
+			path: ["end_line"],
+		},
+	);
+
+export const ReadFileRequestSchema = z
+	.object({
+		path: AbsolutePath,
+		start_line: ReadFileLineRangeSchema.shape.start_line,
+		end_line: ReadFileLineRangeSchema.shape.end_line,
+	})
+	.refine(
+		({ start_line, end_line }) =>
+			start_line == null || end_line == null || start_line <= end_line,
+		{
+			message: "start_line must be less than or equal to end_line",
+			path: ["end_line"],
+		},
+	);
+
+/**
+ * Schema for read_files tool input
+ */
+export const ReadFilesInputSchema = z.object({
+	files: z
+		.array(ReadFileRequestSchema)
+		.describe(
+			"Array of file read requests. Omit start_line/end_line or set them to null to return the full file content boundaries; provide integers 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.",
+		),
+});
+
+/**
+ * Union schema for read_files tool input, allowing either a single string, an array of strings, or the full object schema
+ */
+export const ReadFilesInputUnionSchema = z.union([
+	ReadFilesInputSchema,
+	ReadFileRequestSchema,
+	z.array(ReadFileRequestSchema),
+	z.array(z.string()),
+	z.string(),
+	z.object({ files: ReadFileRequestSchema }),
+	z.object({ file_paths: z.array(AbsolutePath) }),
+	z.object({ file_paths: z.string() }),
+]);
+
+/**
+ * Schema for search_codebase tool input
+ */
+export const SearchCodebaseInputSchema = z.object({
+	queries: z
+		.array(z.string())
+		.describe("Array of regex search queries to execute"),
+});
+
+/**
+ * Union schema for search_codebase tool input, allowing either a single string, an array of strings, or the full object schema
+ */
+export const SearchCodebaseUnionInputSchema = z.union([
+	SearchCodebaseInputSchema,
+	z.array(z.string()),
+	z.string(),
+	z.object({ queries: z.string() }),
+]);
+
+const CommandInputSchema = z
+	.string()
+	.describe(
+		`The non-interactive shell command to execute - MUST keep input short and concise (within ${INPUT_ARG_CHAR_LIMIT * 2} characters) to avoid timeouts.`,
+	);
+
+/**
+ * Schema for run_commands tool input
+ */
+export const RunCommandsInputSchema = z.object({
+	commands: z
+		.array(CommandInputSchema)
+		.describe("Array of shell commands to execute"),
+});
+
+/**
+ * Union schema for run_commands tool input. More flexible.
+ */
+export const RunCommandsInputUnionSchema = z.union([
+	RunCommandsInputSchema,
+	z.object({ commands: CommandInputSchema }),
+	z.array(z.string()),
+	z.string(),
+]);
+
+export const StructuredCommandInputSchema = z.object({
+	command: z
+		.string()
+		.min(1)
+		.describe("The executable to run directly without shell parsing."),
+	args: z
+		.array(z.string())
+		.optional()
+		.describe("Optional argv list passed directly to the executable."),
+});
+
+export const StructuredCommandEntrySchema = z.union([
+	CommandInputSchema,
+	StructuredCommandInputSchema,
+]);
+/**
+ * Schema for run_commands tool input
+ */
+export const StructuredCommandsInputSchema = z.object({
+	commands: z
+		.array(StructuredCommandEntrySchema)
+		.describe(
+			"Array of commands to execute. Prefer structured { command, args } entries for portability; plain strings are still supported and are interpreted by the active shell.",
+		),
+});
+
+/**
+ * Union schema for run_commands tool input. More flexible.
+ */
+export const StructuredCommandsInputUnionSchema = z.union([
+	RunCommandsInputSchema,
+	StructuredCommandsInputSchema,
+	z.object({ commands: StructuredCommandEntrySchema }),
+	z.array(z.string()),
+	z.array(StructuredCommandInputSchema),
+	z.string(),
+	StructuredCommandInputSchema,
+]);
+
+/**
+ * Schema for a single web fetch request
+ */
+export const WebFetchRequestSchema = z.object({
+	url: z.string().describe("The URL to fetch"),
+	prompt: z.string().min(2).describe("Analysis prompt for the fetched content"),
+});
+
+/**
+ * Schema for fetch_web_content tool input
+ */
+export const FetchWebContentInputSchema = z.object({
+	requests: z
+		.array(WebFetchRequestSchema)
+		.describe("Array of the URLs for the web fetch requests"),
+});
+
+/**
+ * Schema for editor tool input
+ */
+export const EditFileInputSchema = z
+	.object({
+		path: z
+			.string()
+			.min(1)
+			.describe("The absolute file path for the action to be performed on"),
+		old_text: z
+			.string()
+			.nullable()
+			.optional()
+			.describe(
+				`Exact text to replace (must match exactly once). Omit this when creating a missing file or inserting via insert_line. Keep this at or below ${INPUT_ARG_CHAR_LIMIT} characters when possible; larger payloads should be split across multiple tool calls to avoid timeouts.`,
+			),
+		new_text: z
+			.string()
+			.describe(
+				`The new content to write when creating a missing file, the replacement text for edits, or the inserted text when insert_line is provided. Keep this at or below ${INPUT_ARG_CHAR_LIMIT} characters when possible; for large edits, use multiple calls with small chunks of old_text and new_text to iteratively edit the file.`,
+			),
+		insert_line: z
+			.number()
+			.int()
+			.nullable()
+			.optional()
+			.describe(
+				"Optional one-based line index. When provided, the tool inserts new_text at that line instead of performing a replacement edit.",
+			),
+	})
+	.describe(
+		"Edit a text file by replacing old_text with new_text, create the file with new_text if it does not exist, or insert new_text at insert_line when insert_line is provided. Prefer using this tool for file edits over shell commands. IMPORTANT: large edits can time out, so use small chunks and multiple calls when possible.",
+	);
+
+/**
+ * Schema for apply_patch tool input
+ */
+export const ApplyPatchInputSchema = z
+	.object({
+		input: z
+			.string()
+			.min(1)
+			.describe("The apply_patch text payload, including patch instructions"),
+	})
+	.describe(
+		"Modify or create a text file by applying patches. Prefer using this tool for file edits over shell commands. IMPORTANT: large patches can time out, so use small chunks and multiple calls when possible.",
+	);
+export const ApplyPatchInputUnionSchema = z.union([
+	ApplyPatchInputSchema,
+	z.string(),
+]);
+
+/**
+ * Schema for skills tool input
+ */
+export const SkillsInputSchema = z.object({
+	skill: z.string().min(1).describe("Name of the skill to execute."),
+	args: z
+		.string()
+		.nullable()
+		.optional()
+		.describe("Arguments for the skill; use null when omitted"),
+});
+
+/**
+ * Schema for ask_followup_question tool input
+ */
+export const AskQuestionInputSchema = z.object({
+	question: z
+		.string()
+		.min(1)
+		.describe(
+			'The single question to ask the user. E.g. "How can I help you?"',
+		),
+	options: z
+		.array(z.string().min(1))
+		.min(2)
+		.max(5)
+		.describe(
+			"Array of 2-5 user-selectable answer options for the single question",
+		),
+});
+
+// =============================================================================
+// Type Definitions (derived from Zod schemas)
+// =============================================================================
+
+/**
+ * Input for a single file read request
+ */
+export type ReadFileRequest = z.infer<typeof ReadFileRequestSchema>;
+
+/**
+ * Input for the read_files tool
+ */
+export type ReadFilesInput = z.infer<typeof ReadFilesInputSchema>;
+
+/**
+ * Input for the search_codebase tool
+ */
+export type SearchCodebaseInput = z.infer<typeof SearchCodebaseInputSchema>;
+
+/**
+ * Input for the run_commands tool
+ */
+export type RunCommandsInput = z.infer<typeof RunCommandsInputSchema>;
+export type StructuredCommandInput = z.infer<
+	typeof StructuredCommandInputSchema
+>;
+
+/**
+ * Web fetch request parameters
+ */
+export type WebFetchRequest = z.infer<typeof WebFetchRequestSchema>;
+
+/**
+ * Input for the fetch_web_content tool
+ */
+export type FetchWebContentInput = z.infer<typeof FetchWebContentInputSchema>;
+
+/**
+ * Input for the editor tool
+ */
+export type EditFileInput = z.infer<typeof EditFileInputSchema>;
+
+/**
+ * Input for the apply_patch tool
+ */
+export type ApplyPatchInput = z.infer<typeof ApplyPatchInputSchema>;
+
+/**
+ * Input for the skills tool
+ */
+export type SkillsInput = z.infer<typeof SkillsInputSchema>;
+
+/**
+ * Input for the ask_followup_question tool
+ */
+export type AskQuestionInput = z.infer<typeof AskQuestionInputSchema>;

package/src/tools/types.ts

@@ -0,0 +1,329 @@
+/**
+ * Types for Default Tools
+ *
+ * Type definitions for executors, configuration, and results.
+ */
+
+import type { ToolContext } from "@clinebot/agents";
+import type {
+	ApplyPatchInput,
+	EditFileInput,
+	ReadFileRequest,
+	StructuredCommandInput,
+} from "./schemas";
+
+// =============================================================================
+// Tool Result Types
+// =============================================================================
+
+/**
+ * Result from a single tool operation
+ */
+export interface ToolOperationResult {
+	/** The query/input that was executed */
+	query: string;
+	/** The result content (if successful) */
+	result: string;
+	/** Error message (if failed) */
+	error?: string;
+	/** Whether the operation succeeded */
+	success: boolean;
+	/** Duration in MS */
+	duration?: number;
+}
+
+// =============================================================================
+// Executor Interfaces
+// =============================================================================
+
+/**
+ * Executor for reading files
+ *
+ * @param request - File path and optional inclusive line range to read
+ * @param context - Tool execution context
+ * @returns The file content as a string
+ */
+export type FileReadExecutor = (
+	request: ReadFileRequest,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for searching the codebase
+ *
+ * @param query - Regex pattern to search for
+ * @param cwd - Current working directory for the search
+ * @param context - Tool execution context
+ * @returns Search results as a formatted string
+ */
+export type SearchExecutor = (
+	query: string,
+	cwd: string,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for running shell commands
+ *
+ * @param command - Shell command to execute
+ * @param cwd - Current working directory for execution
+ * @param context - Tool execution context
+ * @returns Command output (stdout)
+ */
+export type BashExecutor = (
+	command: string | StructuredCommandInput,
+	cwd: string,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for fetching web content
+ *
+ * @param url - URL to fetch
+ * @param prompt - Analysis prompt for the content
+ * @param context - Tool execution context
+ * @returns Analyzed/extracted content
+ */
+export type WebFetchExecutor = (
+	url: string,
+	prompt: string,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for editing files
+ *
+ * @param input - Editor command input
+ * @param cwd - Current working directory for filesystem operations
+ * @param context - Tool execution context
+ * @returns A formatted operation result string
+ */
+export type EditorExecutor = (
+	input: EditFileInput,
+	cwd: string,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for apply_patch operations
+ *
+ * @param input - apply_patch command payload
+ * @param cwd - Current working directory for filesystem operations
+ * @param context - Tool execution context
+ * @returns A formatted operation result string
+ */
+export type ApplyPatchExecutor = (
+	input: ApplyPatchInput,
+	cwd: string,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for invoking configured skills
+ *
+ * @param skill - Skill name to invoke
+ * @param args - Optional arguments for the skill
+ * @param context - Tool execution context
+ * @returns Skill loading/invocation result
+ */
+export type SkillsExecutor = (
+	skill: string,
+	args: string | undefined,
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Executor for asking a single follow-up question with selectable options
+ *
+ * @param question - Single clarifying question for the user
+ * @param options - 2-5 selectable answer options
+ * @param context - Tool execution context
+ * @returns Executor-specific result payload
+ */
+export type AskQuestionExecutor = (
+	question: string,
+	options: string[],
+	context: ToolContext,
+) => Promise<string>;
+
+/**
+ * Skill metadata exposed by SkillsExecutor for clients/UI
+ */
+export interface SkillsExecutorSkillMetadata {
+	/** Normalized skill id (usually lowercased name) */
+	id: string;
+	/** Display name for the skill */
+	name: string;
+	/** Optional short description */
+	description?: string;
+	/** True when configured but intentionally disabled */
+	disabled: boolean;
+}
+
+/**
+ * A callable executor that can also expose configured skill metadata.
+ */
+export interface SkillsExecutorWithMetadata {
+	(
+		skill: string,
+		args: string | undefined,
+		context: ToolContext,
+	): Promise<string>;
+	configuredSkills?: SkillsExecutorSkillMetadata[];
+}
+
+/**
+ * Collection of all tool executors
+ */
+export interface ToolExecutors {
+	/** File reading implementation */
+	readFile?: FileReadExecutor;
+	/** Codebase search implementation */
+	search?: SearchExecutor;
+	/** Shell command execution implementation */
+	bash?: BashExecutor;
+	/** Web content fetching implementation */
+	webFetch?: WebFetchExecutor;
+	/** Filesystem editor implementation */
+	editor?: EditorExecutor;
+	/** Apply patch implementation */
+	applyPatch?: ApplyPatchExecutor;
+	/** Skill invocation implementation */
+	skills?: SkillsExecutorWithMetadata;
+	/** Follow-up question implementation */
+	askQuestion?: AskQuestionExecutor;
+}
+
+// =============================================================================
+// Tool Configuration
+// =============================================================================
+
+/**
+ * Names of available default tools
+ */
+export type DefaultToolName =
+	| "read_files"
+	| "search_codebase"
+	| "run_commands"
+	| "fetch_web_content"
+	| "apply_patch"
+	| "editor"
+	| "skills"
+	| "ask_question";
+
+/**
+ * Configuration for enabling/disabling default tools
+ */
+export interface DefaultToolsConfig {
+	/**
+	 * Enable the read_files tool
+	 * @default true
+	 */
+	enableReadFiles?: boolean;
+
+	/**
+	 * Enable the search_codebase tool
+	 * @default true
+	 */
+	enableSearch?: boolean;
+
+	/**
+	 * Enable the run_commands tool
+	 * @default true
+	 */
+	enableBash?: boolean;
+
+	/**
+	 * Enable the fetch_web_content tool
+	 * @default true
+	 */
+	enableWebFetch?: boolean;
+
+	/**
+	 * Enable the apply_patch tool
+	 * @default true
+	 */
+	enableApplyPatch?: boolean;
+
+	/**
+	 * Enable the editor tool
+	 * @default true
+	 */
+	enableEditor?: boolean;
+
+	/**
+	 * Enable the skills tool
+	 * @default true
+	 */
+	enableSkills?: boolean;
+
+	/**
+	 * Enable the ask_followup_question tool
+	 * @default true
+	 */
+	enableAskQuestion?: boolean;
+
+	/**
+	 * Current working directory for tools that need it
+	 */
+	cwd?: string;
+
+	/**
+	 * Timeout for file read operations in milliseconds
+	 * @default 10000
+	 */
+	fileReadTimeoutMs?: number;
+
+	/**
+	 * Timeout for bash command execution in milliseconds
+	 * @default 30000
+	 */
+	bashTimeoutMs?: number;
+
+	/**
+	 * Timeout for web fetch operations in milliseconds
+	 * @default 30000
+	 */
+	webFetchTimeoutMs?: number;
+
+	/**
+	 * Timeout for search operations in milliseconds
+	 * @default 30000
+	 */
+	searchTimeoutMs?: number;
+
+	/**
+	 * Timeout for apply_patch operations in milliseconds
+	 * @default 30000
+	 */
+	applyPatchTimeoutMs?: number;
+
+	/**
+	 * Timeout for editor operations in milliseconds
+	 * @default 30000
+	 */
+	editorTimeoutMs?: number;
+
+	/**
+	 * Timeout for skills operations in milliseconds
+	 * @default 15000
+	 */
+	skillsTimeoutMs?: number;
+
+	/**
+	 * Timeout for ask_followup_question operations in milliseconds
+	 * @default 15000
+	 */
+	askQuestionTimeoutMs?: number;
+}
+
+/**
+ * Options for creating default tools
+ */
+export interface CreateDefaultToolsOptions extends DefaultToolsConfig {
+	/**
+	 * Executor implementations for the tools
+	 * Only tools with provided executors will be available
+	 */
+	executors: ToolExecutors;
+}

package/src/types/common.ts

@@ -0,0 +1,26 @@
+import { SESSION_STATUS_VALUES } from "@clinebot/shared";
+
+export const SESSION_STATUSES = SESSION_STATUS_VALUES;
+
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+
+export const SessionSource = {
+	CORE: "core",
+	CLI: "cli",
+	SUBAGENT: "subagent",
+	DESKTOP: "desktop",
+	KANBAN: "kanban",
+	API: "api",
+	WEB: "web",
+	VSCODE: "vscode",
+	ENTERPRISE: "enterprise",
+	IDE: "ide",
+	JETBRAINS: "jetbrains",
+	NEOVIM: "neovim",
+	UNKNOWN: "unknown",
+} as const;
+
+export type BuiltinSessionSource =
+	(typeof SessionSource)[keyof typeof SessionSource];
+
+export type SessionSource = BuiltinSessionSource | (string & {});