@clinebot/agents 0.0.0

package/dist/tools/create.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool Creation Utilities
+ *
+ * Functions for creating tools with proper typing.
+ */
+import type { providers as LlmsProviders } from "@clinebot/llms";
+import { type Tool, type ToolContext } 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 declare 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 declare 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>;
+/**
+ * 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 declare function toToolDefinition(tool: Tool): LlmsProviders.ToolDefinition;
+/**
+ * Convert an array of Tools to ToolDefinitions
+ */
+export declare function toToolDefinitions(tools: Tool[]): LlmsProviders.ToolDefinition[];

package/dist/tools/execution.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare function executeTool(tool: Tool, input: unknown, context: ToolContext): Promise<{
+    output: unknown;
+    error?: string;
+    durationMs: number;
+}>;
+/**
+ * Execute a tool with retries
+ */
+export declare function executeToolWithRetry(tool: Tool, input: unknown, context: ToolContext): Promise<{
+    output: unknown;
+    error?: string;
+    durationMs: number;
+}>;
+/**
+ * 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 declare function executeToolsInParallel(toolRegistry: Map<string, Tool>, calls: PendingToolCall[], context: ToolContext, observer?: ToolExecutionObserver, authorizer?: ToolExecutionAuthorizer, options?: ToolExecutionOptions): Promise<ToolCallRecord[]>;
+/**
+ * Execute tools sequentially (for cases where order matters)
+ */
+export declare function executeToolsSequentially(toolRegistry: Map<string, Tool>, calls: PendingToolCall[], context: ToolContext, observer?: ToolExecutionObserver, authorizer?: ToolExecutionAuthorizer): Promise<ToolCallRecord[]>;

package/dist/tools/formatting.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function formatToolResult(output: unknown, error?: string): string;
+/**
+ * Format multiple tool results into a structured summary
+ */
+export declare function formatToolResultsSummary(records: ToolCallRecord[]): string;
+/**
+ * Format a tool call record as a detailed string
+ */
+export declare function formatToolCallRecord(record: ToolCallRecord): string;

package/dist/tools/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export { createTool, toToolDefinition, toToolDefinitions } from "./create.js";
+export { executeTool, executeToolsInParallel, executeToolsSequentially, executeToolWithRetry, type ToolExecutionAuthorizer, type ToolExecutionObserver, } from "./execution.js";
+export { formatToolCallRecord, formatToolResult, formatToolResultsSummary, } from "./formatting.js";
+export { createToolRegistry, getAllTools, getTool, getToolNames, hasTool, } from "./registry.js";
+export { validateToolDefinition, validateToolInput, validateTools, } from "./validation.js";

package/dist/tools/registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 declare function createToolRegistry(tools: Tool[]): Map<string, Tool>;
+/**
+ * Get a tool by name from the registry
+ */
+export declare function getTool(registry: Map<string, Tool>, name: string): Tool | undefined;
+/**
+ * Check if a tool exists in the registry
+ */
+export declare function hasTool(registry: Map<string, Tool>, name: string): boolean;
+/**
+ * Get all tool names from the registry
+ */
+export declare function getToolNames(registry: Map<string, Tool>): string[];
+/**
+ * Get all tools from the registry
+ */
+export declare function getAllTools(registry: Map<string, Tool>): Tool[];

package/dist/tools/validation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tool Validation
+ *
+ * Functions for validating tools and tool inputs.
+ */
+import type { Tool } from "../types.js";
+/**
+ * Validate that all tools have unique names
+ */
+export declare function validateTools(tools: Tool[]): void;
+/**
+ * Validate tool input against its schema (basic validation)
+ *
+ * Note: This is a simplified validation. For full JSON Schema validation,
+ * consider using a library like ajv.
+ */
+export declare function validateToolInput(tool: Tool, input: unknown): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate a tool definition
+ */
+export declare function validateToolDefinition(tool: Tool): {
+    valid: boolean;
+    errors: string[];
+};