@clinebot/core 0.0.0

package/src/default-tools/executors/web-fetch.ts

@@ -0,0 +1,259 @@
+/**
+ * Web Fetch Executor
+ *
+ * Built-in implementation for fetching web content using native fetch.
+ */
+
+import type { ToolContext } from "@clinebot/agents";
+import type { WebFetchExecutor } from "../types.js";
+
+/**
+ * Options for the web fetch executor
+ */
+export interface WebFetchExecutorOptions {
+	/**
+	 * Timeout for fetch requests in milliseconds
+	 * @default 30000 (30 seconds)
+	 */
+	timeoutMs?: number;
+
+	/**
+	 * Maximum response size in bytes
+	 * @default 5_000_000 (5MB)
+	 */
+	maxResponseBytes?: number;
+
+	/**
+	 * User agent string
+	 * @default "Mozilla/5.0 (compatible; AgentBot/1.0)"
+	 */
+	userAgent?: string;
+
+	/**
+	 * Additional headers
+	 */
+	headers?: Record<string, string>;
+
+	/**
+	 * Whether to follow redirects
+	 * @default true
+	 */
+	followRedirects?: boolean;
+
+	/**
+	 * Maximum number of redirects to follow
+	 * @default 5
+	 */
+	maxRedirects?: number;
+}
+
+/**
+ * Extract text content from HTML
+ * Simple implementation - strips tags and normalizes whitespace
+ */
+function htmlToText(html: string): string {
+	return (
+		html
+			// Remove script and style elements
+			.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+			.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+			// Remove HTML comments
+			.replace(/<!--[\s\S]*?-->/g, "")
+			// Replace block elements with newlines
+			.replace(/<(p|div|br|hr|h[1-6]|li|tr)[^>]*>/gi, "\n")
+			// Remove all remaining tags
+			.replace(/<[^>]+>/g, " ")
+			// Decode HTML entities
+			.replace(/&nbsp;/g, " ")
+			.replace(/&amp;/g, "&")
+			.replace(/&lt;/g, "<")
+			.replace(/&gt;/g, ">")
+			.replace(/&quot;/g, '"')
+			.replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
+			// Normalize whitespace
+			.replace(/\s+/g, " ")
+			.replace(/\n\s+/g, "\n")
+			.replace(/\n{3,}/g, "\n\n")
+			.trim()
+	);
+}
+
+/**
+ * Create a web fetch executor using native fetch
+ *
+ * @example
+ * ```typescript
+ * const webFetch = createWebFetchExecutor({
+ *   timeoutMs: 15000,
+ *   maxResponseBytes: 2_000_000,
+ * })
+ *
+ * const content = await webFetch(
+ *   "https://docs.example.com/api",
+ *   "Extract the authentication section",
+ *   context
+ * )
+ * ```
+ */
+export function createWebFetchExecutor(
+	options: WebFetchExecutorOptions = {},
+): WebFetchExecutor {
+	const {
+		timeoutMs = 30000,
+		maxResponseBytes = 5_000_000,
+		userAgent = "Mozilla/5.0 (compatible; AgentBot/1.0)",
+		headers = {},
+		followRedirects = true,
+		// maxRedirects is available in options but native fetch handles it automatically
+	} = options;
+
+	return async (
+		url: string,
+		prompt: string,
+		context: ToolContext,
+	): Promise<string> => {
+		// Validate URL
+		let parsedUrl: URL;
+		try {
+			parsedUrl = new URL(url);
+		} catch {
+			throw new Error(`Invalid URL: ${url}`);
+		}
+
+		// Only allow http and https
+		if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+			throw new Error(
+				`Invalid protocol: ${parsedUrl.protocol}. Only http and https are supported.`,
+			);
+		}
+
+		// Create abort controller for timeout
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), timeoutMs);
+		let contextAbortHandler: (() => void) | undefined;
+
+		// Combine with context abort signal
+		if (context.abortSignal) {
+			contextAbortHandler = () => controller.abort();
+			context.abortSignal.addEventListener("abort", contextAbortHandler);
+		}
+
+		try {
+			const response = await fetch(url, {
+				method: "GET",
+				headers: {
+					"User-Agent": userAgent,
+					Accept:
+						"text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7",
+					"Accept-Language": "en-US,en;q=0.9",
+					...headers,
+				},
+				redirect: followRedirects ? "follow" : "manual",
+				signal: controller.signal,
+			});
+
+			clearTimeout(timeout);
+
+			// Check for redirect limit (if we're checking manually)
+			if (!followRedirects && response.status >= 300 && response.status < 400) {
+				const location = response.headers.get("location");
+				return `Redirect to: ${location}`;
+			}
+
+			// Check response status
+			if (!response.ok) {
+				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			}
+
+			// Get content type
+			const contentType = response.headers.get("content-type") || "";
+
+			// Read response body with size limit
+			const reader = response.body?.getReader();
+			if (!reader) {
+				throw new Error("Failed to read response body");
+			}
+
+			const chunks: Uint8Array[] = [];
+			let totalSize = 0;
+
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+
+				totalSize += value.length;
+				if (totalSize > maxResponseBytes) {
+					reader.cancel();
+					throw new Error(
+						`Response too large: exceeded ${maxResponseBytes} bytes`,
+					);
+				}
+
+				chunks.push(value);
+			}
+
+			// Combine chunks
+			const buffer = new Uint8Array(totalSize);
+			let offset = 0;
+			for (const chunk of chunks) {
+				buffer.set(chunk, offset);
+				offset += chunk.length;
+			}
+
+			// Decode as text
+			const text = new TextDecoder("utf-8").decode(buffer);
+
+			// Process content based on type
+			let content: string;
+			if (
+				contentType.includes("text/html") ||
+				contentType.includes("application/xhtml")
+			) {
+				content = htmlToText(text);
+			} else if (contentType.includes("application/json")) {
+				try {
+					const json = JSON.parse(text);
+					content = JSON.stringify(json, null, 2);
+				} catch {
+					content = text;
+				}
+			} else {
+				content = text;
+			}
+
+			// Format output with metadata
+			const outputLines = [
+				`URL: ${url}`,
+				`Content-Type: ${contentType}`,
+				`Size: ${totalSize} bytes`,
+				``,
+				`--- Content ---`,
+				content.slice(0, 50000), // Limit content size for output
+			];
+
+			if (content.length > 50000) {
+				outputLines.push(
+					`\n[Content truncated: showing first 50000 of ${content.length} characters]`,
+				);
+			}
+
+			outputLines.push(``, `--- Analysis Request ---`, `Prompt: ${prompt}`);
+
+			return outputLines.join("\n");
+		} catch (error) {
+			clearTimeout(timeout);
+
+			if (error instanceof Error) {
+				if (error.name === "AbortError") {
+					throw new Error(`Request timed out after ${timeoutMs}ms`);
+				}
+				throw error;
+			}
+			throw new Error(`Fetch failed: ${String(error)}`);
+		} finally {
+			if (context.abortSignal && contextAbortHandler) {
+				context.abortSignal.removeEventListener("abort", contextAbortHandler);
+			}
+		}
+	};
+}

package/src/default-tools/index.ts

@@ -0,0 +1,161 @@
+/**
+ * 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.js";
+// Tool Definitions
+export {
+	createApplyPatchTool,
+	createAskQuestionTool,
+	createBashTool,
+	createDefaultTools,
+	createEditorTool,
+	createReadFilesTool,
+	createSearchTool,
+	createSkillsTool,
+	createWebFetchTool,
+} from "./definitions.js";
+// 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.js";
+// Presets
+export {
+	createDefaultToolsWithPreset,
+	createToolPoliciesWithPreset,
+	type ToolPolicyPresetName,
+	type ToolPresetName,
+	ToolPresets,
+} from "./presets.js";
+// Schemas
+export {
+	type ApplyPatchInput,
+	ApplyPatchInputSchema,
+	type AskQuestionInput,
+	AskQuestionInputSchema,
+	type EditFileInput,
+	EditFileInputSchema,
+	type FetchWebContentInput,
+	FetchWebContentInputSchema,
+	type ReadFilesInput,
+	ReadFilesInputSchema,
+	type RunCommandsInput,
+	RunCommandsInputSchema,
+	type SearchCodebaseInput,
+	SearchCodebaseInputSchema,
+	type SkillsInput,
+	SkillsInputSchema,
+	type WebFetchRequest,
+	WebFetchRequestSchema,
+} from "./schemas.js";
+// Types
+export type {
+	ApplyPatchExecutor,
+	AskQuestionExecutor,
+	BashExecutor,
+	CreateDefaultToolsOptions,
+	DefaultToolName,
+	DefaultToolsConfig,
+	EditorExecutor,
+	FileReadExecutor,
+	SearchExecutor,
+	SkillsExecutor,
+	SkillsExecutorSkillMetadata,
+	SkillsExecutorWithMetadata,
+	ToolExecutors,
+	ToolOperationResult,
+	WebFetchExecutor,
+} from "./types.js";
+
+// =============================================================================
+// Convenience: Create Tools with Built-in Executors
+// =============================================================================
+
+import type { Tool } from "@clinebot/agents";
+import { createDefaultTools } from "./definitions.js";
+import {
+	createDefaultExecutors,
+	type DefaultExecutorsOptions,
+} from "./executors/index.js";
+import type { CreateDefaultToolsOptions, ToolExecutors } from "./types.js";
+
+/**
+ * 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/server"
+ *
+ * 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/default-tools/presets.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import {
+	createDefaultToolsWithPreset,
+	createToolPoliciesWithPreset,
+	ToolPresets,
+} from "./presets.js";
+
+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(true);
+	});
+
+	it("yolo preset enables all default tools when executors exist", () => {
+		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",
+			"ask_question",
+		]);
+	});
+});
+
+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/default-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.js";
+import { createDefaultTools } from "./definitions.js";
+import type { CreateDefaultToolsOptions, DefaultToolsConfig } from "./types.js";
+
+/**
+ * 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 (everything enabled + 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: true,
+	},
+} 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 all tools 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,
+	});
+}