@falai/agent 3.4.5 → 4.0.0-alpha.2

package/dist/core/ToolManager.js

@@ -1,1098 +0,0 @@
-/**
- * ToolManager - Centralized tool management with simplified creation APIs
- */
-import { ToolScope } from "../types/index.js";
-import { logger, isToolResultLike, extractResultDirectives } from "../utils/index.js";
-import { StreamingToolExecutor } from "./StreamingToolExecutor.js";
-import { evaluateToolGates } from "./toolGates.js";
-/**
- * Error thrown when tool creation fails
- */
-export class ToolCreationError extends Error {
-    constructor(message, toolId, cause) {
-        super(message);
-        this.toolId = toolId;
-        this.cause = cause;
-        this.name = 'ToolCreationError';
-    }
-}
-/**
- * Error thrown when tool execution fails
- */
-export class ToolExecutionError extends Error {
-    constructor(message, toolId, executionContext, cause) {
-        super(message);
-        this.toolId = toolId;
-        this.executionContext = executionContext;
-        this.cause = cause;
-        this.name = 'ToolExecutionError';
-    }
-}
-/**
- * ToolManager - Centralized tool management with simplified APIs
- */
-export class ToolManager {
-    constructor(agent) {
-        this.agent = agent;
-        /**
-         * 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.
-         */
-        this.transientTools = new Map();
-        this.toolRegistry = new Map();
-    }
-    /**
-     * 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) {
-        this.transientTools.clear();
-        for (const tool of tools) {
-            this.transientTools.set(tool.id, tool);
-        }
-        if (this.transientTools.size > 0) {
-            logger.debug(`[ToolManager] Set transient tools for turn: ${Array.from(this.transientTools.keys()).join(', ')}`);
-        }
-    }
-    /**
-     * Clear the transient tool layer. Called at end of turn via try/finally
-     * guard so tools do not leak into subsequent turns.
-     */
-    clearTransientTools() {
-        if (this.transientTools.size > 0) {
-            logger.debug(`[ToolManager] Cleared transient tools: ${Array.from(this.transientTools.keys()).join(', ')}`);
-        }
-        this.transientTools.clear();
-    }
-    /**
-     * Check whether the transient layer currently has any tools.
-     * Useful for testing and debugging.
-     */
-    hasTransientTools() {
-        return this.transientTools.size > 0;
-    }
-    /**
-     * Validate a tool definition for completeness and correctness
-     */
-    validateToolDefinition(definition) {
-        const errors = [];
-        // Required fields validation
-        if (!definition.id || typeof definition.id !== 'string') {
-            errors.push('Tool ID is required and must be a non-empty string');
-        }
-        else if (definition.id.trim() === '') {
-            errors.push('Tool ID cannot be empty or whitespace only');
-        }
-        else if (!/^[a-zA-Z0-9_-]+$/.test(definition.id)) {
-            errors.push('Tool ID must contain only alphanumeric characters, underscores, and hyphens');
-        }
-        if (!definition.handler || typeof definition.handler !== 'function') {
-            errors.push('Tool handler is required and must be a function');
-        }
-        if (definition.description !== undefined && (typeof definition.description !== 'string' || definition.description.trim() === '')) {
-            errors.push('Tool description must be a non-empty string if provided');
-        }
-        // Parameters validation (basic JSON schema check)
-        if (definition.parameters !== undefined) {
-            try {
-                if (typeof definition.parameters === 'object' && definition.parameters !== null) {
-                    // Basic validation for JSON schema structure
-                    const params = definition.parameters;
-                    if ('type' in params && params.type && typeof params.type !== 'string') {
-                        errors.push('Tool parameters type must be a string if specified');
-                    }
-                    if ('properties' in params && params.properties && typeof params.properties !== 'object') {
-                        errors.push('Tool parameters properties must be an object if specified');
-                    }
-                }
-                else if (typeof definition.parameters !== 'string') {
-                    errors.push('Tool parameters must be an object (JSON schema) or string if provided');
-                }
-            }
-            catch {
-                errors.push('Tool parameters must be valid JSON schema or string');
-            }
-        }
-        if (errors.length > 0) {
-            throw new ToolCreationError(`[ToolCreationError] Tool definition validation failed for "${definition.id || 'unknown'}": ${errors.join('; ')}. ` +
-                `Fix the tool definition to meet the required schema.`, definition.id || 'unknown');
-        }
-    }
-    /**
-     * Validate data enrichment configuration
-     */
-    validateDataEnrichmentConfig(config) {
-        const errors = [];
-        if (!config.fields || !Array.isArray(config.fields) || config.fields.length === 0) {
-            errors.push('Data enrichment fields must be a non-empty array');
-        }
-        if (!config.enricher || typeof config.enricher !== 'function') {
-            errors.push('Data enrichment enricher must be a function');
-        }
-        if (errors.length > 0) {
-            throw new ToolCreationError(`[ToolCreationError] Data enrichment config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
-                `Fix the enrichment config to satisfy the required fields.`, config.id || 'unknown');
-        }
-    }
-    /**
-     * Validate validation configuration
-     */
-    validateValidationConfig(config) {
-        const errors = [];
-        if (!config.fields || !Array.isArray(config.fields) || config.fields.length === 0) {
-            errors.push('Validation fields must be a non-empty array');
-        }
-        if (!config.validator || typeof config.validator !== 'function') {
-            errors.push('Validation validator must be a function');
-        }
-        if (errors.length > 0) {
-            throw new ToolCreationError(`[ToolCreationError] Validation config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
-                `Fix the validation config to satisfy the required fields.`, config.id || 'unknown');
-        }
-    }
-    /**
-     * Validate API call configuration
-     */
-    validateApiCallConfig(config) {
-        const errors = [];
-        if (!config.endpoint) {
-            errors.push('API call endpoint is required');
-        }
-        else if (typeof config.endpoint !== 'string' && typeof config.endpoint !== 'function') {
-            errors.push('API call endpoint must be a string or function');
-        }
-        if (config.method && !['GET', 'POST', 'PUT', 'DELETE'].includes(config.method)) {
-            errors.push('API call method must be one of: GET, POST, PUT, DELETE');
-        }
-        if (config.headers && typeof config.headers !== 'object' && typeof config.headers !== 'function') {
-            errors.push('API call headers must be an object or function');
-        }
-        if (config.body && typeof config.body !== 'function') {
-            errors.push('API call body must be a function');
-        }
-        if (config.transform && typeof config.transform !== 'function') {
-            errors.push('API call transform must be a function');
-        }
-        if (errors.length > 0) {
-            throw new ToolCreationError(`[ToolCreationError] API call config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
-                `Fix the API call config to satisfy the required fields.`, config.id || 'unknown');
-        }
-    }
-    /**
-     * Validate computation configuration
-     */
-    validateComputationConfig(config) {
-        const errors = [];
-        if (!config.inputs || !Array.isArray(config.inputs) || config.inputs.length === 0) {
-            errors.push('Computation inputs must be a non-empty array');
-        }
-        if (!config.compute || typeof config.compute !== 'function') {
-            errors.push('Computation compute function is required');
-        }
-        if (errors.length > 0) {
-            throw new ToolCreationError(`[ToolCreationError] Computation config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
-                `Fix the computation config to satisfy the required fields.`, config.id || 'unknown');
-        }
-    }
-    /**
-     * Create a tool instance with type inference from parent Agent
-     * Does not register the tool anywhere - just creates it
-     */
-    create(definition) {
-        try {
-            // Validate the tool definition first
-            this.validateToolDefinition(definition);
-            logger.debug(`[ToolManager] Created tool: ${definition.id}`);
-            return definition;
-        }
-        catch (error) {
-            throw new ToolCreationError(`[ToolCreationError] Failed to create tool "${definition.id}": ${error instanceof Error ? error.message : String(error)}. ` +
-                `Ensure the tool definition passes validation.`, definition.id, error instanceof Error ? error : undefined);
-        }
-    }
-    /**
-     * Register a tool in the registry for later reference by ID
-     * Can accept a tool instance
-     */
-    register(tool) {
-        try {
-            if (!tool) {
-                throw new ToolCreationError('[ToolCreationError] Tool registration failed: no tool provided. Pass a valid tool object with id and handler.', 'unknown');
-            }
-            if (!('handler' in tool) || typeof tool.handler !== 'function') {
-                throw new ToolCreationError(`[ToolCreationError] Invalid tool for registration: tool "${tool?.id || 'unknown'}" must have a handler function. Add a handler property.`, tool?.id || 'unknown');
-            }
-            // Validate the tool
-            if (!tool.id || typeof tool.id !== 'string' || tool.id.trim() === '') {
-                throw new ToolCreationError('[ToolCreationError] Tool ID missing: tool ID is required and must be a non-empty string. Provide a unique string id.', tool.id || 'unknown');
-            }
-            // Check for ID conflicts and provide better error context
-            if (this.toolRegistry.has(tool.id)) {
-                const existingTool = this.toolRegistry.get(tool.id);
-                logger.warn(`[ToolManager] Overwriting existing registered tool: ${tool.id} (previous: ${existingTool?.id || 'unnamed'})`);
-            }
-            this.toolRegistry.set(tool.id, tool);
-            logger.debug(`[ToolManager] Registered tool: ${tool.id} (${tool.id || 'unnamed'})`);
-            return tool;
-        }
-        catch (error) {
-            if (error instanceof ToolCreationError) {
-                throw error;
-            }
-            const toolId = tool?.id || 'unknown';
-            throw new ToolCreationError(`[ToolCreationError] Failed to register tool "${toolId}": ${error instanceof Error ? error.message : String(error)}. ` +
-                `Ensure the tool object is valid and has id + handler.`, toolId, error instanceof Error ? error : undefined);
-        }
-    }
-    /**
-     * Register multiple tools at once
-     */
-    registerMany(tools) {
-        return tools.map(tool => this.register(tool));
-    }
-    /**
-     * Get a registered tool by ID
-     */
-    getRegisteredTool(toolId) {
-        return this.toolRegistry.get(toolId);
-    }
-    /**
-     * Get all registered tools
-     */
-    getAllRegistered() {
-        return new Map(this.toolRegistry);
-    }
-    /**
-     * Check if a tool is registered
-     */
-    isRegistered(toolId) {
-        return this.toolRegistry.has(toolId);
-    }
-    /**
-     * Get all registered tool IDs
-     */
-    getRegisteredIds() {
-        return Array.from(this.toolRegistry.keys());
-    }
-    /**
-     * Get tool by ID from a specific scope
-     */
-    getFromScope(toolId, scope, step, flow) {
-        return this.find(toolId, scope, step, flow);
-    }
-    /**
-     * Check if a tool exists in any scope
-     */
-    exists(toolId, step, flow) {
-        return this.find(toolId, ToolScope.ALL, step, flow) !== undefined;
-    }
-    /**
-     * Get tool count by scope
-     */
-    getToolCount(scope, step, flow) {
-        return this.getAvailable(scope, step, flow).length;
-    }
-    /**
-     * Clear all registered tools
-     */
-    clearRegistry() {
-        this.toolRegistry.clear();
-        logger.debug('[ToolManager] Cleared tool registry');
-    }
-    /**
-     * Remove a tool from registry
-     */
-    unregister(toolId) {
-        const existed = this.toolRegistry.has(toolId);
-        this.toolRegistry.delete(toolId);
-        if (existed) {
-            logger.debug(`[ToolManager] Unregistered tool: ${toolId}`);
-        }
-        return existed;
-    }
-    /**
-     * Add a tool to the agent scope (creates and adds in one operation)
-     */
-    addToAgent(tool) {
-        // Validate tool before adding
-        if (!tool || !tool.id || !tool.handler) {
-            throw new ToolCreationError(`[ToolCreationError] Invalid tool for addToAgent: tool must have id and handler properties. ` +
-                `Provide a complete tool object with { id, handler, ... }.`, tool?.id || 'unknown');
-        }
-        // Add to agent's tools array using the unified interface
-        if (this.agent) {
-            this.agent.addTool(tool);
-        }
-        else {
-            logger.warn(`[ToolManager] No agent available, tool not added to agent scope: ${tool.id}`);
-        }
-        logger.debug(`[ToolManager] Added tool to agent scope: ${tool.id}`);
-        return tool;
-    }
-    /**
-     * Add a tool to a specific flow scope (creates and adds in one operation)
-     */
-    addToFlow(flow, tool) {
-        // Add to flow's tools array using the existing createTool method
-        if (flow && typeof flow.createTool === 'function') {
-            flow.createTool(tool);
-        }
-        else {
-            logger.warn(`[ToolManager] Flow does not support createTool method, tool not added to flow scope: ${tool.id}`);
-        }
-        logger.debug(`[ToolManager] Added tool to flow scope: ${tool.id}`);
-        return tool;
-    }
-    /**
-     * 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, scope, step, flow) {
-        logger.debug(`[ToolManager] Finding tool: ${toolId} with scope: ${scope || 'ALL'}`);
-        // Check transient tools first (highest priority — per-turn injectTools)
-        if (!scope || scope === ToolScope.ALL) {
-            const transientTool = this.transientTools.get(toolId);
-            if (transientTool) {
-                logger.debug(`[ToolManager] Found tool in transient scope: ${toolId}`);
-                return transientTool;
-            }
-        }
-        // Check step-level tools (if step provided and scope allows)
-        if (step && (!scope || scope === ToolScope.STEP || scope === ToolScope.ALL)) {
-            if (step.tools) {
-                for (const toolRef of step.tools) {
-                    if (typeof toolRef !== 'string') {
-                        // Inline tool object - check both id and name
-                        if (toolRef.id === toolId) {
-                            logger.debug(`[ToolManager] Found tool in step scope: ${toolId}`);
-                            return toolRef;
-                        }
-                    }
-                    else {
-                        // String reference - check if it matches and resolve from registry
-                        if (toolRef === toolId) {
-                            const registeredTool = this.toolRegistry.get(toolId);
-                            if (registeredTool) {
-                                logger.debug(`[ToolManager] Found tool reference in step, resolved from registry: ${toolId}`);
-                                return registeredTool;
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        // Check flow-level tools (if route provided and scope allows)
-        if (flow && (!scope || scope === ToolScope.FLOW || scope === ToolScope.ALL)) {
-            if (flow.tools) {
-                const flowTool = flow.tools.find((t) => t.id === toolId);
-                if (flowTool) {
-                    logger.debug(`[ToolManager] Found tool in flow scope: ${toolId}`);
-                    return flowTool;
-                }
-            }
-        }
-        // Check agent-level tools (if scope allows)
-        if (!scope || scope === ToolScope.AGENT || scope === ToolScope.ALL) {
-            if (this.agent) {
-                const agentTools = this.agent.getTools();
-                const agentTool = agentTools.find((t) => t.id === toolId);
-                if (agentTool) {
-                    logger.debug(`[ToolManager] Found tool in agent scope: ${toolId}`);
-                    return agentTool;
-                }
-            }
-        }
-        // Check registry (if scope allows)
-        if (!scope || scope === ToolScope.REGISTERED || scope === ToolScope.ALL) {
-            const registeredTool = this.toolRegistry.get(toolId);
-            if (registeredTool) {
-                logger.debug(`[ToolManager] Found tool in registry: ${toolId}`);
-                return registeredTool;
-            }
-            // Also check by name in registry
-            for (const [id, tool] of Array.from(this.toolRegistry.entries())) {
-                if (tool.id === toolId) {
-                    logger.debug(`[ToolManager] Found tool in registry by name: ${toolId} (id: ${id})`);
-                    return tool;
-                }
-            }
-        }
-        logger.debug(`[ToolManager] Tool not found: ${toolId}`);
-        return 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, step, flow) {
-        const toolMap = new Map();
-        const resolvedTools = [];
-        logger.debug(`[ToolManager] Getting available tools with scope: ${scope || 'ALL'}`);
-        // Add registered tools first (lowest priority)
-        if (!scope || scope === ToolScope.REGISTERED || scope === ToolScope.ALL) {
-            for (const [id, tool] of Array.from(this.toolRegistry.entries())) {
-                toolMap.set(id, tool);
-            }
-            logger.debug(`[ToolManager] Added ${this.toolRegistry.size} registered tools`);
-        }
-        // Add agent-level tools (override registered tools with same ID)
-        if (!scope || scope === ToolScope.AGENT || scope === ToolScope.ALL) {
-            if (this.agent) {
-                const agentTools = this.agent.getTools();
-                for (const tool of agentTools) {
-                    toolMap.set(tool.id, tool);
-                }
-                logger.debug(`[ToolManager] Added ${agentTools.length} agent tools`);
-            }
-        }
-        // Add route-level tools (override agent and registered tools with same ID)
-        if (flow && (!scope || scope === ToolScope.FLOW || scope === ToolScope.ALL)) {
-            if (flow.tools) {
-                for (const tool of flow.tools) {
-                    toolMap.set(tool.id, tool);
-                }
-                logger.debug(`[ToolManager] Added ${flow.tools.length} flow.tools`);
-            }
-        }
-        // Add step-level tools (override flow/agent/registry with same ID)
-        if (step && (!scope || scope === ToolScope.STEP || scope === ToolScope.ALL)) {
-            if (step.tools) {
-                for (const toolRef of step.tools) {
-                    if (typeof toolRef !== 'string') {
-                        // Inline tool object - add directly
-                        toolMap.set(toolRef.id, toolRef);
-                        resolvedTools.push(toolRef);
-                    }
-                    else {
-                        // String reference - resolve from registry and add if found
-                        const registeredTool = this.toolRegistry.get(toolRef);
-                        if (registeredTool) {
-                            toolMap.set(registeredTool.id, registeredTool);
-                            resolvedTools.push(registeredTool);
-                        }
-                        else {
-                            logger.warn(`[ToolExecutionError] Step references unknown tool: "${toolRef}" is not registered. Skipping. Register the tool or remove the reference.`);
-                        }
-                    }
-                }
-                logger.debug(`[ToolManager] Added ${step.tools.length} step tools (${resolvedTools.length} resolved)`);
-            }
-        }
-        // Add transient tools (highest priority — override everything with same ID)
-        if (!scope || scope === ToolScope.ALL) {
-            if (this.transientTools.size > 0) {
-                for (const [id, tool] of this.transientTools) {
-                    toolMap.set(id, tool);
-                }
-                logger.debug(`[ToolManager] Added ${this.transientTools.size} transient tools`);
-            }
-        }
-        // Convert map to array, preserving priority order
-        const allTools = Array.from(toolMap.values());
-        // If we have step-specific tools, prioritize them in the ordering
-        // (but transient tools that override step tools via same ID are already in the map)
-        if (resolvedTools.length > 0) {
-            // Add resolved step tools first, then other tools not already included
-            const stepToolIds = new Set(resolvedTools.map(t => t.id));
-            const otherTools = allTools.filter(t => !stepToolIds.has(t.id));
-            // For step tools, use the map version (which may be overridden by transient)
-            const finalStepTools = resolvedTools.map(t => toolMap.get(t.id) || t);
-            return [...finalStepTools, ...otherTools];
-        }
-        logger.debug(`[ToolManager] Returning ${allTools.length} available tools`);
-        return allTools;
-    }
-    /**
-     * Execute a single tool with context and collected data.
-     */
-    async executeTool(params) {
-        const { tool, context, updateContext, updateData, history, data, toolArguments } = params;
-        const startTime = Date.now();
-        const executionTimeout = 30000; // 30 seconds default timeout
-        try {
-            // Validate tool before execution
-            if (!tool || !tool.handler || typeof tool.handler !== 'function') {
-                return {
-                    success: false,
-                    error: `Invalid tool: ${tool?.id || 'unknown'} - missing or invalid handler`,
-                    metadata: { toolId: tool?.id, executionTime: 0 }
-                };
-            }
-            // Build tool context with complete agent data
-            const collectedDirectives = [];
-            const toolContext = {
-                context,
-                updateContext,
-                updateData,
-                history,
-                data: data || {},
-                getField: (key) => {
-                    return data?.[key];
-                },
-                setField: async (key, value) => {
-                    const update = {};
-                    update[key] = value;
-                    await updateData(update);
-                },
-                hasField: (key) => {
-                    return data != null && key in data;
-                },
-                dispatch: (directive) => {
-                    collectedDirectives.push(directive);
-                }
-            };
-            logger.debug(`[ToolManager] Executing tool: ${tool.id} with args:`, toolArguments);
-            // Pre-execution gates (validateInput → checkPermissions). Shared with the
-            // streaming executor (StreamingToolExecutor) so authorization/validation
-            // behave identically on every transport. When a gate denies, the handler
-            // is NOT invoked.
-            const gateDenial = await evaluateToolGates(tool, toolArguments, toolContext, startTime);
-            if (gateDenial) {
-                return gateDenial;
-            }
-            // Execute tool with timeout protection. The timer is cleared when the
-            // race settles AND unref'd so a pending timer never delays process
-            // shutdown; a handler that loses the race keeps running detached (its
-            // result is discarded), which we surface in a warn.
-            let timeoutTimer;
-            const timeoutPromise = new Promise((_, reject) => {
-                timeoutTimer = setTimeout(() => reject(new Error(`Tool execution timeout after ${executionTimeout}ms`)), executionTimeout);
-                timeoutTimer.unref?.();
-            });
-            let result;
-            try {
-                // Attach a no-op catch to the losing handler promise so a post-timeout
-                // rejection can't surface as an unhandled rejection and crash the process.
-                const handlerPromise = Promise.resolve(tool.handler(toolContext, toolArguments));
-                handlerPromise.catch(() => undefined);
-                result = await Promise.race([handlerPromise, timeoutPromise]);
-            }
-            finally {
-                clearTimeout(timeoutTimer);
-            }
-            const executionTime = Date.now() - startTime;
-            logger.debug(`[ToolManager] Tool ${tool.id} completed in ${executionTime}ms`);
-            // Handle different result types. Only SEMANTIC markers identify a
-            // ToolResult — bare `{data}` / `{error}` shapes are indistinguishable
-            // from ordinary business payloads (e.g. upstream API envelopes) and are
-            // wrapped as raw results instead.
-            let toolResult;
-            if (isToolResultLike(result)) {
-                // It's already a ToolResult-like object
-                toolResult = result;
-            }
-            else {
-                // It's a raw result - wrap it
-                toolResult = {
-                    data: result,
-                    success: true
-                };
-            }
-            // Collect directives from the result — singular and plural forms both
-            // count, ordered identically to the concurrent executor.
-            collectedDirectives.push(...extractResultDirectives(toolResult));
-            // Apply data updates from tool result with validation
-            if (toolResult.dataUpdate) {
-                try {
-                    if (typeof toolResult.dataUpdate === 'object' && toolResult.dataUpdate !== null) {
-                        await updateData(toolResult.dataUpdate);
-                    }
-                    else {
-                        logger.warn(`[DataValidationError] Tool "${tool.id}" returned invalid dataUpdate: expected object, got ${typeof toolResult.dataUpdate}. Fix the tool handler to return a valid dataUpdate object.`);
-                    }
-                }
-                catch (updateError) {
-                    logger.error(`[ToolManager] Failed to apply data update from tool ${tool.id}:`, updateError);
-                    return {
-                        success: false,
-                        error: `Failed to apply data update: ${updateError instanceof Error ? updateError.message : String(updateError)}`,
-                        metadata: { toolId: tool.id, executionTime, updateError: updateError instanceof Error ? updateError.message : String(updateError) }
-                    };
-                }
-            }
-            // Apply context updates from tool result with validation
-            if (toolResult.contextUpdate) {
-                try {
-                    if (typeof toolResult.contextUpdate === 'object' && toolResult.contextUpdate !== null) {
-                        await updateContext(toolResult.contextUpdate);
-                    }
-                    else {
-                        logger.warn(`[DataValidationError] Tool "${tool.id}" returned invalid contextUpdate: expected object, got ${typeof toolResult.contextUpdate}. Fix the tool handler to return a valid contextUpdate object.`);
-                    }
-                }
-                catch (updateError) {
-                    logger.error(`[ToolManager] Failed to apply context update from tool ${tool.id}:`, updateError);
-                    return {
-                        success: false,
-                        error: `Failed to apply context update: ${updateError instanceof Error ? updateError.message : String(updateError)}`,
-                        metadata: { toolId: tool.id, executionTime, updateError: updateError instanceof Error ? updateError.message : String(updateError) }
-                    };
-                }
-            }
-            // Return execution result with metadata
-            return {
-                success: toolResult.success !== false, // Default to true unless explicitly false
-                data: toolResult.data,
-                contextUpdate: toolResult.contextUpdate,
-                dataUpdate: toolResult.dataUpdate,
-                error: toolResult.error,
-                directives: collectedDirectives.length > 0 ? collectedDirectives : undefined,
-                metadata: {
-                    toolId: tool.id,
-                    toolName: tool.id,
-                    executionTime,
-                    ...(toolResult.meta || {})
-                }
-            };
-        }
-        catch (error) {
-            const executionTime = Date.now() - startTime;
-            logger.error(`[ToolManager] Tool execution error for ${tool.id} after ${executionTime}ms:`, error);
-            if (error instanceof Error && error.message.includes("Tool execution timeout")) {
-                // The losing handler may still be running with captured callbacks.
-                // Its writes are NOT rolled back here — tools should stay idempotent
-                // or accept their own cancellation via interruptBehavior/abort.
-                logger.warn(`[ToolManager] Handler for "${tool.id}" exceeded ${executionTimeout}ms and was abandoned while still running. ` +
-                    `Its eventual side effects are not cancelled or rolled back.`);
-            }
-            // Re-throw the error so callers can handle it
-            throw error;
-        }
-    }
-    /**
-     * 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.
-     */
-    async *executeWithConcurrency(params) {
-        const { toolCalls, context, data, history, signal, flow, step } = params;
-        if (toolCalls.length === 0) {
-            return;
-        }
-        // Build a ToolContext for the executor
-        const toolContext = {
-            context,
-            data: data || {},
-            history: history || [],
-            step: step ? { id: step.id, flowId: flow?.id || '' } : undefined,
-            updateContext: (updates) => {
-                Object.assign(context, updates);
-                return Promise.resolve();
-            },
-            updateData: (updates) => {
-                if (data) {
-                    Object.assign(data, updates);
-                }
-                return Promise.resolve();
-            },
-            getField: (key) => {
-                return data?.[key];
-            },
-            setField: (key, value) => {
-                if (data) {
-                    data[key] = value;
-                }
-                return Promise.resolve();
-            },
-            hasField: (key) => {
-                return data != null && key in data;
-            },
-            dispatch: (_directive) => {
-                // Handlers never see THIS context — StreamingToolExecutor.executeTool
-                // wraps each call in a per-call context whose dispatch attributes the
-                // directive to that tool. Reaching here means a gate or future caller
-                // dispatched outside a tool execution; surface it instead of dropping.
-                logger.warn("[ToolManager] ctx.dispatch called outside tool execution has no turn to attach to; directive dropped.");
-            },
-        };
-        const executor = new StreamingToolExecutor(toolContext, {
-            signal,
-        });
-        // Resolve and queue each tool call
-        for (const toolCall of toolCalls) {
-            const tool = this.find(toolCall.toolName, undefined, step, flow);
-            if (!tool) {
-                logger.warn(`[ToolExecutionError] Tool not found for concurrent execution: "${toolCall.toolName}" is not registered in any scope. Skipping. Register the tool or check the tool name.`);
-                continue;
-            }
-            // Tool carries all metadata fields directly — no cast needed
-            executor.addTool(toolCall, tool);
-        }
-        // Yield all results in order
-        yield* executor.getRemainingResults();
-    }
-    /**
-     * Create a data enrichment tool that modifies collected data
-     * Returns a tool instance that can be registered or added to scope
-     */
-    createDataEnrichment(config) {
-        // Validate configuration first
-        this.validateDataEnrichmentConfig(config);
-        const tool = {
-            id: config.id,
-            description: config.description || `Enriches data fields: ${config.fields.join(', ')}`,
-            parameters: {
-                type: 'object',
-                properties: {
-                    fields: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: `Fields to enrich: ${config.fields.join(', ')}`
-                    }
-                }
-            },
-            handler: async (context) => {
-                try {
-                    // Extract the specified fields from current data
-                    const fieldData = {};
-                    for (const field of config.fields) {
-                        if (context.hasField(field)) {
-                            const value = context.getField(field);
-                            if (value !== undefined) {
-                                fieldData[field] = value;
-                            }
-                        }
-                    }
-                    // Call the enricher function
-                    const enrichedData = await config.enricher(context.context, fieldData);
-                    // Update the data with enriched values
-                    if (enrichedData && typeof enrichedData === 'object') {
-                        await context.updateData(enrichedData);
-                    }
-                    logger.debug(`[ToolManager] Data enrichment completed for tool: ${config.id}`);
-                    return {
-                        success: true,
-                        dataUpdate: enrichedData
-                    };
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.error(`[ToolManager] Data enrichment failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`[ToolExecutionError] Data enrichment failed for tool "${config.id}": ${errorMessage}. ` +
-                        `Check the enrichment handler and field references.`, config.id, { fields: config.fields }, error instanceof Error ? error : undefined);
-                }
-            }
-        };
-        return tool;
-    }
-    /**
-     * Create a validation tool that validates data fields
-     * Returns a tool instance that can be registered or added to scope
-     */
-    createValidation(config) {
-        // Validate configuration first
-        this.validateValidationConfig(config);
-        const tool = {
-            id: config.id,
-            description: config.description || `Validates data fields: ${config.fields.join(', ')}`,
-            parameters: {
-                type: 'object',
-                properties: {
-                    fields: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: `Fields to validate: ${config.fields.join(', ')}`
-                    }
-                }
-            },
-            handler: async (context) => {
-                try {
-                    // Extract the specified fields from current data
-                    const fieldData = {};
-                    for (const field of config.fields) {
-                        if (context.hasField(field)) {
-                            const value = context.getField(field);
-                            if (value !== undefined) {
-                                fieldData[field] = value;
-                            }
-                        }
-                    }
-                    // Call the validator function
-                    const result = await config.validator(context.context, fieldData);
-                    logger.debug(`[ToolManager] Validation completed for tool: ${config.id}, valid: ${result.valid}`);
-                    return result;
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.error(`[ToolManager] Validation failed for ${config.id}: ${errorMessage}`);
-                    // Return validation failure result instead of throwing
-                    return {
-                        valid: false,
-                        errors: [{
-                                field: 'validation',
-                                message: `Validation error: ${errorMessage}`,
-                                value: undefined,
-                                schemaPath: config.id
-                            }],
-                        warnings: []
-                    };
-                }
-            }
-        };
-        return tool;
-    }
-    /**
-     * Create an API call tool that makes external HTTP requests
-     * Returns a tool instance that can be registered or added to scope
-     */
-    createApiCall(config) {
-        // Validate configuration first
-        this.validateApiCallConfig(config);
-        const tool = {
-            id: config.id,
-            description: config.description || `Makes API call to external service`,
-            parameters: {
-                type: 'object',
-                properties: {
-                    endpoint: {
-                        type: 'string',
-                        description: 'API endpoint URL'
-                    },
-                    method: {
-                        type: 'string',
-                        enum: ['GET', 'POST', 'PUT', 'DELETE'],
-                        description: 'HTTP method'
-                    }
-                }
-            },
-            handler: async (context, args) => {
-                try {
-                    // Resolve endpoint URL
-                    const endpoint = typeof config.endpoint === 'function'
-                        ? config.endpoint(context.context, context.data)
-                        : config.endpoint;
-                    // Resolve headers
-                    const headers = typeof config.headers === 'function'
-                        ? config.headers(context.context)
-                        : config.headers || {};
-                    // Prepare request options
-                    const requestOptions = {
-                        method: config.method || 'GET',
-                        headers: {
-                            'Content-Type': 'application/json',
-                            ...headers
-                        }
-                    };
-                    // Add body for non-GET requests
-                    if (config.body && (config.method === 'POST' || config.method === 'PUT')) {
-                        const bodyData = config.body(context.context, context.data, args);
-                        requestOptions.body = JSON.stringify(bodyData);
-                    }
-                    // Make the API call
-                    const response = await fetch(endpoint, requestOptions);
-                    if (!response.ok) {
-                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-                    }
-                    // Parse response
-                    let responseData;
-                    const contentType = response.headers.get('content-type');
-                    if (contentType && contentType.includes('application/json')) {
-                        responseData = await response.json();
-                    }
-                    else {
-                        responseData = await response.text();
-                    }
-                    // Transform response if transformer provided
-                    const result = config.transform ? config.transform(responseData) : responseData;
-                    logger.debug(`[ToolManager] API call completed for tool: ${config.id}`);
-                    return result;
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.error(`[ToolManager] API call failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`[ToolExecutionError] API call failed for tool "${config.id}": ${errorMessage}. ` +
-                        `Check the endpoint URL, method, and network connectivity.`, config.id, { endpoint: config.endpoint, method: config.method, args }, error instanceof Error ? error : undefined);
-                }
-            }
-        };
-        return tool;
-    }
-    /**
-     * Create a computation tool that performs calculations on input data
-     * Returns a tool instance that can be registered or added to scope
-     */
-    createComputation(config) {
-        // Validate configuration first
-        this.validateComputationConfig(config);
-        const tool = {
-            id: config.id,
-            description: config.description || `Performs computation on inputs: ${config.inputs.join(', ')}`,
-            parameters: {
-                type: 'object',
-                properties: {
-                    inputs: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: `Input fields: ${config.inputs.join(', ')}`
-                    }
-                }
-            },
-            handler: async (context, args) => {
-                try {
-                    // Extract the specified input fields from current data
-                    const inputData = {};
-                    for (const input of config.inputs) {
-                        if (context.hasField(input)) {
-                            const value = context.getField(input);
-                            if (value !== undefined) {
-                                inputData[input] = value;
-                            }
-                        }
-                    }
-                    // Call the compute function
-                    const result = await config.compute(context.context, inputData, args);
-                    logger.debug(`[ToolManager] Computation completed for tool: ${config.id}`);
-                    return result;
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.error(`[ToolManager] Computation failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`[ToolExecutionError] Computation failed for tool "${config.id}": ${errorMessage}. ` +
-                        `Check the compute function and input field references.`, config.id, { inputs: config.inputs, args }, error instanceof Error ? error : undefined);
-                }
-            }
-        };
-        return tool;
-    }
-    /**
-     * Get detailed information about a tool for debugging
-     */
-    getToolInfo(toolId, scope, step, flow) {
-        const tool = this.find(toolId, scope, step, flow);
-        if (!tool) {
-            return { found: false };
-        }
-        // Determine which scope the tool was found in
-        let foundScope = 'unknown';
-        // Check step scope
-        if (step?.tools) {
-            const stepTool = step.tools.find((t) => (typeof t === 'string' && t === toolId) ||
-                (typeof t === 'object' && (t.id === toolId)));
-            if (stepTool)
-                foundScope = 'step';
-        }
-        // Check route scope
-        if (foundScope === 'unknown' && flow?.tools) {
-            const flowTool = flow.tools.find((t) => t.id === toolId);
-            if (flowTool)
-                foundScope = 'flow';
-        }
-        // Check agent scope
-        if (foundScope === 'unknown' && this.agent) {
-            const agentTools = this.agent.tools;
-            const agentTool = agentTools.find((t) => t.id === toolId);
-            if (agentTool)
-                foundScope = 'agent';
-        }
-        // Check registry
-        if (foundScope === 'unknown' && this.toolRegistry.has(toolId)) {
-            foundScope = 'registry';
-        }
-        return {
-            found: true,
-            tool,
-            scope: foundScope,
-            metadata: {
-                id: tool.id,
-                hasDescription: !!tool.description,
-                hasParameters: !!tool.parameters,
-                handlerLength: tool.handler.length
-            }
-        };
-    }
-    /**
-     * Validate that all tools in a list exist and are accessible
-     */
-    validateToolReferences(toolIds, step, flow) {
-        const missing = [];
-        const found = [];
-        const details = [];
-        for (const toolId of toolIds) {
-            const info = this.getToolInfo(toolId, ToolScope.ALL, step, flow);
-            if (info.found) {
-                found.push(toolId);
-                details.push({ id: toolId, found: true, scope: info.scope });
-            }
-            else {
-                missing.push(toolId);
-                details.push({ id: toolId, found: false });
-            }
-        }
-        return {
-            valid: missing.length === 0,
-            missing,
-            found,
-            details
-        };
-    }
-    /**
-     * Get comprehensive statistics about the tool system
-     */
-    getStatistics() {
-        const registeredToolIds = Array.from(this.toolRegistry.keys());
-        const agentTools = this.agent ? this.agent.getTools() : [];
-        const agentToolIds = agentTools.map((t) => t.id);
-        // Find duplicate IDs between registry and agent
-        const duplicateIds = registeredToolIds.filter(id => agentToolIds.includes(id));
-        const allAvailable = this.getAvailable();
-        return {
-            registeredTools: this.toolRegistry.size,
-            agentTools: agentTools.length,
-            totalAvailable: allAvailable.length,
-            registeredToolIds,
-            duplicateIds
-        };
-    }
-    /**
-     * Perform health check on the tool system
-     */
-    healthCheck() {
-        const issues = [];
-        const warnings = [];
-        const stats = this.getStatistics();
-        // Check for duplicate tool IDs
-        if (stats.duplicateIds.length > 0) {
-            warnings.push(`Duplicate tool IDs found between registry and agent: ${stats.duplicateIds.join(', ')}`);
-        }
-        // Check for tools with missing handlers
-        for (const [id, tool] of Array.from(this.toolRegistry.entries())) {
-            if (!tool.handler || typeof tool.handler !== 'function') {
-                issues.push(`Tool '${id}' has invalid or missing handler`);
-            }
-            if (!tool.id || tool.id.trim() === '') {
-                issues.push(`Tool has empty or invalid ID: ${JSON.stringify(tool)}`);
-            }
-        }
-        // Check agent tools if available
-        if (this.agent) {
-            const agentTools = this.agent.getTools();
-            for (const tool of agentTools) {
-                if (!tool.handler || typeof tool.handler !== 'function') {
-                    issues.push(`Agent tool '${tool.id}' has invalid or missing handler`);
-                }
-            }
-        }
-        return {
-            healthy: issues.length === 0,
-            issues,
-            warnings,
-            statistics: stats
-        };
-    }
-}
-//# sourceMappingURL=ToolManager.js.map