@librechat/agents 3.1.86 → 3.1.88

package/dist/esm/tools/ToolNode.mjs

@@ -2,17 +2,15 @@ import { isBaseMessage, ToolMessage, HumanMessage, isAIMessage } from '@langchai
 import { isCommand, isGraphInterrupt, interrupt, Command, Send, END } from '@langchain/langgraph';
 import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
 import { Constants, CODE_EXECUTION_TOOLS, GraphEvents } from '../common/enum.mjs';
-import 'nanoid';
-import '../messages/core.mjs';
-import { calculateMaxToolResultChars, truncateToolResultContent } from '../utils/truncation.mjs';
-import { toLangChainContent } from '../messages/langchain.mjs';
-import { safeDispatchCustomEvent } from '../utils/events.mjs';
-import 'uuid';
+import '../stream.mjs';
 import { RunnableCallable } from '../utils/run.mjs';
 import 'ai-tokenizer';
 import 'zod-to-json-schema';
+import { calculateMaxToolResultChars, truncateToolResultContent } from '../utils/truncation.mjs';
+import { safeDispatchCustomEvent } from '../utils/events.mjs';
 import { executeHooks } from '../hooks/executeHooks.mjs';
 import '../hooks/createWorkspacePolicyHook.mjs';
+import { toLangChainContent } from '../messages/langchain.mjs';
 import { ToolOutputReferenceRegistry, buildReferenceKey } from './toolOutputReferences.mjs';
 import './local/CompileCheckTool.mjs';
 import 'path';
@@ -28,6 +26,7 @@ import './ProgrammaticToolCalling.mjs';
 import './BashProgrammaticToolCalling.mjs';
 import { resolveLocalToolRegistry, resolveLocalExecutionTools } from './local/resolveLocalExecutionTools.mjs';
 import './local/attachments.mjs';
+import { buildToolExecutionRequestPlan, recordArgsEqual } from './eagerEventExecution.mjs';
 
 /**
  * Helper to check if a value is a Send object
@@ -258,6 +257,12 @@ class ToolNode extends 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) */
@@ -301,7 +306,7 @@ class ToolNode extends 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, 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, 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;
@@ -315,6 +320,9 @@ class ToolNode extends 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 =
@@ -493,6 +501,18 @@ class ToolNode extends 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.
      *
@@ -1298,7 +1318,7 @@ class ToolNode extends 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];
@@ -1344,7 +1364,7 @@ class ToolNode extends RunnableCallable {
                 output: contentString,
                 progress: 1,
             };
-            safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
+            await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
                 result: {
                     id: stepId,
                     index: turn,
@@ -1513,9 +1533,9 @@ class ToolNode extends 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({
                             registry: hookRegistry,
@@ -1738,7 +1758,7 @@ class ToolNode extends 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') {
@@ -1804,7 +1824,7 @@ class ToolNode extends 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);
@@ -1812,50 +1832,92 @@ class ToolNode extends 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 = buildToolExecutionRequestPlan({
+                toolCalls: approvedEntries.map((entry) => {
+                    const codeSessionContext = CODE_EXECUTION_TOOLS.has(entry.call.name) ||
+                        entry.call.name === Constants.SKILL_TOOL ||
+                        entry.call.name === 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 (CODE_EXECUTION_TOOLS.has(entry.call.name) ||
-                    entry.call.name === Constants.SKILL_TOOL ||
-                    entry.call.name === 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,
-                };
-                safeDispatchCustomEvent(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 safeDispatchCustomEvent(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;
@@ -1994,7 +2056,7 @@ class ToolNode extends 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 ?? {},
@@ -2022,6 +2084,62 @@ class ToolNode extends 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 ||
+            !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`
@@ -2087,7 +2205,7 @@ class ToolNode extends 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
@@ -2095,7 +2213,7 @@ class ToolNode extends RunnableCallable {
                 'This indicates a race between the stream consumer and graph execution. ' +
                 `Map size: ${this.toolCallStepIds?.size ?? 0}`);
         }
-        safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
+        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
             result: {
                 id: stepId,
                 index: turn ?? this.toolUsageCount.get(toolName) ?? 0,
@@ -2214,7 +2332,7 @@ class ToolNode extends 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);
@@ -2338,7 +2456,7 @@ class ToolNode extends 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, {
@@ -2386,7 +2504,7 @@ class ToolNode extends 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 =