@clinebot/core 0.0.37 → 0.0.38

package/src/extensions/tools/types.ts

@@ -1,354 +0,0 @@
-/**
- * Types for Default Tools
- *
- * Type definitions for executors, configuration, and results.
- */
-
-import type { ImageContent, TextContent, ToolContext } from "@clinebot/shared";
-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: unknown;
-	/** Error message (if failed) */
-	error?: string;
-	/** Whether the operation succeeded */
-	success: boolean;
-	/** Duration in MS */
-	duration?: number;
-}
-
-export type FileReadResultContent = string | Array<TextContent | ImageContent>;
-
-// =============================================================================
-// 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<FileReadResultContent>;
-
-/**
- * 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[];
-}
-
-/**
- * Executor for verifying a user's response to a question
- *
- * @param summary - Summary of the solution ans steps taken
- * @param verified - Boolean indicating if the solution has been verified
- * @param context - Tool execution context
- * @returns Executor-specific result payload
- */
-export type VerifySubmitExecutor = (
-	summary: string,
-	verified: boolean,
-	context: ToolContext,
-) => Promise<string>;
-
-/**
- * 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;
-	/** Final submission implementation */
-	submit?: VerifySubmitExecutor;
-}
-
-// =============================================================================
-// 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"
-	| "submit_and_exit";
-
-/**
- * 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;
-
-	/**
-	 * Enable the submit_and_exit tool
-	 * @default false
-	 */
-	enableSubmitAndExit?: 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 submit_and_exit operations in milliseconds
-	 * @default 15000
-	 */
-	submitTimeoutMs?: 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/hooks/checkpoint-hooks.ts

@@ -1,238 +0,0 @@
-import { execFile as execFileCallback } from "node:child_process";
-import { promisify } from "node:util";
-import type { AgentHooks, BasicLogger } from "@clinebot/shared";
-
-const execFile = promisify(execFileCallback);
-
-export interface CheckpointEntry {
-	ref: string;
-	createdAt: number;
-	runCount: number;
-	kind?: "stash" | "commit";
-}
-
-export interface CheckpointMetadata {
-	latest: CheckpointEntry;
-	history: CheckpointEntry[];
-}
-
-type CreateCheckpointHooksOptions = {
-	cwd: string;
-	sessionId: string;
-	logger?: BasicLogger;
-	readSessionMetadata: () => Promise<Record<string, unknown> | undefined>;
-	writeSessionMetadata: (
-		metadata: Record<string, unknown>,
-	) => Promise<void> | void;
-	/**
-	 * Optional custom checkpoint implementation. When provided, the built-in
-	 * git stash/ref logic is skipped entirely and this function is called
-	 * instead. Return `undefined` to skip writing a checkpoint for that run.
-	 */
-	createCheckpoint?: (context: {
-		cwd: string;
-		sessionId: string;
-		runCount: number;
-	}) => Promise<CheckpointEntry | undefined> | CheckpointEntry | undefined;
-};
-
-function warn(logger: BasicLogger | undefined, message: string): void {
-	logger?.log(message, { severity: "warn" });
-}
-
-function readCheckpointMetadata(
-	metadata: Record<string, unknown> | undefined,
-): CheckpointMetadata | undefined {
-	const candidate = metadata?.checkpoint;
-	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
-		return undefined;
-	}
-	const record = candidate as Partial<CheckpointMetadata>;
-	if (!record.latest || !Array.isArray(record.history)) {
-		return undefined;
-	}
-	const latest = record.latest as Partial<CheckpointEntry>;
-	const history = record.history.filter(
-		(entry): entry is CheckpointEntry =>
-			!!entry &&
-			typeof entry === "object" &&
-			typeof (entry as Partial<CheckpointEntry>).ref === "string" &&
-			typeof (entry as Partial<CheckpointEntry>).createdAt === "number" &&
-			typeof (entry as Partial<CheckpointEntry>).runCount === "number",
-	);
-	if (
-		typeof latest.ref !== "string" ||
-		typeof latest.createdAt !== "number" ||
-		typeof latest.runCount !== "number"
-	) {
-		return undefined;
-	}
-	return {
-		latest: latest as CheckpointEntry,
-		history,
-	};
-}
-
-async function runGit(
-	cwd: string,
-	args: string[],
-): Promise<{ stdout: string; stderr: string }> {
-	const result = await execFile("git", ["-C", cwd, ...args], {
-		windowsHide: true,
-	});
-	return {
-		stdout: result.stdout.trim(),
-		stderr: result.stderr.trim(),
-	};
-}
-
-/**
- * Deletes all private git refs under refs/cline/checkpoints/{sessionId}/ that
- * were created by the checkpoint system to keep stash objects reachable.
- * Errors are swallowed — if the cwd is not a git repo or the refs don't exist,
- * the delete is a no-op.
- */
-export async function deleteCheckpointRefs(
-	cwd: string | null | undefined,
-	sessionId: string,
-): Promise<void> {
-	if (!cwd) return;
-	const prefix = `refs/cline/checkpoints/${sessionId}/`;
-	try {
-		const { stdout } = await runGit(cwd, [
-			"for-each-ref",
-			"--format=%(refname)",
-			prefix,
-		]);
-		const refs = stdout.trim().split("\n").filter(Boolean);
-		await Promise.allSettled(
-			refs.map((ref) => runGit(cwd, ["update-ref", "-d", ref])),
-		);
-	} catch {
-		// Not a git repo or git not available — ignore.
-	}
-}
-
-export function createCheckpointHooks(
-	options: CreateCheckpointHooksOptions,
-): AgentHooks {
-	let runCount = 0;
-	let repoSupported: boolean | undefined;
-
-	const ensureGitRepository = async (): Promise<boolean> => {
-		if (repoSupported !== undefined) {
-			return repoSupported;
-		}
-		try {
-			const result = await runGit(options.cwd, [
-				"rev-parse",
-				"--is-inside-work-tree",
-			]);
-			repoSupported = result.stdout === "true";
-		} catch {
-			repoSupported = false;
-		}
-		return repoSupported;
-	};
-
-	const createCheckpoint = async (): Promise<CheckpointEntry | undefined> => {
-		if (options.createCheckpoint) {
-			return await options.createCheckpoint({
-				cwd: options.cwd,
-				sessionId: options.sessionId,
-				runCount,
-			});
-		}
-
-		if (!(await ensureGitRepository())) {
-			return undefined;
-		}
-
-		const message = `cline checkpoint session=${options.sessionId} run=${runCount}`;
-		let ref = "";
-		try {
-			const result = await runGit(options.cwd, ["stash", "create", message]);
-			ref = result.stdout.trim();
-		} catch (error) {
-			warn(
-				options.logger,
-				`Checkpoint snapshot failed: ${error instanceof Error ? error.message : String(error)}`,
-			);
-			return undefined;
-		}
-		if (!ref) {
-			try {
-				const result = await runGit(options.cwd, ["rev-parse", "HEAD"]);
-				ref = result.stdout.trim();
-			} catch (error) {
-				warn(
-					options.logger,
-					`Checkpoint HEAD fallback failed: ${error instanceof Error ? error.message : String(error)}`,
-				);
-				return undefined;
-			}
-			if (!ref) {
-				return undefined;
-			}
-			return {
-				ref,
-				createdAt: Date.now(),
-				runCount,
-				kind: "commit",
-			};
-		}
-
-		// Store the stash commit under a private ref namespace so it is
-		// invisible to the user's normal `git stash list` workflow.
-		// `refs/stash` is what populates that list; writing to any other
-		// ref path keeps the object reachable (GC-safe) without surfacing
-		// it to the user.  The raw SHA already works with `git stash apply`
-		// on the restore path, so no restore-side changes are needed.
-		const privateRef = `refs/cline/checkpoints/${options.sessionId}/${runCount}`;
-		try {
-			await runGit(options.cwd, ["update-ref", privateRef, ref]);
-		} catch (error) {
-			warn(
-				options.logger,
-				`Checkpoint store failed: ${error instanceof Error ? error.message : String(error)}`,
-			);
-			return undefined;
-		}
-
-		return {
-			ref,
-			createdAt: Date.now(),
-			runCount,
-			kind: "stash",
-		};
-	};
-
-	return {
-		onRunStart: async ({ parentAgentId }) => {
-			if (parentAgentId === null) {
-				runCount += 1;
-			}
-			return undefined;
-		},
-		onBeforeAgentStart: async ({ parentAgentId, iteration }) => {
-			if (parentAgentId !== null || iteration !== 1 || runCount < 1) {
-				return undefined;
-			}
-			const entry = await createCheckpoint();
-			if (!entry) {
-				return undefined;
-			}
-			const metadata = await options.readSessionMetadata();
-			const existing = readCheckpointMetadata(metadata);
-			const history = [...(existing?.history ?? []), entry];
-			await options.writeSessionMetadata({
-				...(metadata ?? {}),
-				checkpoint: {
-					latest: entry,
-					history,
-				} satisfies CheckpointMetadata,
-			});
-			return undefined;
-		},
-	};
-}