@clinebot/core 0.0.35 → 0.0.36

package/src/extensions/tools/executors/search.ts

@@ -1,9 +1,10 @@
 /**
  * Search Executor
  *
- * Built-in implementation for searching the codebase using regex.
+ * Built-in implementation for searching the codebase using ripgrep (if available) or regex.
  */
 
+import { spawn } from "node:child_process";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { ToolContext } from "@clinebot/shared";
@@ -118,6 +119,152 @@ interface SearchMatch {
 	context: string[];
 }
 
+let rgAvailable: boolean | null = null;
+
+function checkRipgrepAvailable(): Promise<boolean> {
+	if (rgAvailable !== null) {
+		return Promise.resolve(rgAvailable);
+	}
+
+	return new Promise((resolve) => {
+		const child = spawn("rg", ["--version"], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		child.on("close", (code) => {
+			rgAvailable = code === 0;
+			resolve(rgAvailable);
+		});
+
+		child.on("error", () => {
+			rgAvailable = false;
+			resolve(false);
+		});
+
+		setTimeout(() => {
+			if (!child.killed) {
+				child.kill("SIGTERM");
+			}
+			if (rgAvailable === null) {
+				rgAvailable = false;
+				resolve(false);
+			}
+		}, 1000);
+	});
+}
+
+function searchWithRipgrep(
+	query: string,
+	cwd: string,
+	maxResults: number,
+	contextLines: number,
+	timeoutMs: number = 5000,
+	abortSignal?: AbortSignal,
+): Promise<SearchMatch[] | null> {
+	return new Promise((resolve) => {
+		const child = spawn(
+			"rg",
+			["--json", `--context=${contextLines}`, "--max-count=1", "-i", query],
+			{
+				cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			},
+		);
+
+		let stdout = "";
+		let resolved = false;
+
+		const cleanup = () => {
+			if (!child.killed) {
+				child.kill("SIGTERM");
+			}
+		};
+
+		const timeout = setTimeout(() => {
+			if (!resolved) {
+				resolved = true;
+				cleanup();
+				resolve(null);
+			}
+		}, timeoutMs);
+
+		const finalize = (result: SearchMatch[] | null) => {
+			if (!resolved) {
+				resolved = true;
+				clearTimeout(timeout);
+				cleanup();
+				resolve(result);
+			}
+		};
+
+		if (abortSignal?.aborted) {
+			cleanup();
+			resolve(null);
+			return;
+		}
+
+		abortSignal?.addEventListener("abort", () => {
+			finalize(null);
+		});
+
+		child.stdout.on("data", (chunk: Buffer | string) => {
+			stdout += chunk.toString();
+		});
+
+		child.stderr.on("data", () => {
+			// Ignore stderr
+		});
+
+		child.on("close", (code: number | null) => {
+			if (code === 0 || code === 1) {
+				try {
+					const matches: SearchMatch[] = [];
+					const lines = stdout.split("\n").filter((line) => line.trim());
+
+					for (const line of lines) {
+						if (matches.length >= maxResults) break;
+
+						const json = JSON.parse(line);
+						if (json.type === "match") {
+							const matchData = json.data;
+							const contextLines: string[] = [];
+
+							if (json.data.submatches && json.data.submatches.length > 0) {
+								const submatch = json.data.submatches[0];
+								matches.push({
+									file: matchData.path.text,
+									line: matchData.line_number,
+									column: (submatch?.start ?? 0) + 1,
+									match: submatch?.match?.text ?? "",
+									context: contextLines,
+								});
+							}
+						} else if (json.type === "context" && matches.length > 0) {
+							const lastMatch = matches[matches.length - 1];
+							const prefix =
+								json.data.line_number === lastMatch.line ? ">" : " ";
+							lastMatch.context.push(
+								`${prefix} ${json.data.line_number}: ${json.data.lines?.text ?? json.data.line?.text ?? ""}`,
+							);
+						}
+					}
+
+					finalize(matches.length > 0 ? matches : null);
+				} catch {
+					finalize(null);
+				}
+				return;
+			}
+
+			finalize(null);
+		});
+
+		child.on("error", () => {
+			finalize(null);
+		});
+	});
+}
+
 function shouldIncludeFile(
 	relativePath: string,
 	excludeDirs: Set<string>,
@@ -173,9 +320,49 @@ export function createSearchExecutor(
 	return async (
 		query: string,
 		cwd: string,
-		_context: ToolContext,
+		context: ToolContext,
 	): Promise<string> => {
-		// Compile regex
+		// Check for abort before starting
+		if (context.abortSignal?.aborted) {
+			throw new Error("Search operation aborted");
+		}
+
+		// Try ripgrep first if available
+		const isRgAvailable = await checkRipgrepAvailable();
+		let rgMatches: SearchMatch[] | null = null;
+		if (isRgAvailable) {
+			rgMatches = await searchWithRipgrep(
+				query,
+				cwd,
+				maxResults,
+				contextLines,
+				5000,
+				context.abortSignal,
+			);
+		}
+
+		if (rgMatches) {
+			const resultLines: string[] = [
+				`Found ${rgMatches.length} result${rgMatches.length === 1 ? "" : "s"} for pattern: ${query}`,
+				"",
+			];
+
+			for (const match of rgMatches) {
+				resultLines.push(`${match.file}:${match.line}:${match.column}`);
+				resultLines.push(...match.context);
+				resultLines.push("");
+			}
+
+			if (rgMatches.length >= maxResults) {
+				resultLines.push(
+					`(Showing first ${maxResults} results. Refine your search for more specific results.)`,
+				);
+			}
+
+			return resultLines.join("\n");
+		}
+
+		// Fallback to manual regex search
 		let regex: RegExp;
 		try {
 			regex = new RegExp(query, "gim");
@@ -192,6 +379,11 @@ export function createSearchExecutor(
 
 		// Search files from the fast index.
 		for (const relativePath of fileList) {
+			// Check for abort signal
+			if (context.abortSignal?.aborted) {
+				throw new Error("Search operation aborted");
+			}
+
 			if (
 				!shouldIncludeFile(
 					relativePath,

package/src/extensions/tools/index.ts

@@ -53,6 +53,15 @@ export {
 	type ToolPresetName,
 	ToolPresets,
 } from "./presets";
+export {
+	type BuiltinToolAvailabilityContext,
+	getCoreAcpToolNames,
+	getCoreBuiltinToolCatalog,
+	getCoreDefaultEnabledToolIds,
+	getCoreHeadlessToolNames,
+	resolveCoreSelectedToolIds,
+	type ToolCatalogEntry,
+} from "./runtime";
 // Schemas
 export {
 	type ApplyPatchInput,
@@ -78,6 +87,7 @@ export {
 	type WebFetchRequest,
 	WebFetchRequestSchema,
 } from "./schemas";
+export { TEAM_TOOL_NAMES } from "./team/team-tools";
 // Types
 export type {
 	ApplyPatchExecutor,

package/src/extensions/tools/presets.ts

@@ -4,7 +4,7 @@
  * Pre-configured tool combinations for common use cases.
  */
 
-import type { Tool, ToolPolicy } from "@clinebot/shared";
+import type { AgentMode, Tool, ToolPolicy } from "@clinebot/shared";
 import { ALL_DEFAULT_TOOL_NAMES } from "./constants";
 import { createDefaultTools } from "./definitions";
 import type { CreateDefaultToolsOptions, DefaultToolsConfig } from "./types";
@@ -19,91 +19,73 @@ export interface ToolPresetConfig extends DefaultToolsConfig {
  */
 export const ToolPresets = {
 	/**
-	 * Browser-based tools (no shell access, no web fetch)
-	 */
-	browser: {
-		enableReadFiles: false,
-		enableSearch: false,
-		enableBash: false,
-		enableWebFetch: false,
-		enableApplyPatch: false,
-		enableEditor: false,
-		enableSkills: true,
-		enableAskQuestion: true,
-		enableSubmitAndExit: false,
-		enableSpawnAgent: true,
-		enableAgentTeams: true,
-	},
-
-	/**
-	 * Search-focused tools (read_files + search_codebase)
-	 * Good for code exploration and analysis agents
+	 * Act mode (full development tools)
+	 * Good for coding assistants and task automation
 	 */
-	search: {
+	act: {
 		enableReadFiles: true,
 		enableSearch: true,
-		enableBash: false,
+		enableBash: true,
 		enableWebFetch: false,
 		enableApplyPatch: false,
-		enableEditor: false,
-		enableSkills: false,
-		enableAskQuestion: false,
+		enableEditor: true,
+		enableSkills: true,
+		enableAskQuestion: true,
 		enableSubmitAndExit: false,
 		enableSpawnAgent: true,
 		enableAgentTeams: true,
 	},
 
 	/**
-	 * Full development tools (all tools enabled) - Act mode
-	 * Good for coding assistants and task automation
+	 * Plan mode (read-only, no shell access)
+	 * Good for analysis and documentation agents
 	 */
-	development: {
+	plan: {
 		enableReadFiles: true,
 		enableSearch: true,
 		enableBash: true,
 		enableWebFetch: true,
 		enableApplyPatch: false,
-		enableEditor: true,
+		enableEditor: false,
 		enableSkills: true,
 		enableAskQuestion: true,
-		enableSubmitAndExit: true,
+		enableSubmitAndExit: false,
 		enableSpawnAgent: true,
 		enableAgentTeams: true,
 	},
 
 	/**
-	 * Read-only tools (no shell access) - Plan mode
-	 * Good for analysis and documentation agents
+	 * Search-focused tools (read_files + search_codebase)
+	 * Good for code exploration and analysis agents
 	 */
-	readonly: {
+	search: {
 		enableReadFiles: true,
 		enableSearch: true,
-		enableBash: true,
-		enableWebFetch: true,
+		enableBash: false,
+		enableWebFetch: false,
 		enableApplyPatch: false,
 		enableEditor: false,
-		enableSkills: true,
-		enableAskQuestion: true,
+		enableSkills: false,
+		enableAskQuestion: false,
 		enableSubmitAndExit: false,
 		enableSpawnAgent: true,
 		enableAgentTeams: true,
 	},
 
 	/**
-	 * Minimal tools (file reading only)
-	 * Good for focused single-file tasks
+	 * Minimal tools for focused tasks
 	 */
 	minimal: {
 		enableReadFiles: false,
 		enableSearch: false,
-		enableBash: false,
+		enableBash: true,
 		enableWebFetch: false,
 		enableApplyPatch: false,
 		enableEditor: false,
 		enableSkills: false,
-		enableAskQuestion: true,
+		enableAskQuestion: false,
 		enableSubmitAndExit: false,
-		enableSpawnAgent: false,
+		enableSpawnAgent: true,
 		enableAgentTeams: false,
 	},
 
@@ -132,12 +114,15 @@ export const ToolPresets = {
 export type ToolPresetName = keyof typeof ToolPresets;
 
 export function resolveToolPresetName(options: {
-	mode?: "act" | "plan" | "yolo";
+	mode?: AgentMode;
 }): ToolPresetName {
 	if (options.mode === "plan") {
-		return "readonly";
+		return "plan";
+	}
+	if (options.mode === "yolo") {
+		return "yolo";
 	}
-	return options.mode === "yolo" ? "yolo" : "development";
+	return "act";
 }
 
 /**
@@ -177,7 +162,7 @@ export function createToolPoliciesWithPreset(
  *
  * @example
  * ```typescript
- * const tools = createDefaultToolsWithPreset("readonly", {
+ * const tools = createDefaultToolsWithPreset("plan", {
  *   executors: {
  *     readFile: async ({ path }) => fs.readFile(path, "utf-8"),
  *     search: async (query, cwd) => searchFiles(query, cwd),

package/src/extensions/tools/runtime.ts

@@ -0,0 +1,261 @@
+import type { CoreAgentMode } from "../../types/config";
+import {
+	DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	resolveToolRoutingConfig,
+} from "./model-tool-routing";
+import { resolveToolPresetName, ToolPresets } from "./presets";
+import { createSpawnAgentTool } from "./team/spawn-agent-tool";
+import { TEAM_TOOL_NAMES } from "./team/team-tools";
+import type { DefaultToolsConfig } from "./types";
+
+export interface ToolCatalogEntry {
+	id: string;
+	description: string;
+	defaultEnabled: boolean;
+	headlessToolNames: string[];
+}
+
+export interface BuiltinToolAvailabilityContext {
+	mode?: CoreAgentMode;
+	providerId?: string;
+	modelId?: string;
+	enableSpawnAgent?: boolean;
+	enableAgentTeams?: boolean;
+	disabledToolIds?: ReadonlySet<string>;
+}
+
+type RuntimeToolCatalogEntry = Omit<ToolCatalogEntry, "defaultEnabled">;
+
+const BASE_TOOL_CATALOG: readonly RuntimeToolCatalogEntry[] = [
+	{
+		id: "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.",
+		headlessToolNames: ["read_files"],
+	},
+	{
+		id: "search_codebase",
+		description:
+			"Perform regex pattern searches across the codebase for code patterns, definitions, imports, and other text matches.",
+		headlessToolNames: ["search_codebase"],
+	},
+	{
+		id: "run_commands",
+		description:
+			"Run shell commands from the root of the workspace for listing files, checking git status, builds, tests, and similar tasks.",
+		headlessToolNames: ["run_commands"],
+	},
+	{
+		id: "editor",
+		description:
+			"Make controlled filesystem edits on text files with create, replace, and insert operations.",
+		headlessToolNames: ["editor"],
+	},
+	{
+		id: "fetch_web_content",
+		description:
+			"Fetch URL content and analyze it with a prompt describing what to extract.",
+		headlessToolNames: ["fetch_web_content"],
+	},
+	{
+		id: "skills",
+		description:
+			"Execute a configured skill within the main conversation when a matching skill exists for the task.",
+		headlessToolNames: ["skills"],
+	},
+	{
+		id: "ask_question",
+		description:
+			"Ask the user a single clarifying question with 2-5 selectable options.",
+		headlessToolNames: ["ask_question"],
+	},
+	{
+		id: "spawn_agent",
+		description: createSpawnAgentTool({ configProvider: {} as never })
+			.description,
+		headlessToolNames: ["spawn_agent"],
+	},
+	{
+		id: "teams",
+		description:
+			"Enable team collaboration tools for teammate management, task coordination, mailbox messaging, mission logs, and outcomes.",
+		headlessToolNames: [...TEAM_TOOL_NAMES],
+	},
+] as const;
+
+const TOOL_NAME_TO_FLAG: Partial<
+	Record<
+		string,
+		keyof Pick<
+			DefaultToolsConfig,
+			| "enableReadFiles"
+			| "enableSearch"
+			| "enableBash"
+			| "enableWebFetch"
+			| "enableApplyPatch"
+			| "enableEditor"
+			| "enableSkills"
+			| "enableAskQuestion"
+			| "enableSubmitAndExit"
+		>
+	>
+> = {
+	read_files: "enableReadFiles",
+	search_codebase: "enableSearch",
+	run_commands: "enableBash",
+	fetch_web_content: "enableWebFetch",
+	apply_patch: "enableApplyPatch",
+	editor: "enableEditor",
+	skills: "enableSkills",
+	ask_question: "enableAskQuestion",
+};
+
+function resolveContextMode(
+	mode?: BuiltinToolAvailabilityContext["mode"],
+): CoreAgentMode {
+	return mode === "plan" || mode === "yolo" ? mode : "act";
+}
+
+type ResolvedToolFlags = Pick<
+	DefaultToolsConfig,
+	| "enableReadFiles"
+	| "enableSearch"
+	| "enableBash"
+	| "enableWebFetch"
+	| "enableApplyPatch"
+	| "enableEditor"
+	| "enableSkills"
+	| "enableAskQuestion"
+	| "enableSubmitAndExit"
+> & {
+	enableSpawnAgent?: boolean;
+	enableAgentTeams?: boolean;
+};
+
+function resolvePresetFlags(context: BuiltinToolAvailabilityContext): {
+	mode: CoreAgentMode;
+	flags: ResolvedToolFlags;
+} {
+	const mode = resolveContextMode(context.mode);
+	const preset = ToolPresets[resolveToolPresetName({ mode })];
+	const routed = resolveToolRoutingConfig(
+		context.providerId ?? "",
+		context.modelId ?? "",
+		mode,
+		DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	);
+	return {
+		mode,
+		flags: {
+			...preset,
+			...routed,
+			...(typeof context.enableSpawnAgent === "boolean"
+				? { enableSpawnAgent: context.enableSpawnAgent }
+				: {}),
+			...(typeof context.enableAgentTeams === "boolean"
+				? { enableAgentTeams: context.enableAgentTeams }
+				: {}),
+		},
+	};
+}
+
+function isEntryEnabledByDefault(
+	entryId: string,
+	context: BuiltinToolAvailabilityContext,
+): boolean {
+	if (context.disabledToolIds?.has(entryId)) {
+		return false;
+	}
+
+	const { flags } = resolvePresetFlags(context);
+	if (entryId === "spawn_agent") {
+		return flags.enableSpawnAgent === true;
+	}
+	if (entryId === "teams") {
+		return flags.enableAgentTeams === true;
+	}
+	if (entryId === "editor") {
+		return flags.enableEditor === true || flags.enableApplyPatch === true;
+	}
+
+	const flag = TOOL_NAME_TO_FLAG[entryId];
+	return flag ? flags[flag] === true : false;
+}
+
+function buildCatalogEntry(
+	entry: RuntimeToolCatalogEntry,
+	context: BuiltinToolAvailabilityContext,
+): ToolCatalogEntry {
+	if (entry.id === "editor") {
+		const { flags } = resolvePresetFlags(context);
+		const usesApplyPatch =
+			flags.enableApplyPatch === true && flags.enableEditor !== true;
+		return {
+			...entry,
+			defaultEnabled: isEntryEnabledByDefault(entry.id, context),
+			headlessToolNames: [usesApplyPatch ? "apply_patch" : "editor"],
+		};
+	}
+
+	return {
+		...entry,
+		defaultEnabled: isEntryEnabledByDefault(entry.id, context),
+	};
+}
+
+export function getCoreBuiltinToolCatalog(
+	context: BuiltinToolAvailabilityContext = {},
+): ToolCatalogEntry[] {
+	return BASE_TOOL_CATALOG.map((entry) => buildCatalogEntry(entry, context));
+}
+
+export function getCoreDefaultEnabledToolIds(
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreBuiltinToolCatalog(context)
+		.filter((entry) => entry.defaultEnabled)
+		.map((entry) => entry.id);
+}
+
+export function resolveCoreSelectedToolIds(input: {
+	enabled: boolean;
+	allowlist?: string[];
+	availabilityContext?: BuiltinToolAvailabilityContext;
+}): Set<string> {
+	if (!input.enabled) {
+		return new Set();
+	}
+
+	const catalog = getCoreBuiltinToolCatalog(input.availabilityContext);
+	const known = new Set(catalog.map((entry) => entry.id));
+	if (!input.allowlist || input.allowlist.length === 0) {
+		return new Set(
+			catalog.filter((entry) => entry.defaultEnabled).map((entry) => entry.id),
+		);
+	}
+
+	for (const id of input.allowlist) {
+		if (!known.has(id)) {
+			throw new Error(
+				`Unknown tool "${id}". Available tools: ${catalog.map((entry) => entry.id).join(", ")}`,
+			);
+		}
+	}
+	return new Set(input.allowlist);
+}
+
+export function getCoreHeadlessToolNames(
+	selectedToolIds: ReadonlySet<string>,
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreBuiltinToolCatalog(context)
+		.filter((entry) => selectedToolIds.has(entry.id))
+		.flatMap((entry) => entry.headlessToolNames);
+}
+
+export function getCoreAcpToolNames(
+	selectedToolIds: ReadonlySet<string>,
+	context: BuiltinToolAvailabilityContext = {},
+): string[] {
+	return getCoreHeadlessToolNames(selectedToolIds, context);
+}

package/src/extensions/tools/schemas.ts

@@ -228,10 +228,12 @@ export const ApplyPatchInputSchema = z
 		input: z
 			.string()
 			.min(1)
-			.describe("The apply_patch text payload, including patch instructions"),
+			.describe(
+				"The freeform apply_patch payload in the canonical patch grammar (e.g *** Begin Patch, *** Update File:, @@, and *** End Patch).",
+			),
 	})
 	.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.",
+		"Modify or create a text file by applying patches using the canonical apply_patch diff grammar. Prefer sending the patch body directly rather than wrapping it in shell syntax. IMPORTANT: large patches can time out, so use small chunks and multiple calls when possible.",
 	);
 export const ApplyPatchInputUnionSchema = z.union([
 	ApplyPatchInputSchema,

package/src/extensions/tools/team/team-tools.ts

@@ -161,6 +161,27 @@ export interface BootstrapAgentTeamsResult {
 	restoredTeammates: string[];
 }
 
+export const TEAM_TOOL_NAMES = [
+	"team_spawn_teammate",
+	"team_shutdown_teammate",
+	"team_status",
+	"team_task",
+	"team_run_task",
+	"team_cancel_run",
+	"team_list_runs",
+	"team_await_runs",
+	"team_send_message",
+	"team_broadcast",
+	"team_read_mailbox",
+	"team_mission_log",
+	"team_cleanup",
+	"team_create_outcome",
+	"team_attach_outcome_fragment",
+	"team_review_outcome_fragment",
+	"team_finalize_outcome",
+	"team_list_outcomes",
+] as const;
+
 function spawnTeamTeammate(
 	options: Omit<CreateAgentTeamsToolsOptions, "requesterId" | "allowSpawn"> & {
 		requesterId: string;