@falai/agent 0.9.0 → 0.9.2

package/dist/cjs/src/core/ToolManager.d.ts

@@ -0,0 +1,234 @@
+/**
+ * ToolManager - Centralized tool management with simplified creation APIs
+ */
+import type { Tool, ToolExecutionResult, DataEnrichmentConfig, ValidationConfig, ValidationResult, ApiCallConfig, ComputationConfig, Event } from "../types";
+import { ToolScope } from "../types";
+import { Agent } from "./Agent";
+import { Route } from "./Route";
+import { Step } from "./Step";
+/**
+ * Error thrown when tool creation fails
+ */
+export declare class ToolCreationError extends Error {
+    readonly toolId: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, toolId: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when tool execution fails
+ */
+export declare class ToolExecutionError extends Error {
+    readonly toolId: string;
+    readonly executionContext?: Record<string, unknown> | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, toolId: string, executionContext?: Record<string, unknown> | undefined, cause?: Error | undefined);
+}
+/**
+ * ToolManager - Centralized tool management with simplified APIs
+ */
+export declare class ToolManager<TContext = unknown, TData = unknown> {
+    private agent;
+    private toolRegistry;
+    constructor(agent: Agent<TContext, TData>);
+    /**
+     * Validate a tool definition for completeness and correctness
+     */
+    private validateToolDefinition;
+    /**
+     * Validate data enrichment configuration
+     */
+    private validateDataEnrichmentConfig;
+    /**
+     * Validate validation configuration
+     */
+    private validateValidationConfig;
+    /**
+     * Validate API call configuration
+     */
+    private validateApiCallConfig;
+    /**
+     * Validate computation configuration
+     */
+    private validateComputationConfig;
+    /**
+     * Create a tool instance with type inference from parent Agent
+     * Does not register the tool anywhere - just creates it
+     */
+    create(definition: Tool<TContext, TData>): Tool<TContext, TData>;
+    /**
+     * Register a tool in the registry for later reference by ID
+     * Can accept a tool instance
+     */
+    register(tool: Tool<TContext, TData>): Tool<TContext, TData>;
+    /**
+     * Register multiple tools at once
+     */
+    registerMany(tools: Array<Tool<TContext, TData>>): Tool<TContext, TData>[];
+    /**
+     * Get a registered tool by ID
+     */
+    getRegisteredTool(toolId: string): Tool<TContext, TData> | undefined;
+    /**
+     * Get all registered tools
+     */
+    getAllRegistered(): Map<string, Tool<TContext, TData>>;
+    /**
+     * Check if a tool is registered
+     */
+    isRegistered(toolId: string): boolean;
+    /**
+     * Get all registered tool IDs
+     */
+    getRegisteredIds(): string[];
+    /**
+     * Get tool by ID from a specific scope
+     */
+    getFromScope(toolId: string, scope: ToolScope, step?: Step<TContext, TData>, route?: Route<TContext, TData>): Tool<TContext, TData> | undefined;
+    /**
+     * Check if a tool exists in any scope
+     */
+    exists(toolId: string, step?: Step<TContext, TData>, route?: Route<TContext, TData>): boolean;
+    /**
+     * Get tool count by scope
+     */
+    getToolCount(scope?: ToolScope, step?: Step<TContext, TData>, route?: Route<TContext, TData>): number;
+    /**
+     * Clear all registered tools
+     */
+    clearRegistry(): void;
+    /**
+     * Remove a tool from registry
+     */
+    unregister(toolId: string): boolean;
+    /**
+     * Add a tool to the agent scope (creates and adds in one operation)
+     */
+    addToAgent(tool: Tool<TContext, TData>): Tool<TContext, TData>;
+    /**
+     * Add a tool to a specific route scope (creates and adds in one operation)
+     */
+    addToRoute(route: Route<TContext, TData>, tool: Tool<TContext, TData>): Tool<TContext, TData>;
+    /**
+     * Find a tool by ID across different scopes with enhanced resolution logic
+     * Priority: step → route → agent → registry
+     * Supports both ID and name matching for better compatibility
+     */
+    find(toolId: string, scope?: ToolScope, step?: Step<TContext, TData>, route?: Route<TContext, TData>): Tool<TContext, TData> | undefined;
+    /**
+     * Get available tools for current context with enhanced resolution and deduplication
+     * Returns tools in priority order with higher-priority scopes taking precedence
+     */
+    getAvailable(scope?: ToolScope, step?: Step<TContext, TData>, route?: Route<TContext, TData>): Tool<TContext, TData>[];
+    /**
+     * Execute a tool by ID with proper error handling and fallback strategies
+     * Consolidates tool execution logic from ToolExecutor and ResponseModal
+     */
+    execute(toolId: string, args?: Record<string, unknown>, context?: {
+        step?: Step<TContext, TData>;
+        route?: Route<TContext, TData>;
+        context?: TContext;
+        data?: Partial<TData>;
+        history?: Event[];
+        updateContext?: (updates: Partial<TContext>) => Promise<void>;
+        updateData?: (updates: Partial<TData>) => Promise<void>;
+        fallbackTools?: string[];
+        retryCount?: number;
+    }): Promise<ToolExecutionResult>;
+    /**
+     * Determine if an error is transient and should be retried
+     */
+    private isTransientError;
+    /**
+     * Execute a single tool with context and collected data
+     * Consolidates logic from ToolExecutor class with enhanced error handling
+     */
+    executeTool(params: {
+        tool: Tool<TContext, TData>;
+        context: TContext;
+        updateContext: (updates: Partial<TContext>) => Promise<void>;
+        updateData: (updates: Partial<TData>) => Promise<void>;
+        history: Event[];
+        data?: Partial<TData>;
+        toolArguments?: Record<string, unknown>;
+    }): Promise<ToolExecutionResult>;
+    /**
+     * Execute multiple tools in sequence
+     * Consolidates logic from ToolExecutor class
+     */
+    executeTools(params: {
+        tools: Array<Tool<TContext, TData>>;
+        context: TContext;
+        updateContext: (updates: Partial<TContext>) => Promise<void>;
+        updateData: (updates: Partial<TData>) => Promise<void>;
+        history: Event[];
+        data?: Partial<TData>;
+    }): Promise<ToolExecutionResult[]>;
+    /**
+     * Create a data enrichment tool that modifies collected data
+     * Returns a tool instance that can be registered or added to scope
+     */
+    createDataEnrichment<TFields extends keyof TData>(config: DataEnrichmentConfig<TContext, TData, TFields>): Tool<TContext, TData, void>;
+    /**
+     * Create a validation tool that validates data fields
+     * Returns a tool instance that can be registered or added to scope
+     */
+    createValidation<TFields extends keyof TData>(config: ValidationConfig<TContext, TData, TFields>): Tool<TContext, TData, ValidationResult>;
+    /**
+     * Create an API call tool that makes external HTTP requests
+     * Returns a tool instance that can be registered or added to scope
+     */
+    createApiCall<TResult = unknown>(config: ApiCallConfig<TContext, TData, TResult>): Tool<TContext, TData, TResult>;
+    /**
+     * Create a computation tool that performs calculations on input data
+     * Returns a tool instance that can be registered or added to scope
+     */
+    createComputation<TResult = unknown>(config: ComputationConfig<TContext, TData, TResult>): Tool<TContext, TData, TResult>;
+    /**
+     * Get detailed information about a tool for debugging
+     */
+    getToolInfo(toolId: string, scope?: ToolScope, step?: Step<TContext, TData>, route?: Route<TContext, TData>): {
+        found: boolean;
+        tool?: Tool<TContext, TData>;
+        scope?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /**
+     * Validate that all tools in a list exist and are accessible
+     */
+    validateToolReferences(toolIds: string[], step?: Step<TContext, TData>, route?: Route<TContext, TData>): {
+        valid: boolean;
+        missing: string[];
+        found: string[];
+        details: Array<{
+            id: string;
+            found: boolean;
+            scope?: string;
+        }>;
+    };
+    /**
+     * Get comprehensive statistics about the tool system
+     */
+    getStatistics(): {
+        registeredTools: number;
+        agentTools: number;
+        totalAvailable: number;
+        registeredToolIds: string[];
+        duplicateIds: string[];
+    };
+    /**
+     * Perform health check on the tool system
+     */
+    healthCheck(): {
+        healthy: boolean;
+        issues: string[];
+        warnings: string[];
+        statistics: {
+            registeredTools: number;
+            agentTools: number;
+            totalAvailable: number;
+            registeredToolIds: string[];
+            duplicateIds: string[];
+        };
+    };
+}
+//# sourceMappingURL=ToolManager.d.ts.map

package/dist/cjs/src/core/ToolManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolManager.d.ts","sourceRoot":"","sources":["../../../../src/core/ToolManager.ts"],"names":[],"mappings":"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"}