@falai/agent 3.4.5 → 4.0.0-alpha.2

package/dist/core/ToolManager.d.ts

@@ -1,250 +0,0 @@
-/**
- * ToolManager - Centralized tool management with simplified creation APIs
- */
-import type { Tool, ToolExecutionResult, DataEnrichmentConfig, ValidationConfig, ValidationResult, ApiCallConfig, ComputationConfig, ToolCallRequest, ToolExecutionUpdate, Event } from "../types/index.js";
-import { ToolScope } from "../types/index.js";
-import type { Agent } from "./Agent.js";
-import { Flow } from "./Flow.js";
-import { Step } from "./Step.js";
-/**
- * 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;
-    /**
-     * Per-turn transient tool layer populated from Directive.injectTools.
-     * Resolution order: transient → step → flow → agent.
-     * Drained at end of turn via try/finally guard.
-     *
-     * Tools are deduplicated by `id` with last-definition-wins when
-     * multiple pre-LLM emitters contribute tools in the same turn.
-     */
-    private transientTools;
-    constructor(agent: Agent<TContext, TData>);
-    /**
-     * Set the transient tool layer for the current turn.
-     *
-     * Accepts the merged `injectTools` array from pre-LLM emitters
-     * (concatenated in outer-to-inner order).
-     * Deduplicates by tool `id` with last-definition-wins.
-     *
-     * Must be paired with `clearTransientTools()` in a try/finally guard
-     * so the layer is drained even on abnormal termination.
-     */
-    setTransientTools(tools: Tool<TContext, TData>[]): void;
-    /**
-     * Clear the transient tool layer. Called at end of turn via try/finally
-     * guard so tools do not leak into subsequent turns.
-     */
-    clearTransientTools(): void;
-    /**
-     * Check whether the transient layer currently has any tools.
-     * Useful for testing and debugging.
-     */
-    hasTransientTools(): boolean;
-    /**
-     * 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>, flow?: Flow<TContext, TData>): Tool<TContext, TData> | undefined;
-    /**
-     * Check if a tool exists in any scope
-     */
-    exists(toolId: string, step?: Step<TContext, TData>, flow?: Flow<TContext, TData>): boolean;
-    /**
-     * Get tool count by scope
-     */
-    getToolCount(scope?: ToolScope, step?: Step<TContext, TData>, flow?: Flow<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 flow scope (creates and adds in one operation)
-     */
-    addToFlow(flow: Flow<TContext, TData>, tool: Tool<TContext, TData>): Tool<TContext, TData>;
-    /**
-     * Find a tool by ID across different scopes with enhanced resolution logic
-     * Priority: transient → step → flow → agent → registry
-     * Supports both ID and name matching for better compatibility
-     */
-    find(toolId: string, scope?: ToolScope, step?: Step<TContext, TData>, flow?: Flow<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
-     * Resolution order: transient → step → flow → agent → registry
-     */
-    getAvailable(scope?: ToolScope, step?: Step<TContext, TData>, flow?: Flow<TContext, TData>): Tool<TContext, TData>[];
-    /**
-     * Execute a single tool with context and collected data.
-     */
-    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 tool calls with concurrency control using StreamingToolExecutor.
-     * Creates a StreamingToolExecutor, resolves tools, queues them, and yields
-     * ToolExecutionUpdate results in original request order.
-     *
-     * Concurrency-safe tools run in parallel; non-safe tools run serially.
-     * Progress messages are yielded immediately.
-     */
-    executeWithConcurrency(params: {
-        toolCalls: ToolCallRequest[];
-        context: TContext;
-        data?: Partial<TData>;
-        history?: Event[];
-        signal?: AbortSignal;
-        flow?: Flow<TContext, TData>;
-        step?: Step<TContext, TData>;
-    }): AsyncGenerator<ToolExecutionUpdate<TData>>;
-    /**
-     * 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>, flow?: Flow<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>, flow?: Flow<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/core/ToolManager.d.ts.map

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