@illuma-ai/agents 1.0.90 → 1.0.93

package/src/tools/ToolNode.js

@@ -0,0 +1,930 @@
+import { ToolMessage, isAIMessage, isBaseMessage, } from '@langchain/core/messages';
+import { END, Send, Command, isCommand, isGraphInterrupt, } from '@langchain/langgraph';
+import { RunnableCallable } from '@/utils';
+import { processToolOutput } from '@/utils/toonFormat';
+import { safeDispatchCustomEvent } from '@/utils/events';
+import { Constants, GraphEvents } from '@/common';
+/**
+ * Helper to check if a value is a Send object
+ */
+function isSend(value) {
+    return value instanceof Send;
+}
+/**
+ * Extract text content from a ToolMessage content field.
+ * Handles both string and MessageContentComplex[] formats.
+ * For array content (e.g., from content_and_artifact tools), extracts text from text blocks.
+ */
+function extractStringContent(content) {
+    // Already a string - return as is
+    if (typeof content === 'string') {
+        return content;
+    }
+    // Array of content blocks - extract text from each
+    if (Array.isArray(content)) {
+        const textParts = [];
+        for (const block of content) {
+            if (typeof block === 'string') {
+                textParts.push(block);
+            }
+            else if (block != null && typeof block === 'object') {
+                // Handle {type: 'text', text: '...'} format
+                const obj = block;
+                if (obj.type === 'text' && typeof obj.text === 'string') {
+                    textParts.push(obj.text);
+                }
+                else if (typeof obj.text === 'string') {
+                    // Just has 'text' property
+                    textParts.push(obj.text);
+                }
+            }
+        }
+        if (textParts.length > 0) {
+            return textParts.join('\n');
+        }
+    }
+    // Fallback: stringify whatever it is
+    return JSON.stringify(content);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class ToolNode extends RunnableCallable {
+    toolMap;
+    loadRuntimeTools;
+    handleToolErrors = true;
+    trace = false;
+    toolCallStepIds;
+    errorHandler;
+    toolUsageCount;
+    /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
+    toolCallTurns = new Map();
+    /** Tool registry for filtering (lazy computation of programmatic maps) */
+    toolRegistry;
+    /** Cached programmatic tools (computed once on first PTC call) */
+    programmaticCache;
+    /** Reference to Graph's sessions map for automatic session injection */
+    sessions;
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    eventDrivenMode = false;
+    /** Agent ID for event-driven mode */
+    agentId;
+    /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
+    directToolNames;
+    /** HITL tool approval configuration */
+    toolApprovalConfig;
+    /** Buffer for recovering truncated tool call arguments from streaming data */
+    streamingToolCallBuffer;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, streamingToolCallBuffer, toolApprovalConfig, }) {
+        super({ name, tags, func: (input, config) => this.run(input, config) });
+        this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+        this.toolCallStepIds = toolCallStepIds;
+        this.handleToolErrors = handleToolErrors ?? this.handleToolErrors;
+        this.loadRuntimeTools = loadRuntimeTools;
+        this.errorHandler = errorHandler;
+        this.toolUsageCount = new Map();
+        this.toolRegistry = toolRegistry;
+        this.sessions = sessions;
+        this.eventDrivenMode = eventDrivenMode ?? false;
+        this.agentId = agentId;
+        this.directToolNames = directToolNames;
+        this.streamingToolCallBuffer = streamingToolCallBuffer;
+        this.toolApprovalConfig = toolApprovalConfig;
+    }
+    /**
+     * Returns cached programmatic tools, computing once on first access.
+     * Single iteration builds both toolMap and toolDefs simultaneously.
+     */
+    getProgrammaticTools() {
+        if (this.programmaticCache)
+            return this.programmaticCache;
+        const toolMap = new Map();
+        const toolDefs = [];
+        if (this.toolRegistry) {
+            for (const [name, toolDef] of this.toolRegistry) {
+                if ((toolDef.allowed_callers ?? ['direct']).includes('code_execution')) {
+                    toolDefs.push(toolDef);
+                    const tool = this.toolMap.get(name);
+                    if (tool)
+                        toolMap.set(name, tool);
+                }
+            }
+        }
+        this.programmaticCache = { toolMap, toolDefs };
+        return this.programmaticCache;
+    }
+    /**
+     * Returns a snapshot of the current tool usage counts.
+     * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
+     */
+    getToolUsageCounts() {
+        return new Map(this.toolUsageCount); // Return a copy
+    }
+    /**
+     * Evaluates whether a tool call requires human approval.
+     * Returns true if approval is needed, false otherwise.
+     * Does NOT perform the actual approval flow - that's handled by requestApproval().
+     */
+    requiresApproval(toolName, args) {
+        if (!this.toolApprovalConfig) {
+            return false;
+        }
+        const { defaultPolicy, overrides, executionContext } = this.toolApprovalConfig;
+        // Scheduled and browser extension executions bypass all approval checks
+        // Browser extension has no HITL UI — approval is handled by the extension's own UX
+        if (executionContext === 'scheduled' || executionContext === 'browser') {
+            return false;
+        }
+        // Determine the effective policy for this tool
+        const toolOverride = overrides?.[toolName];
+        const effectivePolicy = toolOverride ?? defaultPolicy ?? 'always';
+        // Evaluate whether approval is required
+        if (effectivePolicy === 'always') {
+            return true;
+        }
+        else if (effectivePolicy === 'never') {
+            return false;
+        }
+        else {
+            // Custom function - evaluate with tool name and args
+            return effectivePolicy(toolName, args);
+        }
+    }
+    /**
+     * Requests human approval for a tool call via event dispatch.
+     * Dispatches an ON_TOOL_APPROVAL_REQUIRED event and waits for the host
+     * to resolve the promise with an approval response.
+     *
+     * This uses the same pattern as ON_TOOL_EXECUTE: a promise-based event
+     * dispatch where the host calls resolve/reject when the human responds.
+     *
+     * @param call - The tool call requiring approval
+     * @param config - The runnable config for event dispatch
+     * @returns The approval response from the human
+     */
+    async requestApproval(call, config) {
+        const approvalRequest = {
+            type: 'tool_approval_required',
+            toolCallId: call.id ?? '',
+            toolName: call.name,
+            toolArgs: call.args,
+            agentId: this.agentId,
+            description: `Tool "${call.name}" wants to execute with the provided arguments.`,
+        };
+        return new Promise((resolve, reject) => {
+            safeDispatchCustomEvent(GraphEvents.ON_TOOL_APPROVAL_REQUIRED, {
+                ...approvalRequest,
+                resolve,
+                reject,
+            }, config);
+        });
+    }
+    /**
+     * Runs a single tool call with error handling
+     */
+    async runTool(call, config) {
+        const tool = this.toolMap.get(call.name);
+        try {
+            if (tool === undefined) {
+                throw new Error(`Tool "${call.name}" not found.`);
+            }
+            const turn = this.toolUsageCount.get(call.name) ?? 0;
+            this.toolUsageCount.set(call.name, turn + 1);
+            if (call.id != null && call.id !== '') {
+                this.toolCallTurns.set(call.id, turn);
+            }
+            let args = call.args;
+            const stepId = this.toolCallStepIds?.get(call.id);
+            // Recover truncated tool call arguments from the streaming buffer.
+            // When max_tokens truncates a tool call mid-JSON, parsePartialJson may lose
+            // content that was already streamed to the UI. The buffer has the raw accumulated
+            // arg string, so we can extract field values that were dropped.
+            if (call.id && this.streamingToolCallBuffer?.has(call.id)) {
+                args = this.recoverTruncatedArgs(call.name, call.id, args);
+                this.streamingToolCallBuffer.clear(call.id);
+            }
+            // Build invoke params - LangChain extracts non-schema fields to config.toolCall
+            let invokeParams = {
+                ...call,
+                args,
+                type: 'tool_call',
+                stepId,
+                turn,
+            };
+            // Inject runtime data for special tools (becomes available at config.toolCall)
+            if (call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+                const { toolMap, toolDefs } = this.getProgrammaticTools();
+                invokeParams = {
+                    ...invokeParams,
+                    toolMap,
+                    toolDefs,
+                };
+            }
+            else if (call.name === Constants.TOOL_SEARCH) {
+                invokeParams = {
+                    ...invokeParams,
+                    toolRegistry: this.toolRegistry,
+                };
+            }
+            /**
+             * Inject session context for code execution tools when available.
+             * Each file uses its own session_id (supporting multi-session file tracking).
+             * Both session_id and _injected_files are injected directly to invokeParams
+             * (not inside args) so they bypass Zod schema validation and reach config.toolCall.
+             *
+             * session_id is always injected when available (even without tracked files)
+             * so the CodeExecutor can fall back to the /files endpoint for session continuity.
+             */
+            if (call.name === Constants.EXECUTE_CODE ||
+                call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+                const codeSession = this.sessions?.get(Constants.EXECUTE_CODE);
+                if (codeSession != null && codeSession.session_id !== '') {
+                    /**
+                     * Always inject session_id so retries reuse the same workspace.
+                     * Also inject file refs when files exist from previous executions.
+                     */
+                    invokeParams = {
+                        ...invokeParams,
+                        session_id: codeSession.session_id,
+                    };
+                    if (codeSession.files != null && codeSession.files.length > 0) {
+                        /**
+                         * Convert tracked files to CodeEnvFile format for the API.
+                         * Each file uses its own session_id (set when file was created).
+                         * This supports files from multiple parallel/sequential executions.
+                         */
+                        const fileRefs = codeSession.files.map((file) => ({
+                            session_id: file.session_id ?? codeSession.session_id,
+                            id: file.id,
+                            name: file.name,
+                        }));
+                        invokeParams = {
+                            ...invokeParams,
+                            _injected_files: fileRefs,
+                        };
+                    }
+                }
+            }
+            // ========================================================================
+            // HITL: Check if this tool requires human approval before execution.
+            // Uses event-driven pattern: dispatches ON_TOOL_APPROVAL_REQUIRED event
+            // and waits for the host to resolve/reject with a ToolApprovalResponse.
+            // ========================================================================
+            if (this.requiresApproval(call.name, call.args)) {
+                const approvalResponse = await this.requestApproval(call, config);
+                if (!approvalResponse.approved) {
+                    // Human denied the tool call - return a denial message
+                    return new ToolMessage({
+                        status: 'error',
+                        content: `Tool call "${call.name}" was denied by the user.${approvalResponse.feedback != null && approvalResponse.feedback !== '' ? ` Reason: ${approvalResponse.feedback}` : ''} Please acknowledge the denial and proceed without executing this tool.`,
+                        name: call.name,
+                        tool_call_id: call.id ?? '',
+                    });
+                }
+                // Human approved - optionally use modified args
+                if (approvalResponse.modifiedArgs) {
+                    invokeParams = {
+                        ...invokeParams,
+                        args: approvalResponse.modifiedArgs,
+                    };
+                }
+            }
+            const output = await tool.invoke(invokeParams, config);
+            // Handle Command outputs directly
+            if (isCommand(output)) {
+                return output;
+            }
+            // ========================================================================
+            // TOOL OUTPUT PROCESSING - Single point for all tools (MCP and non-MCP)
+            // 1. Extract string content from any output format
+            // 2. Apply TOON conversion if content contains JSON
+            // 3. Apply truncation if still too large
+            // 4. Return ToolMessage with processed string content
+            // ========================================================================
+            // Step 1: Extract string content from the output
+            let rawContent;
+            if (isBaseMessage(output) && output._getType() === 'tool') {
+                const toolMsg = output;
+                rawContent = extractStringContent(toolMsg.content);
+            }
+            else {
+                rawContent = extractStringContent(output);
+            }
+            // Step 2 & 3: Apply TOON conversion and truncation
+            // Skip TOON for content_tool — its output is line-numbered source code.
+            // TOON corrupts embedded JSON in source files, causing edit (str_replace) failures
+            // because the agent sees TOON-transformed content but strReplace matches original.
+            const isContentTool = call.name === 'content_tool';
+            const processed = processToolOutput(rawContent, {
+                maxLength: 100000, // 100K char limit
+                enableToon: !isContentTool,
+                minSizeForToon: 1000,
+                minReductionPercent: 10, // Only apply TOON when clearly beneficial
+            });
+            // Step 4: Return ToolMessage with processed string content
+            if (isBaseMessage(output) && output._getType() === 'tool') {
+                const toolMsg = output;
+                return new ToolMessage({
+                    status: toolMsg.status,
+                    name: toolMsg.name,
+                    content: processed.content,
+                    tool_call_id: toolMsg.tool_call_id,
+                });
+            }
+            else {
+                return new ToolMessage({
+                    status: 'success',
+                    name: tool.name,
+                    content: processed.content,
+                    tool_call_id: call.id,
+                });
+            }
+        }
+        catch (_e) {
+            const e = _e;
+            if (!this.handleToolErrors) {
+                throw e;
+            }
+            if (isGraphInterrupt(e)) {
+                throw e;
+            }
+            if (this.errorHandler) {
+                try {
+                    await this.errorHandler({
+                        error: e,
+                        id: call.id,
+                        name: call.name,
+                        input: call.args,
+                    }, config.metadata);
+                }
+                catch (handlerError) {
+                    // eslint-disable-next-line no-console
+                    console.error('Error in errorHandler:', {
+                        toolName: call.name,
+                        toolCallId: call.id,
+                        toolArgs: call.args,
+                        stepId: this.toolCallStepIds?.get(call.id),
+                        turn: this.toolUsageCount.get(call.name),
+                        originalError: {
+                            message: e.message,
+                            stack: e.stack ?? undefined,
+                        },
+                        handlerError: handlerError instanceof Error
+                            ? {
+                                message: handlerError.message,
+                                stack: handlerError.stack ?? undefined,
+                            }
+                            : {
+                                message: String(handlerError),
+                                stack: undefined,
+                            },
+                    });
+                }
+            }
+            return new ToolMessage({
+                status: 'error',
+                content: `Error: ${e.message}\n Please fix your mistakes.`,
+                name: call.name,
+                tool_call_id: call.id ?? '',
+            });
+        }
+    }
+    /**
+     * Recover truncated tool call arguments using the raw streaming buffer.
+     *
+     * When parsePartialJson drops content (e.g., a large "content" field truncated
+     * at max_tokens), this method extracts the field value from the raw accumulated
+     * arg string and merges it back into the parsed args object.
+     *
+     * This is generic — it checks ALL string fields in the raw buffer, not just
+     * content_tool fields. Any tool with a truncated string value benefits.
+     */
+    /**
+     * Recover truncated tool call arguments using the raw streaming buffer.
+     *
+     * Strategy:
+     * 1. If args are completely empty → try parsePartialJson on the raw buffer
+     * 2. Otherwise → field-level recovery: extract missing fields from raw buffer
+     *
+     * @param toolName - Tool name (for logging)
+     * @param toolCallId - The tool call ID
+     * @param args - The parsed args (potentially incomplete from parsePartialJson)
+     * @returns The args with recovered fields merged in
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    recoverTruncatedArgs(toolName, toolCallId, args) {
+        if (!this.streamingToolCallBuffer)
+            return args;
+        const rawArgs = this.streamingToolCallBuffer.getRawArgs(toolCallId);
+        if (!rawArgs)
+            return args;
+        const rawLen = rawArgs.length;
+        // If args is completely empty (JSON parsing aborted before any key),
+        // attempt to parse the raw accumulated string
+        if (args == null || (typeof args === 'object' && Object.keys(args).length === 0)) {
+            try {
+                const { parsePartialJson } = require('@langchain/core/utils/json');
+                const recovered = parsePartialJson(rawArgs);
+                if (recovered != null && typeof recovered === 'object' && Object.keys(recovered).length > 0) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[TruncationRecovery] Tool=${toolName}, callId=${toolCallId}, rawBufferLen=${rawLen}, ` +
+                        `parsedFields=[], recoveredFields=[${Object.keys(recovered).join(',')}] (full parse)`);
+                    return recovered;
+                }
+            }
+            catch {
+                // parsePartialJson failed — fall through to field-level extraction
+            }
+        }
+        // Field-level recovery: extract missing fields from the raw buffer
+        const parsedArgs = typeof args === 'object' ? { ...args } : {};
+        const recoveredFields = [];
+        // Extract field names from the raw JSON string
+        const fieldPattern = /"([^"]+)"\s*:/g;
+        let match;
+        const rawFieldNames = [];
+        while ((match = fieldPattern.exec(rawArgs)) !== null) {
+            rawFieldNames.push(match[1]);
+        }
+        for (const fieldName of rawFieldNames) {
+            if (parsedArgs[fieldName] == null ||
+                parsedArgs[fieldName] === '' ||
+                parsedArgs[fieldName] === undefined) {
+                const rawValue = this.streamingToolCallBuffer.extractFieldValue(toolCallId, fieldName);
+                if (rawValue != null && rawValue !== '') {
+                    parsedArgs[fieldName] = rawValue;
+                    recoveredFields.push(fieldName);
+                }
+            }
+        }
+        if (recoveredFields.length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn(`[TruncationRecovery] Tool=${toolName}, callId=${toolCallId}, rawBufferLen=${rawLen}, ` +
+                `parsedFields=[${Object.keys(args ?? {}).join(',')}], recoveredFields=[${recoveredFields.join(',')}]`);
+        }
+        return parsedArgs;
+    }
+    /**
+     * Builds code session context for injection into event-driven tool calls.
+     * Mirrors the session injection logic in runTool() for direct execution.
+     */
+    getCodeSessionContext() {
+        if (!this.sessions) {
+            return undefined;
+        }
+        const codeSession = this.sessions.get(Constants.EXECUTE_CODE);
+        if (!codeSession) {
+            return undefined;
+        }
+        const context = {
+            session_id: codeSession.session_id,
+        };
+        if (codeSession.files && codeSession.files.length > 0) {
+            context.files = codeSession.files.map((file) => ({
+                session_id: file.session_id ?? codeSession.session_id,
+                id: file.id,
+                name: file.name,
+            }));
+        }
+        return context;
+    }
+    /**
+     * Extracts code execution session context from tool results and stores in Graph.sessions.
+     * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
+     */
+    storeCodeSessionFromResults(results, requests) {
+        if (!this.sessions) {
+            return;
+        }
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            if (result.status !== 'success' || result.artifact == null) {
+                continue;
+            }
+            const request = requests.find((r) => r.id === result.toolCallId);
+            if (request?.name !== Constants.EXECUTE_CODE &&
+                request?.name !== Constants.PROGRAMMATIC_TOOL_CALLING) {
+                continue;
+            }
+            const artifact = result.artifact;
+            if (artifact?.session_id == null || artifact.session_id === '') {
+                continue;
+            }
+            const newFiles = artifact.files ?? [];
+            const existingSession = this.sessions.get(Constants.EXECUTE_CODE);
+            const existingFiles = existingSession?.files ?? [];
+            if (newFiles.length > 0) {
+                const filesWithSession = newFiles.map((file) => ({
+                    ...file,
+                    session_id: artifact.session_id,
+                }));
+                const newFileNames = new Set(filesWithSession.map((f) => f.name));
+                const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
+                this.sessions.set(Constants.EXECUTE_CODE, {
+                    session_id: artifact.session_id,
+                    files: [...filteredExisting, ...filesWithSession],
+                    lastUpdated: Date.now(),
+                });
+            }
+            else {
+                this.sessions.set(Constants.EXECUTE_CODE, {
+                    session_id: artifact.session_id,
+                    files: existingFiles,
+                    lastUpdated: Date.now(),
+                });
+            }
+        }
+    }
+    /**
+     * Post-processes standard runTool outputs: dispatches ON_RUN_STEP_COMPLETED
+     * and stores code session context. Mirrors the completion handling in
+     * dispatchToolEvents for the event-driven path.
+     *
+     * By handling completions here in graph context (rather than in the
+     * stream consumer via ToolEndHandler), the race between the stream
+     * consumer and graph execution is eliminated.
+     */
+    handleRunToolCompletions(calls, outputs, config) {
+        for (let i = 0; i < calls.length; i++) {
+            const call = calls[i];
+            const output = outputs[i];
+            const turn = this.toolCallTurns.get(call.id) ?? 0;
+            if (isCommand(output)) {
+                continue;
+            }
+            const toolMessage = output;
+            const toolCallId = call.id ?? '';
+            // Skip error ToolMessages when errorHandler already dispatched ON_RUN_STEP_COMPLETED
+            // via handleToolCallErrorStatic. Without this check, errors would be double-dispatched.
+            if (toolMessage.status === 'error' && this.errorHandler != null) {
+                continue;
+            }
+            // Store code session context from tool results
+            if (this.sessions &&
+                (call.name === Constants.EXECUTE_CODE ||
+                    call.name === Constants.PROGRAMMATIC_TOOL_CALLING)) {
+                const artifact = toolMessage.artifact;
+                if (artifact?.session_id != null && artifact.session_id !== '') {
+                    const newFiles = artifact.files ?? [];
+                    const existingSession = this.sessions.get(Constants.EXECUTE_CODE);
+                    const existingFiles = existingSession?.files ?? [];
+                    if (newFiles.length > 0) {
+                        const filesWithSession = newFiles.map((file) => ({
+                            ...file,
+                            session_id: artifact.session_id,
+                        }));
+                        const newFileNames = new Set(filesWithSession.map((f) => f.name));
+                        const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
+                        this.sessions.set(Constants.EXECUTE_CODE, {
+                            session_id: artifact.session_id,
+                            files: [...filteredExisting, ...filesWithSession],
+                            lastUpdated: Date.now(),
+                        });
+                    }
+                    else {
+                        this.sessions.set(Constants.EXECUTE_CODE, {
+                            session_id: artifact.session_id,
+                            files: existingFiles,
+                            lastUpdated: Date.now(),
+                        });
+                    }
+                }
+            }
+            // Dispatch ON_RUN_STEP_COMPLETED via custom event (same path as dispatchToolEvents)
+            const stepId = this.toolCallStepIds?.get(toolCallId) ?? '';
+            if (!stepId) {
+                continue;
+            }
+            const contentString = typeof toolMessage.content === 'string'
+                ? toolMessage.content
+                : JSON.stringify(toolMessage.content);
+            const tool_call = {
+                args: typeof call.args === 'string'
+                    ? call.args
+                    : JSON.stringify(call.args ?? {}),
+                name: call.name,
+                id: toolCallId,
+                output: contentString,
+                progress: 1,
+            };
+            safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
+                result: {
+                    id: stepId,
+                    index: turn,
+                    type: 'tool_call',
+                    tool_call,
+                },
+            }, config);
+        }
+    }
+    /**
+     * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
+     * Core logic for event-driven execution, separated from output shaping.
+     */
+    async dispatchToolEvents(toolCalls, config) {
+        const requests = toolCalls.map((call) => {
+            const turn = this.toolUsageCount.get(call.name) ?? 0;
+            this.toolUsageCount.set(call.name, turn + 1);
+            // Recover truncated args from streaming buffer (same as runTool path)
+            let args = call.args;
+            if (call.id && this.streamingToolCallBuffer?.has(call.id)) {
+                args = this.recoverTruncatedArgs(call.name, call.id, args);
+                this.streamingToolCallBuffer.clear(call.id);
+            }
+            const request = {
+                id: call.id,
+                name: call.name,
+                args,
+                stepId: this.toolCallStepIds?.get(call.id),
+                turn,
+            };
+            if (call.name === Constants.EXECUTE_CODE ||
+                call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+                request.codeSessionContext = this.getCodeSessionContext();
+            }
+            return request;
+        });
+        const results = await new Promise((resolve, reject) => {
+            const request = {
+                toolCalls: requests,
+                userId: config.configurable?.user_id,
+                agentId: this.agentId,
+                configurable: config.configurable,
+                metadata: config.metadata,
+                resolve,
+                reject,
+            };
+            safeDispatchCustomEvent(GraphEvents.ON_TOOL_EXECUTE, request, config);
+        });
+        this.storeCodeSessionFromResults(results, requests);
+        return results.map((result) => {
+            const request = requests.find((r) => r.id === result.toolCallId);
+            const toolName = request?.name ?? 'unknown';
+            const stepId = this.toolCallStepIds?.get(result.toolCallId) ?? '';
+            if (!stepId) {
+                // eslint-disable-next-line no-console
+                console.warn(`[ToolNode] toolCallStepIds missing entry for toolCallId=${result.toolCallId} (tool=${toolName}). ` +
+                    'This indicates a race between the stream consumer and graph execution. ' +
+                    `Map size: ${this.toolCallStepIds?.size ?? 0}`);
+            }
+            let toolMessage;
+            let contentString;
+            if (result.status === 'error') {
+                contentString = `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`;
+                toolMessage = new ToolMessage({
+                    status: 'error',
+                    content: contentString,
+                    name: toolName,
+                    tool_call_id: result.toolCallId,
+                });
+            }
+            else {
+                contentString =
+                    typeof result.content === 'string'
+                        ? result.content
+                        : JSON.stringify(result.content);
+                toolMessage = new ToolMessage({
+                    status: 'success',
+                    name: toolName,
+                    content: contentString,
+                    artifact: result.artifact,
+                    tool_call_id: result.toolCallId,
+                });
+            }
+            const tool_call = {
+                args: typeof request?.args === 'string'
+                    ? request.args
+                    : JSON.stringify(request?.args ?? {}),
+                name: toolName,
+                id: result.toolCallId,
+                output: contentString,
+                progress: 1,
+            };
+            const runStepCompletedData = {
+                result: {
+                    id: stepId,
+                    index: request?.turn ?? 0,
+                    type: 'tool_call',
+                    tool_call,
+                },
+            };
+            safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, runStepCompletedData, config);
+            return toolMessage;
+        });
+    }
+    /**
+     * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+     * Used in event-driven mode where the host handles actual tool execution.
+     */
+    async executeViaEvent(toolCalls, config, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input) {
+        const outputs = await this.dispatchToolEvents(toolCalls, config);
+        return (Array.isArray(input) ? outputs : { messages: outputs });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async run(input, config) {
+        const _toolNodeStart = Date.now();
+        this.toolCallTurns.clear();
+        let outputs;
+        if (this.isSendInput(input)) {
+            const isDirectTool = this.directToolNames?.has(input.lg_tool_call.name);
+            if (this.eventDrivenMode && isDirectTool !== true) {
+                return this.executeViaEvent([input.lg_tool_call], config, input);
+            }
+            outputs = [await this.runTool(input.lg_tool_call, config)];
+            this.handleRunToolCompletions([input.lg_tool_call], outputs, config);
+        }
+        else {
+            let messages;
+            if (Array.isArray(input)) {
+                messages = input;
+            }
+            else if (this.isMessagesState(input)) {
+                messages = input.messages;
+            }
+            else {
+                throw new Error('ToolNode only accepts BaseMessage[] or { messages: BaseMessage[] } as input.');
+            }
+            const toolMessageIds = new Set(messages
+                .filter((msg) => msg._getType() === 'tool')
+                .map((msg) => msg.tool_call_id));
+            let aiMessage;
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const message = messages[i];
+                if (isAIMessage(message)) {
+                    aiMessage = message;
+                    break;
+                }
+            }
+            if (aiMessage == null || !isAIMessage(aiMessage)) {
+                throw new Error('ToolNode only accepts AIMessages as input.');
+            }
+            if (this.loadRuntimeTools) {
+                const { tools, toolMap } = this.loadRuntimeTools(aiMessage.tool_calls ?? []);
+                this.toolMap =
+                    toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+                this.programmaticCache = undefined; // Invalidate cache on toolMap change
+            }
+            const filteredCalls = aiMessage.tool_calls?.filter((call) => {
+                /**
+                 * Filter out:
+                 * 1. Already processed tool calls (present in toolMessageIds)
+                 * 2. Server tool calls (e.g., web_search with IDs starting with 'srvtoolu_')
+                 *    which are executed by the provider's API and don't require invocation
+                 */
+                return ((call.id == null || !toolMessageIds.has(call.id)) &&
+                    !(call.id?.startsWith('srvtoolu_') ?? false));
+            }) ?? [];
+            if (this.eventDrivenMode && filteredCalls.length > 0) {
+                if (!this.directToolNames || this.directToolNames.size === 0) {
+                    return this.executeViaEvent(filteredCalls, config, input);
+                }
+                const directCalls = filteredCalls.filter((c) => this.directToolNames.has(c.name));
+                const eventCalls = filteredCalls.filter((c) => !this.directToolNames.has(c.name));
+                const directOutputs = directCalls.length > 0
+                    ? await Promise.all(directCalls.map((call) => this.runTool(call, config)))
+                    : [];
+                if (directCalls.length > 0 && directOutputs.length > 0) {
+                    this.handleRunToolCompletions(directCalls, directOutputs, config);
+                }
+                const eventOutputs = eventCalls.length > 0
+                    ? await this.dispatchToolEvents(eventCalls, config)
+                    : [];
+                outputs = [...directOutputs, ...eventOutputs];
+            }
+            else {
+                outputs = await Promise.all(filteredCalls.map((call) => this.runTool(call, config)));
+                this.handleRunToolCompletions(filteredCalls, outputs, config);
+            }
+        }
+        console.info(`[TIMING] ToolNode.run total: ${Date.now() - _toolNodeStart}ms`);
+        if (!outputs.some(isCommand)) {
+            return (Array.isArray(input) ? outputs : { messages: outputs });
+        }
+        const combinedOutputs = [];
+        let parentCommand = null;
+        /**
+         * Collect handoff commands (Commands with string goto and Command.PARENT)
+         * for potential parallel handoff aggregation
+         */
+        const handoffCommands = [];
+        const nonCommandOutputs = [];
+        for (const output of outputs) {
+            if (isCommand(output)) {
+                if (output.graph === Command.PARENT &&
+                    Array.isArray(output.goto) &&
+                    output.goto.every((send) => isSend(send))) {
+                    /** Aggregate Send-based commands */
+                    if (parentCommand) {
+                        parentCommand.goto.push(...output.goto);
+                    }
+                    else {
+                        parentCommand = new Command({
+                            graph: Command.PARENT,
+                            goto: output.goto,
+                        });
+                    }
+                }
+                else if (output.graph === Command.PARENT) {
+                    /**
+                     * Handoff Command with destination.
+                     * Handle both string ('agent') and array (['agent']) formats.
+                     * Collect for potential parallel aggregation.
+                     */
+                    const goto = output.goto;
+                    const isSingleStringDest = typeof goto === 'string';
+                    const isSingleArrayDest = Array.isArray(goto) &&
+                        goto.length === 1 &&
+                        typeof goto[0] === 'string';
+                    if (isSingleStringDest || isSingleArrayDest) {
+                        handoffCommands.push(output);
+                    }
+                    else {
+                        /** Multi-destination or other command - pass through */
+                        combinedOutputs.push(output);
+                    }
+                }
+                else {
+                    /** Other commands - pass through */
+                    combinedOutputs.push(output);
+                }
+            }
+            else {
+                nonCommandOutputs.push(output);
+                combinedOutputs.push(Array.isArray(input) ? [output] : { messages: [output] });
+            }
+        }
+        /**
+         * Handle handoff commands - convert to Send objects for parallel execution
+         * when multiple handoffs are requested
+         */
+        if (handoffCommands.length > 1) {
+            /**
+             * Multiple parallel handoffs - convert to Send objects.
+             * Each Send carries its own state with the appropriate messages.
+             * This enables LLM-initiated parallel execution when calling multiple
+             * transfer tools simultaneously.
+             */
+            /** Collect all destinations for sibling tracking */
+            const allDestinations = handoffCommands.map((cmd) => {
+                const goto = cmd.goto;
+                return typeof goto === 'string' ? goto : goto[0];
+            });
+            const sends = handoffCommands.map((cmd, idx) => {
+                const destination = allDestinations[idx];
+                /** Get siblings (other destinations, not this one) */
+                const siblings = allDestinations.filter((d) => d !== destination);
+                /** Add siblings to ToolMessage additional_kwargs */
+                const update = cmd.update;
+                if (update && update.messages) {
+                    for (const msg of update.messages) {
+                        if (msg.getType() === 'tool') {
+                            msg.additional_kwargs.handoff_parallel_siblings =
+                                siblings;
+                        }
+                    }
+                }
+                return new Send(destination, cmd.update);
+            });
+            const parallelCommand = new Command({
+                graph: Command.PARENT,
+                goto: sends,
+            });
+            combinedOutputs.push(parallelCommand);
+        }
+        else if (handoffCommands.length === 1) {
+            /** Single handoff - pass through as-is */
+            combinedOutputs.push(handoffCommands[0]);
+        }
+        if (parentCommand) {
+            combinedOutputs.push(parentCommand);
+        }
+        return combinedOutputs;
+    }
+    isSendInput(input) {
+        return (typeof input === 'object' && input != null && 'lg_tool_call' in input);
+    }
+    isMessagesState(input) {
+        return (typeof input === 'object' &&
+            input != null &&
+            'messages' in input &&
+            Array.isArray(input.messages) &&
+            input.messages.every(isBaseMessage));
+    }
+}
+function areToolCallsInvoked(message, invokedToolIds) {
+    if (!invokedToolIds || invokedToolIds.size === 0)
+        return false;
+    return (message.tool_calls?.every((toolCall) => toolCall.id != null && invokedToolIds.has(toolCall.id)) ?? false);
+}
+export function toolsCondition(state, toolNode, invokedToolIds) {
+    const messages = Array.isArray(state) ? state : state.messages;
+    const message = messages[messages.length - 1];
+    if (message &&
+        'tool_calls' in message &&
+        (message.tool_calls?.length ?? 0) > 0 &&
+        !areToolCallsInvoked(message, invokedToolIds)) {
+        return toolNode;
+    }
+    return END;
+}
+//# sourceMappingURL=ToolNode.js.map