@clinebot/agents 0.0.0

package/src/tools/ask-question.ts

@@ -0,0 +1,78 @@
+import {
+	type Tool,
+	type ToolContext,
+	validateWithZod,
+	zodToJsonSchema,
+} from "@clinebot/shared";
+import { z } from "zod";
+import { createTool } from "./create.js";
+
+export const AskQuestionInputSchema = z.object({
+	question: z
+		.string()
+		.min(1)
+		.describe(
+			'The single question to ask the user. E.g. "How can I help you?"',
+		),
+	options: z
+		.array(z.string().min(1))
+		.min(2)
+		.max(5)
+		.describe(
+			"Array of 2-5 user-selectable answer options for the single question",
+		),
+});
+
+export type AskQuestionInput = z.infer<typeof AskQuestionInputSchema>;
+
+export type AskQuestionExecutor = (
+	question: string,
+	options: string[],
+	context: ToolContext,
+) => Promise<string>;
+
+export interface AskQuestionToolConfig {
+	askQuestionTimeoutMs?: number;
+}
+
+function withTimeout<T>(
+	promise: Promise<T>,
+	ms: number,
+	message: string,
+): Promise<T> {
+	return Promise.race([
+		promise,
+		new Promise<never>((_, reject) => {
+			setTimeout(() => reject(new Error(message)), ms);
+		}),
+	]);
+}
+
+export function createAskQuestionTool(
+	executor: AskQuestionExecutor,
+	config: AskQuestionToolConfig = {},
+): Tool<AskQuestionInput, string> {
+	const timeoutMs = config.askQuestionTimeoutMs ?? 15000;
+
+	return createTool<AskQuestionInput, string>({
+		name: "ask_question",
+		description:
+			"Ask user a question for clarifying or gathering information needed to complete the task. " +
+			"For example, ask the user clarifying questions about a key implementation decision. " +
+			"You should only ask one question. " +
+			"Provide an array of 2-5 options for the user to choose from. " +
+			"Never include an option to toggle to Act mode.",
+		inputSchema: zodToJsonSchema(AskQuestionInputSchema),
+		timeoutMs,
+		retryable: false,
+		maxRetries: 0,
+		execute: async (input, context) => {
+			const validatedInput = validateWithZod(AskQuestionInputSchema, input);
+			return withTimeout(
+				executor(validatedInput.question, validatedInput.options, context),
+				timeoutMs,
+				`ask_question timed out after ${timeoutMs}ms`,
+			);
+		},
+	});
+}

package/src/tools/create.ts

@@ -0,0 +1,104 @@
+/**
+ * Tool Creation Utilities
+ *
+ * Functions for creating tools with proper typing.
+ */
+
+import type { providers as LlmsProviders } from "@clinebot/llms";
+import { type Tool, type ToolContext, zodToJsonSchema } from "@clinebot/shared";
+import { z } from "zod";
+
+/**
+ * Create a tool with proper typing
+ *
+ * @example
+ * ```typescript
+ * const readFile = createTool({
+ *   name: "read_file",
+ *   description: "Read the contents of a file",
+ *   inputSchema: {
+ *     type: "object",
+ *     properties: {
+ *       path: { type: "string", description: "File path to read" }
+ *     },
+ *     required: ["path"]
+ *   },
+ *   execute: async ({ path }) => {
+ *     const content = await fs.readFile(path, "utf-8")
+ *     return { content }
+ *   }
+ * })
+ * ```
+ */
+export function createTool<TInput, TOutput>(config: {
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown>;
+	execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+	timeoutMs?: number;
+	retryable?: boolean;
+	maxRetries?: number;
+}): Tool<TInput, TOutput>;
+export function createTool<TSchema extends z.ZodTypeAny, TOutput>(config: {
+	name: string;
+	description: string;
+	inputSchema: TSchema;
+	execute: (input: z.infer<TSchema>, context: ToolContext) => Promise<TOutput>;
+	timeoutMs?: number;
+	retryable?: boolean;
+	maxRetries?: number;
+}): Tool<z.infer<TSchema>, TOutput>;
+export function createTool<TInput, TOutput>(config: {
+	name: string;
+	description: string;
+	inputSchema: Record<string, unknown> | z.ZodTypeAny;
+	execute: (input: TInput, context: ToolContext) => Promise<TOutput>;
+	timeoutMs?: number;
+	retryable?: boolean;
+	maxRetries?: number;
+}): Tool<TInput, TOutput> {
+	const inputSchema =
+		config.inputSchema instanceof z.ZodType
+			? zodToJsonSchema(config.inputSchema)
+			: config.inputSchema;
+
+	return {
+		name: config.name,
+		description: config.description,
+		inputSchema,
+		execute: config.execute,
+		timeoutMs: config.timeoutMs ?? 30000,
+		retryable: config.retryable ?? true,
+		maxRetries: config.maxRetries ?? 2,
+	};
+}
+
+/**
+ * Convert a Tool to a ToolDefinition for the provider
+ *
+ * This transforms our internal Tool format into the format expected
+ * by the provider's API.
+ */
+export function toToolDefinition(tool: Tool): LlmsProviders.ToolDefinition {
+	return {
+		name: tool.name,
+		description: tool.description,
+		inputSchema: {
+			type: "object",
+			properties: tool.inputSchema.properties as Record<string, unknown>,
+			required: tool.inputSchema.required as string[] | undefined,
+			additionalProperties: tool.inputSchema.additionalProperties as
+				| boolean
+				| undefined,
+		},
+	};
+}
+
+/**
+ * Convert an array of Tools to ToolDefinitions
+ */
+export function toToolDefinitions(
+	tools: Tool[],
+): LlmsProviders.ToolDefinition[] {
+	return tools.map(toToolDefinition);
+}

package/src/tools/execution.ts

@@ -0,0 +1,311 @@
+/**
+ * Tool Execution
+ *
+ * Functions for executing tools with error handling, timeouts, and retries.
+ */
+
+import type { Tool, ToolCallRecord, ToolContext } from "@clinebot/shared";
+import type { PendingToolCall } from "../types.js";
+
+export interface ToolExecutionObserver {
+	onToolCallStart?: (call: PendingToolCall) => Promise<void> | void;
+	onToolCallEnd?: (record: ToolCallRecord) => Promise<void> | void;
+}
+
+export interface ToolExecutionAuthorizer {
+	authorize?: (
+		call: PendingToolCall,
+		context: ToolContext,
+	) =>
+		| Promise<{ allowed: true } | { allowed: false; reason: string }>
+		| { allowed: true }
+		| { allowed: false; reason: string };
+}
+
+export interface ToolExecutionOptions {
+	maxConcurrency?: number;
+}
+
+/**
+ * Execute a single tool with error handling and timeout
+ *
+ * @param tool - The tool to execute
+ * @param input - The input to pass to the tool
+ * @param context - The execution context
+ * @returns A record of the tool call execution
+ */
+export async function executeTool(
+	tool: Tool,
+	input: unknown,
+	context: ToolContext,
+): Promise<{ output: unknown; error?: string; durationMs: number }> {
+	const startTime = Date.now();
+	const timeoutMs = tool.timeoutMs ?? 30000;
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	let abortHandler: (() => void) | undefined;
+
+	// Create a timeout promise
+	const timeoutPromise = new Promise<never>((_, reject) => {
+		timeoutId = setTimeout(() => {
+			reject(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+	});
+
+	// Create abort handling
+	const abortPromise = context.abortSignal
+		? new Promise<never>((_, reject) => {
+				if (context.abortSignal?.aborted) {
+					reject(new Error("Tool execution was aborted"));
+					return;
+				}
+				abortHandler = () => {
+					reject(new Error("Tool execution was aborted"));
+				};
+				context.abortSignal?.addEventListener("abort", abortHandler);
+			})
+		: null;
+
+	try {
+		// Execute with timeout and optional abort
+		const promises: Promise<unknown>[] = [
+			tool.execute(input, context),
+			timeoutPromise,
+		];
+		if (abortPromise) {
+			promises.push(abortPromise);
+		}
+
+		const output = await Promise.race(promises);
+		const durationMs = Date.now() - startTime;
+
+		return { output, durationMs };
+	} catch (error) {
+		const durationMs = Date.now() - startTime;
+		const errorMessage = error instanceof Error ? error.message : String(error);
+
+		return { output: null, error: errorMessage, durationMs };
+	} finally {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+		}
+		if (context.abortSignal && abortHandler) {
+			context.abortSignal.removeEventListener("abort", abortHandler);
+		}
+	}
+}
+
+/**
+ * Execute a tool with retries
+ */
+export async function executeToolWithRetry(
+	tool: Tool,
+	input: unknown,
+	context: ToolContext,
+): Promise<{ output: unknown; error?: string; durationMs: number }> {
+	const maxRetries = tool.maxRetries ?? 2;
+	let lastResult: {
+		output: unknown;
+		error?: string;
+		durationMs: number;
+	} | null = null;
+
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		// Check for abort before each attempt
+		if (context.abortSignal?.aborted) {
+			return {
+				output: null,
+				error: "Tool execution was aborted",
+				durationMs: lastResult?.durationMs ?? 0,
+			};
+		}
+
+		const result = await executeTool(tool, input, context);
+		lastResult = result;
+
+		// If no error, return immediately
+		if (!result.error) {
+			return result;
+		}
+
+		// If tool is not retryable or we've exhausted retries, return the error
+		if (!tool.retryable || attempt === maxRetries) {
+			return result;
+		}
+
+		// Wait a bit before retrying (exponential backoff)
+		const delayMs = Math.min(1000 * 2 ** attempt, 10000);
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+
+	return lastResult!;
+}
+
+/**
+ * Execute multiple tools in parallel
+ *
+ * @param toolRegistry - Map of tools by name
+ * @param calls - Array of tool calls to execute
+ * @param context - The execution context
+ * @returns Array of tool call records
+ */
+export async function executeToolsInParallel(
+	toolRegistry: Map<string, Tool>,
+	calls: PendingToolCall[],
+	context: ToolContext,
+	observer?: ToolExecutionObserver,
+	authorizer?: ToolExecutionAuthorizer,
+	options?: ToolExecutionOptions,
+): Promise<ToolCallRecord[]> {
+	const executeCall = async (
+		call: PendingToolCall,
+	): Promise<ToolCallRecord> => {
+		const startedAt = new Date();
+		await observer?.onToolCallStart?.(call);
+		const tool = toolRegistry.get(call.name);
+
+		if (!tool) {
+			const endedAt = new Date();
+			const record = {
+				id: call.id,
+				name: call.name,
+				input: call.input,
+				output: null,
+				error: `Unknown tool: ${call.name}`,
+				durationMs: endedAt.getTime() - startedAt.getTime(),
+				startedAt,
+				endedAt,
+			};
+			await observer?.onToolCallEnd?.(record);
+			return record;
+		}
+
+		const authorization = await authorizer?.authorize?.(call, context);
+		if (authorization && !authorization.allowed) {
+			const endedAt = new Date();
+			const record = {
+				id: call.id,
+				name: call.name,
+				input: call.input,
+				output: null,
+				error: authorization.reason,
+				durationMs: endedAt.getTime() - startedAt.getTime(),
+				startedAt,
+				endedAt,
+			};
+			await observer?.onToolCallEnd?.(record);
+			return record;
+		}
+
+		const result = await executeToolWithRetry(tool, call.input, context);
+		const endedAt = new Date();
+
+		const record = {
+			id: call.id,
+			name: call.name,
+			input: call.input,
+			output: result.output,
+			error: result.error,
+			durationMs: result.durationMs,
+			startedAt,
+			endedAt,
+		};
+		await observer?.onToolCallEnd?.(record);
+		return record;
+	};
+
+	const maxConcurrency = Math.max(
+		1,
+		options?.maxConcurrency ?? (calls.length || 1),
+	);
+	const results = new Array<ToolCallRecord>(calls.length);
+	let nextIndex = 0;
+	const workerCount = Math.min(maxConcurrency, calls.length);
+	const workers = Array.from({ length: workerCount }, async () => {
+		while (true) {
+			const index = nextIndex++;
+			if (index >= calls.length) {
+				return;
+			}
+			results[index] = await executeCall(calls[index]);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+
+/**
+ * Execute tools sequentially (for cases where order matters)
+ */
+export async function executeToolsSequentially(
+	toolRegistry: Map<string, Tool>,
+	calls: PendingToolCall[],
+	context: ToolContext,
+	observer?: ToolExecutionObserver,
+	authorizer?: ToolExecutionAuthorizer,
+): Promise<ToolCallRecord[]> {
+	const results: ToolCallRecord[] = [];
+
+	for (const call of calls) {
+		// Check for abort before each tool
+		if (context.abortSignal?.aborted) {
+			break;
+		}
+
+		const startedAt = new Date();
+		await observer?.onToolCallStart?.(call);
+		const tool = toolRegistry.get(call.name);
+
+		if (!tool) {
+			const endedAt = new Date();
+			const record = {
+				id: call.id,
+				name: call.name,
+				input: call.input,
+				output: null,
+				error: `Unknown tool: ${call.name}`,
+				durationMs: endedAt.getTime() - startedAt.getTime(),
+				startedAt,
+				endedAt,
+			};
+			await observer?.onToolCallEnd?.(record);
+			results.push(record);
+			continue;
+		}
+
+		const authorization = await authorizer?.authorize?.(call, context);
+		if (authorization && !authorization.allowed) {
+			const endedAt = new Date();
+			const record = {
+				id: call.id,
+				name: call.name,
+				input: call.input,
+				output: null,
+				error: authorization.reason,
+				durationMs: endedAt.getTime() - startedAt.getTime(),
+				startedAt,
+				endedAt,
+			};
+			await observer?.onToolCallEnd?.(record);
+			results.push(record);
+			continue;
+		}
+
+		const result = await executeToolWithRetry(tool, call.input, context);
+		const endedAt = new Date();
+
+		const record = {
+			id: call.id,
+			name: call.name,
+			input: call.input,
+			output: result.output,
+			error: result.error,
+			durationMs: result.durationMs,
+			startedAt,
+			endedAt,
+		};
+		await observer?.onToolCallEnd?.(record);
+		results.push(record);
+	}
+
+	return results;
+}

package/src/tools/formatting.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool Result Formatting
+ *
+ * Functions for formatting tool results for various purposes.
+ */
+
+import type { ToolCallRecord } from "../types.js";
+
+/**
+ * Format a tool result for sending back to the model
+ *
+ * The result is serialized to a string (JSON for objects, string for primitives)
+ */
+export function formatToolResult(output: unknown, error?: string): string {
+	if (error) {
+		return JSON.stringify({ error });
+	}
+
+	if (output === null || output === undefined) {
+		return "null";
+	}
+
+	if (typeof output === "string") {
+		return output;
+	}
+
+	if (typeof output === "number" || typeof output === "boolean") {
+		return String(output);
+	}
+
+	try {
+		return JSON.stringify(output);
+	} catch {
+		return String(output);
+	}
+}
+
+/**
+ * Format multiple tool results into a structured summary
+ */
+export function formatToolResultsSummary(records: ToolCallRecord[]): string {
+	if (records.length === 0) {
+		return "No tools were called.";
+	}
+
+	const lines = records.map((record) => {
+		const status = record.error ? "FAILED" : "SUCCESS";
+		const duration = `${record.durationMs}ms`;
+		return `- ${record.name}: ${status} (${duration})`;
+	});
+
+	return `Tool Results:\n${lines.join("\n")}`;
+}
+
+/**
+ * Format a tool call record as a detailed string
+ */
+export function formatToolCallRecord(record: ToolCallRecord): string {
+	const lines = [
+		`Tool: ${record.name}`,
+		`ID: ${record.id}`,
+		`Status: ${record.error ? "FAILED" : "SUCCESS"}`,
+		`Duration: ${record.durationMs}ms`,
+		`Started: ${record.startedAt.toISOString()}`,
+		`Ended: ${record.endedAt.toISOString()}`,
+	];
+
+	if (record.error) {
+		lines.push(`Error: ${record.error}`);
+	}
+
+	return lines.join("\n");
+}

package/src/tools/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool Utilities
+ *
+ * This module provides utilities for creating, managing, and executing tools.
+ */
+
+export {
+	type AskQuestionExecutor,
+	type AskQuestionInput,
+	AskQuestionInputSchema,
+	type AskQuestionToolConfig,
+	createAskQuestionTool,
+} from "./ask-question.js";
+// Creation
+export { createTool, toToolDefinition, toToolDefinitions } from "./create.js";
+// Execution
+export {
+	executeTool,
+	executeToolsInParallel,
+	executeToolsSequentially,
+	executeToolWithRetry,
+	type ToolExecutionAuthorizer,
+	type ToolExecutionObserver,
+} from "./execution.js";
+// Formatting
+export {
+	formatToolCallRecord,
+	formatToolResult,
+	formatToolResultsSummary,
+} from "./formatting.js";
+// Registry
+export {
+	createToolRegistry,
+	getAllTools,
+	getTool,
+	getToolNames,
+	hasTool,
+} from "./registry.js";
+
+// Validation
+export {
+	validateToolDefinition,
+	validateToolInput,
+	validateTools,
+} from "./validation.js";

package/src/tools/registry.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool Registry
+ *
+ * Utilities for managing collections of tools.
+ */
+
+import type { Tool } from "../types.js";
+
+/**
+ * Create a map of tools by name for quick lookup
+ */
+export function createToolRegistry(tools: Tool[]): Map<string, Tool> {
+	const registry = new Map<string, Tool>();
+	for (const tool of tools) {
+		if (registry.has(tool.name)) {
+			throw new Error(`Duplicate tool name: ${tool.name}`);
+		}
+		registry.set(tool.name, tool);
+	}
+	return registry;
+}
+
+/**
+ * Get a tool by name from the registry
+ */
+export function getTool(
+	registry: Map<string, Tool>,
+	name: string,
+): Tool | undefined {
+	return registry.get(name);
+}
+
+/**
+ * Check if a tool exists in the registry
+ */
+export function hasTool(registry: Map<string, Tool>, name: string): boolean {
+	return registry.has(name);
+}
+
+/**
+ * Get all tool names from the registry
+ */
+export function getToolNames(registry: Map<string, Tool>): string[] {
+	return Array.from(registry.keys());
+}
+
+/**
+ * Get all tools from the registry
+ */
+export function getAllTools(registry: Map<string, Tool>): Tool[] {
+	return Array.from(registry.values());
+}