@librechat/agents 3.1.86 → 3.1.88

package/dist/cjs/tools/ToolNode.cjs

@@ -4,17 +4,15 @@ var messages = require('@langchain/core/messages');
 var langgraph = require('@langchain/langgraph');
 var singletons = require('@langchain/core/singletons');
 var _enum = require('../common/enum.cjs');
-require('nanoid');
-require('../messages/core.cjs');
-var truncation = require('../utils/truncation.cjs');
-var langchain = require('../messages/langchain.cjs');
-var events = require('../utils/events.cjs');
-require('uuid');
+require('../stream.cjs');
 var run = require('../utils/run.cjs');
 require('ai-tokenizer');
 require('zod-to-json-schema');
+var truncation = require('../utils/truncation.cjs');
+var events = require('../utils/events.cjs');
 var executeHooks = require('../hooks/executeHooks.cjs');
 require('../hooks/createWorkspacePolicyHook.cjs');
+var langchain = require('../messages/langchain.cjs');
 var toolOutputReferences = require('./toolOutputReferences.cjs');
 require('./local/CompileCheckTool.cjs');
 require('path');
@@ -30,6 +28,7 @@ require('./ProgrammaticToolCalling.cjs');
 require('./BashProgrammaticToolCalling.cjs');
 var resolveLocalExecutionTools = require('./local/resolveLocalExecutionTools.cjs');
 require('./local/attachments.cjs');
+var eagerEventExecution = require('./eagerEventExecution.cjs');
 
 /**
  * Helper to check if a value is a Send object
@@ -260,6 +259,12 @@ class ToolNode extends run.RunnableCallable {
     sessions;
     /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
     eventDrivenMode = false;
+    /** Opt-in stream-layer prestart config for event-driven tools. */
+    eagerEventToolExecution;
+    /** Shared per-run prestarted tool registry populated by ChatModelStreamHandler. */
+    eagerEventToolExecutions;
+    /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */
+    eagerEventToolUsageCount;
     /** Agent ID for event-driven mode */
     agentId;
     /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
@@ -303,7 +308,7 @@ class ToolNode extends run.RunnableCallable {
      * other's in-flight state.
      */
     anonBatchCounter = 0;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences: toolOutputReferences$1, toolOutputRegistry, toolExecution, fileCheckpointer, }) {
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences: toolOutputReferences$1, toolOutputRegistry, toolExecution, fileCheckpointer, }) {
         super({ name, tags, func: (input, config) => this.run(input, config) });
         this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
         this.toolCallStepIds = toolCallStepIds;
@@ -317,6 +322,9 @@ class ToolNode extends run.RunnableCallable {
         });
         this.sessions = sessions;
         this.eventDrivenMode = eventDrivenMode ?? false;
+        this.eagerEventToolExecution = eagerEventToolExecution;
+        this.eagerEventToolExecutions = eagerEventToolExecutions;
+        this.eagerEventToolUsageCount = eagerEventToolUsageCount;
         this.agentId = agentId;
         this.directToolNames = directToolNames;
         this.maxToolResultChars =
@@ -495,6 +503,18 @@ class ToolNode extends run.RunnableCallable {
     getToolUsageCounts() {
         return new Map(this.toolUsageCount); // Return a copy
     }
+    recordToolUsageTurn(toolName, turn, callId) {
+        this.toolUsageCount.set(toolName, Math.max(this.toolUsageCount.get(toolName) ?? 0, turn + 1));
+        if (callId != null && callId !== '') {
+            this.toolCallTurns.set(callId, turn);
+        }
+    }
+    recordEventToolPlanningTurn(toolName, turn, callId) {
+        this.recordToolUsageTurn(toolName, turn, callId);
+        if (this.canConsumeEagerEventExecution()) {
+            this.eagerEventToolUsageCount?.set(toolName, Math.max(this.eagerEventToolUsageCount.get(toolName) ?? 0, turn + 1));
+        }
+    }
     /**
      * Runs a single tool call with error handling.
      *
@@ -1300,7 +1320,7 @@ class ToolNode extends run.RunnableCallable {
      *   by `runTool`. Threaded as a local map (instead of instance state)
      *   so concurrent batches cannot read each other's entries.
      */
-    handleRunToolCompletions(calls, outputs, config, resolvedArgsByCallId) {
+    async handleRunToolCompletions(calls, outputs, config, resolvedArgsByCallId) {
         for (let i = 0; i < calls.length; i++) {
             const call = calls[i];
             const output = outputs[i];
@@ -1346,7 +1366,7 @@ class ToolNode extends run.RunnableCallable {
                 output: contentString,
                 progress: 1,
             };
-            events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_COMPLETED, {
+            await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_COMPLETED, {
                 result: {
                     id: stepId,
                     index: turn,
@@ -1515,9 +1535,9 @@ class ToolNode extends run.RunnableCallable {
                     reason,
                 });
             };
-            const flushDeferredBlockedSideEffects = () => {
+            const flushDeferredBlockedSideEffects = async () => {
                 for (const item of deferredBlockedSideEffects) {
-                    this.dispatchStepCompleted(item.callId, item.toolName, item.args, item.contentString, config);
+                    await this.dispatchStepCompleted(item.callId, item.toolName, item.args, item.contentString, config);
                     if (hookRegistry.hasHookFor('PermissionDenied', runId)) {
                         executeHooks.executeHooks({
                             registry: hookRegistry,
@@ -1740,7 +1760,7 @@ class ToolNode extends run.RunnableCallable {
                          * no risk of being rolled back by a subsequent throw, so
                          * no risk of a duplicate `ON_RUN_STEP_COMPLETED` event.
                          */
-                        this.dispatchStepCompleted(entry.call.id, entry.call.name, entry.args, truncatedResponse, config);
+                        await this.dispatchStepCompleted(entry.call.id, entry.call.name, entry.args, truncatedResponse, config);
                         continue;
                     }
                     if (decision.type === 'edit') {
@@ -1806,7 +1826,7 @@ class ToolNode extends run.RunnableCallable {
              * dispatches in the same relative position as the pre-deferral
              * code did (after hook processing, before tool execution).
              */
-            flushDeferredBlockedSideEffects();
+            await flushDeferredBlockedSideEffects();
         }
         else {
             approvedEntries.push(...preToolCalls);
@@ -1814,50 +1834,92 @@ class ToolNode extends run.RunnableCallable {
         const injected = [];
         const batchIndexByCallId = new Map();
         if (approvedEntries.length > 0) {
-            const requests = approvedEntries.map((entry) => {
-                const turn = this.toolUsageCount.get(entry.call.name) ?? 0;
-                this.toolUsageCount.set(entry.call.name, turn + 1);
+            const plan = eagerEventExecution.buildToolExecutionRequestPlan({
+                toolCalls: approvedEntries.map((entry) => {
+                    const codeSessionContext = _enum.CODE_EXECUTION_TOOLS.has(entry.call.name) ||
+                        entry.call.name === _enum.Constants.SKILL_TOOL ||
+                        entry.call.name === _enum.Constants.READ_FILE
+                        ? this.getCodeSessionContext()
+                        : undefined;
+                    return {
+                        id: entry.call.id,
+                        name: entry.call.name,
+                        args: entry.args,
+                        stepId: entry.stepId,
+                        codeSessionContext,
+                    };
+                }),
+                usageCount: this.toolUsageCount,
+                invalidArgsBehavior: 'error-result',
+                recordTurn: (toolName, reservedTurn, callId) => {
+                    this.recordEventToolPlanningTurn(toolName, reservedTurn, callId);
+                },
+            });
+            if (plan == null) {
+                throw new Error('Unable to build event tool execution request plan');
+            }
+            const requests = plan.requests;
+            for (const entry of approvedEntries) {
                 if (entry.batchIndex != null && entry.call.id != null) {
                     batchIndexByCallId.set(entry.call.id, entry.batchIndex);
                 }
-                const request = {
-                    id: entry.call.id,
-                    name: entry.call.name,
-                    args: entry.args,
-                    stepId: entry.stepId,
-                    turn,
-                };
-                /**
-                 * Emit `codeSessionContext` for any tool whose host handler may need
-                 * to reach into the code-execution sandbox:
-                 *   - `CODE_EXECUTION_TOOLS` — direct executors that POST to /exec.
-                 *   - `SKILL_TOOL` — skill files live alongside code-env state.
-                 *   - `READ_FILE` — when the requested path is a code-env artifact
-                 *     (e.g. `/mnt/data/...`) the host falls back to reading via the
-                 *     same sandbox session; without the seeded `session_id` /
-                 *     `_injected_files` here, that fallback can't see prior-turn
-                 *     artifacts on the very first call of a turn.
-                 */
-                if (_enum.CODE_EXECUTION_TOOLS.has(entry.call.name) ||
-                    entry.call.name === _enum.Constants.SKILL_TOOL ||
-                    entry.call.name === _enum.Constants.READ_FILE) {
-                    request.codeSessionContext = this.getCodeSessionContext();
+            }
+            for (const result of plan.rejectedResults) {
+                this.eagerEventToolExecutions?.delete(result.toolCallId);
+            }
+            const requestMap = new Map(plan.allRequests.map((r) => [r.id, r]));
+            const eagerExecutions = [];
+            const dispatchRequests = [];
+            for (const request of requests) {
+                const eagerExecution = this.takeMatchingEagerEventExecution(request);
+                if (eagerExecution != null) {
+                    eagerExecutions.push({ request, execution: eagerExecution });
                 }
-                return request;
-            });
-            const requestMap = new Map(requests.map((r) => [r.id, r]));
-            const results = await new Promise((resolve, reject) => {
-                const batchRequest = {
-                    toolCalls: requests,
-                    userId: config.configurable?.user_id,
-                    agentId: this.agentId,
-                    configurable: config.configurable,
-                    metadata: config.metadata,
-                    resolve,
-                    reject,
-                };
-                events.safeDispatchCustomEvent(_enum.GraphEvents.ON_TOOL_EXECUTE, batchRequest, config);
-            });
+                else {
+                    dispatchRequests.push(request);
+                }
+            }
+            const dispatchPromise = dispatchRequests.length === 0
+                ? Promise.resolve([])
+                : new Promise((resolve, reject) => {
+                    let dispatchSettled = false;
+                    let resultSettled = false;
+                    let settledResults;
+                    const maybeResolve = () => {
+                        if (dispatchSettled && resultSettled) {
+                            resolve(settledResults ?? []);
+                        }
+                    };
+                    const batchRequest = {
+                        toolCalls: dispatchRequests,
+                        userId: config.configurable?.user_id,
+                        agentId: this.agentId,
+                        configurable: config.configurable,
+                        metadata: config.metadata,
+                        resolve: (results) => {
+                            resultSettled = true;
+                            settledResults = results;
+                            maybeResolve();
+                        },
+                        reject,
+                    };
+                    void events.safeDispatchCustomEvent(_enum.GraphEvents.ON_TOOL_EXECUTE, batchRequest, config)
+                        .then(() => {
+                        dispatchSettled = true;
+                        maybeResolve();
+                    })
+                        .catch(reject);
+                });
+            const eagerResultsPromise = Promise.all(eagerExecutions.map(({ request, execution }) => this.resolveEagerEventExecution(request, execution))).then((results) => results.flat());
+            const [eagerResults, dispatchedResults] = await Promise.all([
+                eagerResultsPromise,
+                dispatchPromise,
+            ]);
+            const results = [
+                ...plan.rejectedResults,
+                ...eagerResults,
+                ...dispatchedResults,
+            ];
             this.storeCodeSessionFromResults(results, requestMap);
             const hasPostHook = this.hookRegistry?.hasHookFor('PostToolUse', runId) === true;
             const hasFailureHook = this.hookRegistry?.hasHookFor('PostToolUseFailure', runId) === true;
@@ -1996,7 +2058,7 @@ class ToolNode extends run.RunnableCallable {
                         }),
                     });
                 }
-                this.dispatchStepCompleted(result.toolCallId, toolName, request?.args ?? {}, contentString, config, request?.turn);
+                await this.dispatchStepCompleted(result.toolCallId, toolName, request?.args ?? {}, contentString, config, request?.turn);
                 postToolBatchEntryByCallId.set(result.toolCallId, {
                     toolName,
                     toolInput: request?.args ?? {},
@@ -2024,6 +2086,62 @@ class ToolNode extends run.RunnableCallable {
         });
         return { toolMessages, injected };
     }
+    canConsumeEagerEventExecution() {
+        return (this.eventDrivenMode &&
+            this.eagerEventToolExecution?.enabled === true &&
+            this.hookRegistry == null &&
+            this.humanInTheLoop?.enabled !== true &&
+            this.toolOutputRegistry == null);
+    }
+    takeMatchingEagerEventExecution(request) {
+        if (!this.canConsumeEagerEventExecution()) {
+            return undefined;
+        }
+        const execution = this.eagerEventToolExecutions?.get(request.id);
+        if (execution == null) {
+            return undefined;
+        }
+        this.eagerEventToolExecutions?.delete(request.id);
+        if (execution.toolName !== request.name ||
+            !eagerEventExecution.recordArgsEqual(execution.args, request.args) ||
+            execution.request.turn !== request.turn) {
+            return {
+                toolCallId: request.id,
+                toolName: request.name,
+                args: request.args,
+                request,
+                promise: Promise.resolve({
+                    results: [
+                        {
+                            toolCallId: request.id,
+                            status: 'error',
+                            content: '',
+                            errorMessage: 'Tool call changed after eager execution started; refusing to re-run the tool to avoid duplicate side effects.',
+                        },
+                    ],
+                }),
+            };
+        }
+        return execution;
+    }
+    async resolveEagerEventExecution(request, execution) {
+        const outcome = await execution.promise;
+        if (outcome.error != null) {
+            throw outcome.error;
+        }
+        const results = outcome.results.filter((result) => result.toolCallId === request.id);
+        if (results.length > 0) {
+            return results;
+        }
+        return [
+            {
+                toolCallId: request.id,
+                status: 'error',
+                content: '',
+                errorMessage: 'Tool execution completed without a result for this tool call',
+            },
+        ];
+    }
     /**
      * Fires the `PostToolBatch` hook (if registered) and appends the
      * accumulated batch-level `additionalContext` strings to `injected`
@@ -2089,7 +2207,7 @@ class ToolNode extends run.RunnableCallable {
             }));
         }
     }
-    dispatchStepCompleted(toolCallId, toolName, args, output, config, turn) {
+    async dispatchStepCompleted(toolCallId, toolName, args, output, config, turn) {
         const stepId = this.toolCallStepIds?.get(toolCallId) ?? '';
         if (!stepId) {
             // eslint-disable-next-line no-console
@@ -2097,7 +2215,7 @@ class ToolNode extends run.RunnableCallable {
                 'This indicates a race between the stream consumer and graph execution. ' +
                 `Map size: ${this.toolCallStepIds?.size ?? 0}`);
         }
-        events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_COMPLETED, {
+        await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_RUN_STEP_COMPLETED, {
             result: {
                 id: stepId,
                 index: turn ?? this.toolUsageCount.get(toolName) ?? 0,
@@ -2216,7 +2334,7 @@ class ToolNode extends run.RunnableCallable {
                         }),
                     ]
                     : [sendOutput];
-            this.handleRunToolCompletions([input.lg_tool_call], 
+            await this.handleRunToolCompletions([input.lg_tool_call], 
             // Pass only the tool output to completion handling; the
             // HumanMessage isn't a tool result.
             [sendOutput], config, resolvedArgsByCallId);
@@ -2340,7 +2458,7 @@ class ToolNode extends run.RunnableCallable {
                     })))
                     : [];
                 if (directCalls.length > 0 && directOutputs.length > 0) {
-                    this.handleRunToolCompletions(directCalls, directOutputs, config, resolvedArgsByCallId);
+                    await this.handleRunToolCompletions(directCalls, directOutputs, config, resolvedArgsByCallId);
                 }
                 const eventResult = eventCalls.length > 0
                     ? await this.dispatchToolEvents(eventCalls, config, {
@@ -2388,7 +2506,7 @@ class ToolNode extends run.RunnableCallable {
                     preBatchSnapshot,
                     additionalContextsSink: directAdditionalContexts,
                 })));
-                this.handleRunToolCompletions(filteredCalls, toolOutputs, config, resolvedArgsByCallId);
+                await this.handleRunToolCompletions(filteredCalls, toolOutputs, config, resolvedArgsByCallId);
                 // Append accumulated additionalContexts as a single
                 // HumanMessage so the next model turn sees them. Codex P2 #39.
                 outputs =