codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/packages/core/src/extensions/tools/types.ts

@@ -0,0 +1,358 @@
+/**
+ * Types for Default Tools
+ *
+ * Type definitions for executors, configuration, and results.
+ */
+
+import type {
+	AgentToolContext,
+	ImageContent,
+	TextContent,
+} from "@cline/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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+) => 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: AgentToolContext,
+	): 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: AgentToolContext,
+) => 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;
+}

codna/agent-core/vendor/cline/sdk/packages/core/src/hooks/checkpoint-hooks.test.ts

@@ -0,0 +1,276 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+import {
+	type CheckpointEntry,
+	type CheckpointMetadata,
+	createCheckpointHooks,
+} from "./checkpoint-hooks";
+
+const execFile = promisify(execFileCallback);
+
+async function runGit(cwd: string, ...args: string[]): Promise<string> {
+	const result = await execFile("git", ["-C", cwd, ...args], {
+		windowsHide: true,
+	});
+	return result.stdout.trim();
+}
+
+async function createGitRepo(): Promise<string> {
+	const cwd = await mkdtemp(join(tmpdir(), "core-checkpoint-"));
+	await runGit(cwd, "init");
+	await runGit(cwd, "config", "user.name", "Codex Test");
+	await runGit(cwd, "config", "user.email", "codex@example.com");
+	await writeFile(join(cwd, "note.txt"), "base\n", "utf8");
+	await runGit(cwd, "add", "note.txt");
+	await runGit(cwd, "commit", "-m", "initial");
+	return cwd;
+}
+
+async function runCheckpointHooks(
+	hooks: ReturnType<typeof createCheckpointHooks>,
+	options: { parentAgentId?: string | null } = {},
+): Promise<void> {
+	const snapshot = {
+		agentId: options.parentAgentId ? "agent_child" : "agent_1",
+		parentAgentId: options.parentAgentId,
+		conversationId: options.parentAgentId ? "conv_child" : "conv_1",
+		runId: options.parentAgentId ? "run_child" : "run_1",
+		status: "running" as const,
+		iteration: 1,
+		messages: [],
+		pendingToolCalls: [],
+		usage: {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+		},
+	};
+	await hooks.beforeRun?.({ snapshot: { ...snapshot, iteration: 0 } });
+	await hooks.beforeModel?.({
+		snapshot,
+		request: {
+			messages: [],
+			tools: [],
+		},
+	});
+}
+
+describe("createCheckpointHooks", () => {
+	it("creates one checkpoint at the start of each root run and appends metadata", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_1",
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await writeFile(join(cwd, "note.txt"), "run-one\n", "utf8");
+			await runCheckpointHooks(hooks);
+
+			const first = metadata?.checkpoint as CheckpointMetadata;
+			expect(first.history).toHaveLength(1);
+			expect(first.latest.runCount).toBe(1);
+			expect(first.latest.ref).toMatch(/^[0-9a-f]{40}$/);
+
+			await writeFile(join(cwd, "note.txt"), "run-two\n", "utf8");
+			await runCheckpointHooks(hooks);
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.latest.runCount).toBe(2);
+			expect(checkpoint.history).toHaveLength(2);
+			expect(
+				checkpoint.history.map((entry: CheckpointEntry) => entry.runCount),
+			).toEqual([1, 2]);
+			expect(checkpoint.latest.kind).toBe("stash");
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("falls back to a commit checkpoint when the worktree is clean", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_clean",
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await runCheckpointHooks(hooks);
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.history).toHaveLength(1);
+			expect(checkpoint.latest.kind).toBe("commit");
+			expect(checkpoint.latest.ref).toMatch(/^[0-9a-f]{40}$/);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("does not append a checkpoint when the snapshot matches the latest checkpoint", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_no_change",
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await runCheckpointHooks(hooks);
+
+			const first = metadata?.checkpoint as CheckpointMetadata;
+			expect(first.history).toHaveLength(1);
+			expect(first.latest.kind).toBe("commit");
+
+			await runCheckpointHooks(hooks);
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.history).toHaveLength(1);
+			expect(checkpoint.latest.runCount).toBe(1);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("skips checkpoint creation for subagents", async () => {
+		const cwd = await createGitRepo();
+		let writes = 0;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_1",
+				readSessionMetadata: async () => undefined,
+				writeSessionMetadata: async () => {
+					writes += 1;
+				},
+			});
+
+			await writeFile(join(cwd, "note.txt"), "subagent-dirty\n", "utf8");
+			await runCheckpointHooks(hooks, { parentAgentId: "agent_root" });
+
+			expect(writes).toBe(0);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("does not advance root checkpoint numbering for subagent runs", async () => {
+		let metadata: Record<string, unknown> | undefined;
+		const hooks = createCheckpointHooks({
+			cwd: "/tmp",
+			sessionId: "sess_subagent_count",
+			createCheckpoint: ({ runCount }) => ({
+				ref: `checkpoint-${runCount}`,
+				createdAt: runCount,
+				runCount,
+				kind: "commit",
+			}),
+			readSessionMetadata: async () => metadata,
+			writeSessionMetadata: async (next) => {
+				metadata = next;
+			},
+		});
+
+		await runCheckpointHooks(hooks, { parentAgentId: "agent_root" });
+		await runCheckpointHooks(hooks);
+
+		const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+		expect(checkpoint.latest.runCount).toBe(1);
+		expect(checkpoint.history.map((entry) => entry.runCount)).toEqual([1]);
+	});
+
+	it("continues checkpoint numbering after seeded messages", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_seeded",
+				initialRunCount: 2,
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await writeFile(join(cwd, "note.txt"), "run-three\n", "utf8");
+			await runCheckpointHooks(hooks);
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.latest.runCount).toBe(3);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("replaces an existing checkpoint entry for the same run count", async () => {
+		let metadata: Record<string, unknown> | undefined = {
+			checkpoint: {
+				latest: {
+					ref: "old-three",
+					createdAt: 3,
+					runCount: 3,
+					kind: "commit",
+				},
+				history: [
+					{ ref: "one", createdAt: 1, runCount: 1, kind: "commit" },
+					{ ref: "two", createdAt: 2, runCount: 2, kind: "commit" },
+					{
+						ref: "old-three",
+						createdAt: 3,
+						runCount: 3,
+						kind: "commit",
+					},
+				],
+			},
+		};
+		const hooks = createCheckpointHooks({
+			cwd: "/tmp",
+			sessionId: "sess_replace",
+			initialRunCount: 2,
+			createCheckpoint: ({ runCount }) => ({
+				ref: "new-three",
+				createdAt: 4,
+				runCount,
+				kind: "commit",
+			}),
+			readSessionMetadata: async () => metadata,
+			writeSessionMetadata: async (next) => {
+				metadata = next;
+			},
+		});
+
+		await runCheckpointHooks(hooks);
+
+		const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+		expect(checkpoint.latest).toMatchObject({
+			ref: "new-three",
+			runCount: 3,
+		});
+		expect(checkpoint.history.map((entry) => entry.runCount)).toEqual([
+			1, 2, 3,
+		]);
+		expect(checkpoint.history.at(-1)).toMatchObject({
+			ref: "new-three",
+			runCount: 3,
+		});
+	});
+});