@clinebot/core 0.0.21 → 0.0.23

package/src/tools/index.ts

@@ -0,0 +1,169 @@
+/**
+ * Default Tools
+ *
+ * This module provides a set of configurable default tools for agents.
+ */
+
+// Zod Utilities
+export { validateWithZod, zodToJsonSchema } from "@clinebot/shared";
+// Constants
+export { ALL_DEFAULT_TOOL_NAMES, DefaultToolNames } from "./constants";
+// Tool Definitions
+export {
+	createApplyPatchTool,
+	createAskQuestionTool,
+	createBashTool,
+	createDefaultTools,
+	createEditorTool,
+	createReadFilesTool,
+	createSearchTool,
+	createSkillsTool,
+	createWebFetchTool,
+	createWindowsShellTool,
+} from "./definitions";
+// Built-in Executors
+export {
+	type ApplyPatchExecutorOptions,
+	type BashExecutorOptions,
+	createApplyPatchExecutor,
+	createBashExecutor,
+	createDefaultExecutors,
+	createEditorExecutor,
+	createFileReadExecutor,
+	createSearchExecutor,
+	createWebFetchExecutor,
+	type DefaultExecutorsOptions,
+	type EditorExecutorOptions,
+	type FileReadExecutorOptions,
+	type SearchExecutorOptions,
+	type WebFetchExecutorOptions,
+} from "./executors/index";
+export {
+	DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	resolveToolRoutingConfig,
+	type ToolRoutingRule,
+} from "./model-tool-routing";
+// Presets
+export {
+	createDefaultToolsWithPreset,
+	createToolPoliciesWithPreset,
+	type ToolPolicyPresetName,
+	type ToolPresetName,
+	ToolPresets,
+} from "./presets";
+// Schemas
+export {
+	type ApplyPatchInput,
+	ApplyPatchInputSchema,
+	type AskQuestionInput,
+	AskQuestionInputSchema,
+	type EditFileInput,
+	EditFileInputSchema,
+	type FetchWebContentInput,
+	FetchWebContentInputSchema,
+	type ReadFileRequest,
+	ReadFileRequestSchema,
+	type ReadFilesInput,
+	ReadFilesInputSchema,
+	type RunCommandsInput,
+	RunCommandsInputSchema,
+	type SearchCodebaseInput,
+	SearchCodebaseInputSchema,
+	type SkillsInput,
+	SkillsInputSchema,
+	type WebFetchRequest,
+	WebFetchRequestSchema,
+} from "./schemas";
+// Types
+export type {
+	ApplyPatchExecutor,
+	AskQuestionExecutor,
+	BashExecutor,
+	CreateDefaultToolsOptions,
+	DefaultToolName,
+	DefaultToolsConfig,
+	EditorExecutor,
+	FileReadExecutor,
+	SearchExecutor,
+	SkillsExecutor,
+	SkillsExecutorSkillMetadata,
+	SkillsExecutorWithMetadata,
+	ToolExecutors,
+	ToolOperationResult,
+	WebFetchExecutor,
+} from "./types";
+
+// =============================================================================
+// Convenience: Create Tools with Built-in Executors
+// =============================================================================
+
+import type { Tool } from "@clinebot/agents";
+import { createDefaultTools } from "./definitions";
+import {
+	createDefaultExecutors,
+	type DefaultExecutorsOptions,
+} from "./executors/index";
+import type { CreateDefaultToolsOptions, ToolExecutors } from "./types";
+
+/**
+ * Options for creating default tools with built-in executors
+ */
+export interface CreateBuiltinToolsOptions
+	extends Omit<CreateDefaultToolsOptions, "executors"> {
+	/**
+	 * Configuration for the built-in executors
+	 */
+	executorOptions?: DefaultExecutorsOptions;
+	/**
+	 * Optional executor overrides/additions for tools without built-ins
+	 */
+	executors?: Partial<ToolExecutors>;
+}
+
+/**
+ * Create default tools with built-in Node.js executors
+ *
+ * This is a convenience function that creates the default tools with
+ * working implementations using Node.js built-in modules.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from "@clinebot/agents"
+ * import { createBuiltinTools } from "@clinebot/core"
+ *
+ * const tools = createBuiltinTools({
+ *   cwd: "/path/to/project",
+ *   enableBash: true,
+ *   enableWebFetch: false, // Disable web fetching
+ *   executorOptions: {
+ *     bash: { timeoutMs: 60000 },
+ *   },
+ * })
+ *
+ * const agent = new Agent({
+ *   providerId: "anthropic",
+ *   modelId: "claude-sonnet-4-20250514",
+ *   systemPrompt: "You are a coding assistant.",
+ *   tools,
+ * })
+ * ```
+ */
+export function createBuiltinTools(
+	options: CreateBuiltinToolsOptions = {},
+): Tool[] {
+	const {
+		executorOptions = {},
+		executors: executorOverrides,
+		...toolsConfig
+	} = options;
+
+	const executors = {
+		...createDefaultExecutors(executorOptions),
+		...(executorOverrides ?? {}),
+	};
+
+	return createDefaultTools({
+		...toolsConfig,
+		executors,
+	});
+}

package/src/tools/model-tool-routing.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_MODEL_TOOL_ROUTING_RULES,
+	resolveToolRoutingConfig,
+} from "./model-tool-routing";
+
+describe("model tool routing", () => {
+	it("applies default codex/gpt routing in act mode", () => {
+		const config = resolveToolRoutingConfig(
+			"openai",
+			"openai/gpt-5.4",
+			"act",
+			DEFAULT_MODEL_TOOL_ROUTING_RULES,
+		);
+
+		expect(config.enableApplyPatch).toBe(true);
+		expect(config.enableEditor).toBe(false);
+	});
+
+	it("does not apply default codex/gpt routing in plan mode", () => {
+		const config = resolveToolRoutingConfig(
+			"openai",
+			"openai/gpt-5.4",
+			"plan",
+			DEFAULT_MODEL_TOOL_ROUTING_RULES,
+		);
+
+		expect(config).toEqual({});
+	});
+
+	it("applies matching custom rules in order", () => {
+		const config = resolveToolRoutingConfig(
+			"anthropic",
+			"claude-sonnet-4-6",
+			"act",
+			[
+				{
+					name: "claude-editor-off",
+					mode: "act",
+					modelIdIncludes: ["claude"],
+					disableTools: ["editor"],
+				},
+				{
+					name: "claude-apply-patch-on",
+					mode: "act",
+					modelIdIncludes: ["claude"],
+					enableTools: ["apply_patch"],
+				},
+			],
+		);
+
+		expect(config.enableEditor).toBe(false);
+		expect(config.enableApplyPatch).toBe(true);
+	});
+
+	it("returns empty config when no rules match", () => {
+		const config = resolveToolRoutingConfig(
+			"anthropic",
+			"claude-sonnet-4-6",
+			"act",
+			[
+				{
+					mode: "act",
+					modelIdIncludes: ["gpt"],
+					enableTools: ["apply_patch"],
+				},
+			],
+		);
+
+		expect(config).toEqual({});
+	});
+
+	it("can match provider-only rules", () => {
+		const config = resolveToolRoutingConfig("openai", "o4-mini", "act", [
+			{
+				mode: "act",
+				providerIdIncludes: ["openai"],
+				enableTools: ["apply_patch"],
+				disableTools: ["editor"],
+			},
+		]);
+
+		expect(config.enableApplyPatch).toBe(true);
+		expect(config.enableEditor).toBe(false);
+	});
+});

package/src/tools/model-tool-routing.ts

@@ -0,0 +1,132 @@
+import type { CoreAgentMode } from "../types/config";
+import type { DefaultToolName, DefaultToolsConfig } from "./types";
+
+export interface ToolRoutingRule {
+	/**
+	 * Optional rule label for debugging and logs.
+	 */
+	name?: string;
+	/**
+	 * Which mode the rule applies to.
+	 * @default "any"
+	 */
+	mode?: CoreAgentMode | "any";
+	/**
+	 * Case-insensitive substrings that must match the model ID.
+	 * When omitted/empty, the rule is not constrained by model ID.
+	 */
+	modelIdIncludes?: string[];
+	/**
+	 * Case-insensitive substrings that must match the provider ID.
+	 * When omitted/empty, the rule is not constrained by provider ID.
+	 */
+	providerIdIncludes?: string[];
+	/**
+	 * Enable these tools when the rule matches.
+	 */
+	enableTools?: DefaultToolName[];
+	/**
+	 * Disable these tools when the rule matches.
+	 */
+	disableTools?: DefaultToolName[];
+}
+
+const TOOL_NAME_TO_FLAG: Record<
+	DefaultToolName,
+	keyof Pick<
+		DefaultToolsConfig,
+		| "enableReadFiles"
+		| "enableSearch"
+		| "enableBash"
+		| "enableWebFetch"
+		| "enableApplyPatch"
+		| "enableEditor"
+		| "enableSkills"
+		| "enableAskQuestion"
+	>
+> = {
+	read_files: "enableReadFiles",
+	search_codebase: "enableSearch",
+	run_commands: "enableBash",
+	fetch_web_content: "enableWebFetch",
+	apply_patch: "enableApplyPatch",
+	editor: "enableEditor",
+	skills: "enableSkills",
+	ask_question: "enableAskQuestion",
+};
+
+export const DEFAULT_MODEL_TOOL_ROUTING_RULES: ToolRoutingRule[] = [
+	{
+		name: "openai-native-use-apply-patch",
+		mode: "act",
+		providerIdIncludes: ["openai-native"],
+		enableTools: ["apply_patch"],
+		disableTools: ["editor"],
+	},
+	{
+		name: "codex-and-gpt-use-apply-patch",
+		mode: "act",
+		modelIdIncludes: ["codex", "gpt"],
+		enableTools: ["apply_patch"],
+		disableTools: ["editor"],
+	},
+];
+
+function matchesModelId(
+	modelId: string,
+	includes: string[] | undefined,
+): boolean {
+	if (!includes || includes.length === 0) {
+		return true;
+	}
+	const normalizedModelId = modelId.toLowerCase();
+	return includes.some((value) =>
+		normalizedModelId.includes(value.toLowerCase()),
+	);
+}
+
+function matchesRule(
+	rule: ToolRoutingRule,
+	providerId: string,
+	modelId: string,
+	mode: CoreAgentMode,
+): boolean {
+	if (rule.mode && rule.mode !== "any" && rule.mode !== mode) {
+		return false;
+	}
+	return (
+		matchesModelId(providerId, rule.providerIdIncludes) &&
+		matchesModelId(modelId, rule.modelIdIncludes)
+	);
+}
+
+export function resolveToolRoutingConfig(
+	providerId: string,
+	modelId: string,
+	mode: CoreAgentMode,
+	rules: ToolRoutingRule[] | undefined,
+): Partial<DefaultToolsConfig> {
+	if (!rules || rules.length === 0) {
+		return {};
+	}
+
+	const toggles = new Map<DefaultToolName, boolean>();
+
+	for (const rule of rules) {
+		if (!matchesRule(rule, providerId, modelId, mode)) {
+			continue;
+		}
+		for (const toolName of rule.disableTools ?? []) {
+			toggles.set(toolName, false);
+		}
+		for (const toolName of rule.enableTools ?? []) {
+			toggles.set(toolName, true);
+		}
+	}
+
+	const config: Partial<DefaultToolsConfig> = {};
+	for (const [toolName, enabled] of toggles.entries()) {
+		config[TOOL_NAME_TO_FLAG[toolName]] = enabled;
+	}
+	return config;
+}

package/src/tools/presets.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import {
+	createDefaultToolsWithPreset,
+	createToolPoliciesWithPreset,
+	ToolPresets,
+} from "./presets";
+
+describe("default tool presets", () => {
+	it("explicitly configures ask_question across presets", () => {
+		expect(ToolPresets.search.enableAskQuestion).toBe(false);
+		expect(ToolPresets.development.enableAskQuestion).toBe(true);
+		expect(ToolPresets.readonly.enableAskQuestion).toBe(true);
+		expect(ToolPresets.minimal.enableAskQuestion).toBe(true);
+		expect(ToolPresets.yolo.enableAskQuestion).toBe(false);
+	});
+
+	it("yolo preset excludes ask_question even when its executor exists", () => {
+		const tools = createDefaultToolsWithPreset("yolo", {
+			executors: {
+				readFile: async () => "ok",
+				search: async () => "ok",
+				bash: async () => "ok",
+				webFetch: async () => "ok",
+				applyPatch: async () => "ok",
+				editor: async () => "ok",
+				skills: async () => "ok",
+				askQuestion: async () => "ok",
+			},
+		});
+
+		expect(tools.map((tool) => tool.name)).toEqual([
+			"read_files",
+			"search_codebase",
+			"run_commands",
+			"fetch_web_content",
+			"editor",
+			"skills",
+		]);
+	});
+});
+
+describe("tool policy presets", () => {
+	it("returns empty policies for default", () => {
+		expect(createToolPoliciesWithPreset("default")).toEqual({});
+	});
+
+	it("yolo preset enables and auto-approves all tools", () => {
+		const policies = createToolPoliciesWithPreset("yolo");
+		expect(policies["*"]).toEqual({
+			enabled: true,
+			autoApprove: true,
+		});
+		expect(policies.ask_question).toEqual({
+			enabled: true,
+			autoApprove: true,
+		});
+		expect(policies.skills).toEqual({
+			enabled: true,
+			autoApprove: true,
+		});
+	});
+});

package/src/tools/presets.ts

@@ -0,0 +1,168 @@
+/**
+ * Tool Presets
+ *
+ * Pre-configured tool combinations for common use cases.
+ */
+
+import type { Tool, ToolPolicy } from "@clinebot/shared";
+import { ALL_DEFAULT_TOOL_NAMES } from "./constants";
+import { createDefaultTools } from "./definitions";
+import type { CreateDefaultToolsOptions, DefaultToolsConfig } from "./types";
+
+/**
+ * Preset configurations for common use cases
+ */
+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,
+	},
+
+	/**
+	 * Search-focused tools (read_files + search_codebase)
+	 * Good for code exploration and analysis agents
+	 */
+	search: {
+		enableReadFiles: true,
+		enableSearch: true,
+		enableBash: false,
+		enableWebFetch: false,
+		enableApplyPatch: false,
+		enableEditor: false,
+		enableSkills: false,
+		enableAskQuestion: false,
+	},
+
+	/**
+	 * Full development tools (all tools enabled) - Act mode
+	 * Good for coding assistants and task automation
+	 */
+	development: {
+		enableReadFiles: true,
+		enableSearch: true,
+		enableBash: true,
+		enableWebFetch: true,
+		enableApplyPatch: false,
+		enableEditor: true,
+		enableSkills: true,
+		enableAskQuestion: true,
+	},
+
+	/**
+	 * Read-only tools (no shell access) - Plan mode
+	 * Good for analysis and documentation agents
+	 */
+	readonly: {
+		enableReadFiles: true,
+		enableSearch: true,
+		enableBash: true,
+		enableWebFetch: true,
+		enableApplyPatch: false,
+		enableEditor: false,
+		enableSkills: true,
+		enableAskQuestion: true,
+	},
+
+	/**
+	 * Minimal tools (file reading only)
+	 * Good for focused single-file tasks
+	 */
+	minimal: {
+		enableReadFiles: false,
+		enableSearch: false,
+		enableBash: false,
+		enableWebFetch: false,
+		enableApplyPatch: false,
+		enableEditor: false,
+		enableSkills: false,
+		enableAskQuestion: true,
+	},
+
+	/**
+	 * YOLO mode (automation-focused tools + no approval required)
+	 * Good for trusted local automation workflows.
+	 */
+	yolo: {
+		enableReadFiles: true,
+		enableSearch: true,
+		enableBash: true,
+		enableWebFetch: true,
+		enableApplyPatch: false,
+		enableEditor: true,
+		enableSkills: true,
+		enableAskQuestion: false,
+	},
+} as const satisfies Record<string, DefaultToolsConfig>;
+
+/**
+ * Type for preset names
+ */
+export type ToolPresetName = keyof typeof ToolPresets;
+
+/**
+ * Tool policy preset names
+ */
+export type ToolPolicyPresetName = "default" | "yolo";
+
+/**
+ * Build tool policies for a preset.
+ * `yolo` guarantees tool policies are enabled and auto-approved.
+ */
+export function createToolPoliciesWithPreset(
+	presetName: ToolPolicyPresetName,
+): Record<string, ToolPolicy> {
+	if (presetName !== "yolo") {
+		return {};
+	}
+
+	const yoloPolicy: ToolPolicy = {
+		enabled: true,
+		autoApprove: true,
+	};
+
+	const policies: Record<string, ToolPolicy> = {
+		"*": yoloPolicy,
+	};
+
+	for (const toolName of ALL_DEFAULT_TOOL_NAMES) {
+		policies[toolName] = yoloPolicy;
+	}
+
+	return policies;
+}
+
+/**
+ * Create default tools using a preset configuration
+ *
+ * @example
+ * ```typescript
+ * const tools = createDefaultToolsWithPreset("readonly", {
+ *   executors: {
+ *     readFile: async ({ path }) => fs.readFile(path, "utf-8"),
+ *     search: async (query, cwd) => searchFiles(query, cwd),
+ *     webFetch: async (url, prompt) => fetchAndAnalyze(url, prompt),
+ *   },
+ *   cwd: "/path/to/project",
+ * })
+ * ```
+ */
+export function createDefaultToolsWithPreset(
+	presetName: ToolPresetName,
+	options: Omit<CreateDefaultToolsOptions, keyof DefaultToolsConfig> &
+		Partial<DefaultToolsConfig>,
+): Tool[] {
+	const preset = ToolPresets[presetName];
+	return createDefaultTools({
+		...preset,
+		...options,
+	});
+}