@librechat/agents 3.1.86 → 3.1.88

package/src/summarization/node.ts

@@ -1137,7 +1137,7 @@ function createSummarizationChunkHandler({
         ? [{ type: ContentTypes.TEXT, text: raw } as t.MessageContentComplex]
         : raw;
 
-    safeDispatchCustomEvent(
+    void safeDispatchCustomEvent(
       GraphEvents.ON_SUMMARIZE_DELTA,
       {
         id: stepId,

package/src/tools/ToolNode.ts

@@ -50,6 +50,10 @@ import {
   resolveLocalToolRegistry,
   resolveLocalExecutionTools,
 } from '@/tools/local';
+import {
+  buildToolExecutionRequestPlan,
+  recordArgsEqual,
+} from '@/tools/eagerEventExecution';
 
 /**
  * Per-call batch context for `runTool`. Bundles every optional
@@ -413,6 +417,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private sessions?: t.ToolSessionMap;
   /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
   private eventDrivenMode: boolean = false;
+  /** Opt-in stream-layer prestart config for event-driven tools. */
+  private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  /** Shared per-run prestarted tool registry populated by ChatModelStreamHandler. */
+  private eagerEventToolExecutions?: Map<string, t.EagerEventToolExecution>;
+  /** Shared per-run per-tool turn counter used by eager and normal event dispatch. */
+  private eagerEventToolUsageCount?: Map<string, number>;
   /** Agent ID for event-driven mode */
   private agentId?: string;
   /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
@@ -469,6 +479,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolRegistry,
     sessions,
     eventDrivenMode,
+    eagerEventToolExecution,
+    eagerEventToolExecutions,
+    eagerEventToolUsageCount,
     agentId,
     directToolNames,
     maxContextTokens,
@@ -493,6 +506,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     });
     this.sessions = sessions;
     this.eventDrivenMode = eventDrivenMode ?? false;
+    this.eagerEventToolExecution = eagerEventToolExecution;
+    this.eagerEventToolExecutions = eagerEventToolExecutions;
+    this.eagerEventToolUsageCount = eagerEventToolUsageCount;
     this.agentId = agentId;
     this.directToolNames = directToolNames;
     this.maxToolResultChars =
@@ -698,6 +714,34 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     return new Map(this.toolUsageCount); // Return a copy
   }
 
+  private recordToolUsageTurn(
+    toolName: string,
+    turn: number,
+    callId?: string
+  ): void {
+    this.toolUsageCount.set(
+      toolName,
+      Math.max(this.toolUsageCount.get(toolName) ?? 0, turn + 1)
+    );
+    if (callId != null && callId !== '') {
+      this.toolCallTurns.set(callId, turn);
+    }
+  }
+
+  private recordEventToolPlanningTurn(
+    toolName: string,
+    turn: number,
+    callId?: string
+  ): void {
+    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.
    *
@@ -1018,13 +1062,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             handlerError:
               handlerError instanceof Error
                 ? {
-                  message: handlerError.message,
-                  stack: handlerError.stack ?? undefined,
-                }
+                    message: handlerError.message,
+                    stack: handlerError.stack ?? undefined,
+                  }
                 : {
-                  message: String(handlerError),
-                  stack: undefined,
-                },
+                    message: String(handlerError),
+                    stack: undefined,
+                  },
           });
         }
       }
@@ -1032,11 +1076,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       const refMeta =
         unresolvedRefs.length > 0
           ? this.recordOutputReference(
-            runId,
-            errorContent,
-            undefined,
-            unresolvedRefs
-          )
+              runId,
+              errorContent,
+              undefined,
+              unresolvedRefs
+            )
           : undefined;
       return new ToolMessage({
         status: 'error',
@@ -1678,12 +1722,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    *   by `runTool`. Threaded as a local map (instead of instance state)
    *   so concurrent batches cannot read each other's entries.
    */
-  private handleRunToolCompletions(
+  private async handleRunToolCompletions(
     calls: ToolCall[],
     outputs: (BaseMessage | Command)[],
     config: RunnableConfig,
     resolvedArgsByCallId?: ResolvedArgsByCallId
-  ): void {
+  ): Promise<void> {
     for (let i = 0; i < calls.length; i++) {
       const call = calls[i];
       const output = outputs[i];
@@ -1741,7 +1785,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         progress: 1,
       };
 
-      safeDispatchCustomEvent(
+      await safeDispatchCustomEvent(
         GraphEvents.ON_RUN_STEP_COMPLETED,
         {
           result: {
@@ -1949,9 +1993,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         });
       };
 
-      const flushDeferredBlockedSideEffects = (): void => {
+      const flushDeferredBlockedSideEffects = async (): Promise<void> => {
         for (const item of deferredBlockedSideEffects) {
-          this.dispatchStepCompleted(
+          await this.dispatchStepCompleted(
             item.callId,
             item.toolName,
             item.args,
@@ -2236,7 +2280,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
              * no risk of being rolled back by a subsequent throw, so
              * no risk of a duplicate `ON_RUN_STEP_COMPLETED` event.
              */
-            this.dispatchStepCompleted(
+            await this.dispatchStepCompleted(
               entry.call.id!,
               entry.call.name,
               entry.args,
@@ -2321,7 +2365,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * 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);
     }
@@ -2331,67 +2375,118 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     const batchIndexByCallId = new Map<string, number>();
 
     if (approvedEntries.length > 0) {
-      const requests: t.ToolCallRequest[] = 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: t.ToolCallRequest = {
-          id: entry.call.id!,
-          name: entry.call.name,
-          args: entry.args,
-          stepId: entry.stepId,
-          turn,
-        };
+      for (const result of plan.rejectedResults) {
+        this.eagerEventToolExecutions?.delete(result.toolCallId);
+      }
 
-        /**
-         * 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();
+      const requestMap = new Map(plan.allRequests.map((r) => [r.id, r]));
+      const eagerExecutions: Array<{
+        request: t.ToolCallRequest;
+        execution: t.EagerEventToolExecution;
+      }> = [];
+      const dispatchRequests: t.ToolCallRequest[] = [];
+
+      for (const request of requests) {
+        const eagerExecution = this.takeMatchingEagerEventExecution(request);
+        if (eagerExecution != null) {
+          eagerExecutions.push({ request, execution: eagerExecution });
+        } else {
+          dispatchRequests.push(request);
         }
+      }
 
-        return request;
-      });
+      const dispatchPromise =
+        dispatchRequests.length === 0
+          ? Promise.resolve([] as t.ToolExecuteResult[])
+          : new Promise<t.ToolExecuteResult[]>((resolve, reject) => {
+              let dispatchSettled = false;
+              let resultSettled = false;
+              let settledResults: t.ToolExecuteResult[] | undefined;
+
+              const maybeResolve = (): void => {
+                if (dispatchSettled && resultSettled) {
+                  resolve(settledResults ?? []);
+                }
+              };
 
-      const requestMap = new Map(requests.map((r) => [r.id, r]));
+              const batchRequest: t.ToolExecuteBatchRequest = {
+                toolCalls: dispatchRequests,
+                userId: config.configurable?.user_id as string | undefined,
+                agentId: this.agentId,
+                configurable: config.configurable as
+                  | Record<string, unknown>
+                  | undefined,
+                metadata: config.metadata as
+                  | Record<string, unknown>
+                  | undefined,
+                resolve: (results): void => {
+                  resultSettled = true;
+                  settledResults = results;
+                  maybeResolve();
+                },
+                reject,
+              };
 
-      const results = await new Promise<t.ToolExecuteResult[]>(
-        (resolve, reject) => {
-          const batchRequest: t.ToolExecuteBatchRequest = {
-            toolCalls: requests,
-            userId: config.configurable?.user_id as string | undefined,
-            agentId: this.agentId,
-            configurable: config.configurable as
-              | Record<string, unknown>
-              | undefined,
-            metadata: config.metadata as Record<string, unknown> | undefined,
-            resolve,
-            reject,
-          };
+              void safeDispatchCustomEvent(
+                GraphEvents.ON_TOOL_EXECUTE,
+                batchRequest,
+                config
+              )
+                .then(() => {
+                  dispatchSettled = true;
+                  maybeResolve();
+                })
+                .catch(reject);
+            });
 
-          safeDispatchCustomEvent(
-            GraphEvents.ON_TOOL_EXECUTE,
-            batchRequest,
-            config
-          );
-        }
-      );
+      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);
 
@@ -2442,11 +2537,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           const errorRefMeta =
             unresolved.length > 0
               ? this.recordOutputReference(
-                registryRunId,
-                contentString,
-                undefined,
-                unresolved
-              )
+                  registryRunId,
+                  contentString,
+                  undefined,
+                  unresolved
+                )
               : undefined;
           toolMessage = new ToolMessage({
             status: 'error',
@@ -2565,7 +2660,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           });
         }
 
-        this.dispatchStepCompleted(
+        await this.dispatchStepCompleted(
           result.toolCallId,
           toolName,
           request?.args ?? {},
@@ -2606,6 +2701,84 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     return { toolMessages, injected };
   }
 
+  private canConsumeEagerEventExecution(): boolean {
+    return (
+      this.eventDrivenMode &&
+      this.eagerEventToolExecution?.enabled === true &&
+      this.hookRegistry == null &&
+      this.humanInTheLoop?.enabled !== true &&
+      this.toolOutputRegistry == null
+    );
+  }
+
+  private takeMatchingEagerEventExecution(
+    request: t.ToolCallRequest
+  ): t.EagerEventToolExecution | undefined {
+    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;
+  }
+
+  private async resolveEagerEventExecution(
+    request: t.ToolCallRequest,
+    execution: t.EagerEventToolExecution
+  ): Promise<t.ToolExecuteResult[]> {
+    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`
@@ -2692,14 +2865,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     }
   }
 
-  private dispatchStepCompleted(
+  private async dispatchStepCompleted(
     toolCallId: string,
     toolName: string,
     args: Record<string, unknown>,
     output: string,
     config: RunnableConfig,
     turn?: number
-  ): void {
+  ): Promise<void> {
     const stepId = this.toolCallStepIds?.get(toolCallId) ?? '';
     if (!stepId) {
       // eslint-disable-next-line no-console
@@ -2710,7 +2883,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       );
     }
 
-    safeDispatchCustomEvent(
+    await safeDispatchCustomEvent(
       GraphEvents.ON_RUN_STEP_COMPLETED,
       {
         result: {
@@ -2842,17 +3015,17 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       outputs =
         directAdditionalContexts.length > 0
           ? [
-            sendOutput,
-            new HumanMessage({
-              content: directAdditionalContexts.join('\n\n'),
-              // Match the event-driven path's marker so hosts /
-              // model-side annotators treat this as system intent
-              // rather than ordinary user text. Codex P2 [46].
-              additional_kwargs: { role: 'system', source: 'hook' },
-            }),
-          ]
+              sendOutput,
+              new HumanMessage({
+                content: directAdditionalContexts.join('\n\n'),
+                // Match the event-driven path's marker so hosts /
+                // model-side annotators treat this as system intent
+                // rather than ordinary user text. Codex P2 [46].
+                additional_kwargs: { role: 'system', source: 'hook' },
+              }),
+            ]
           : [sendOutput];
-      this.handleRunToolCompletions(
+      await this.handleRunToolCompletions(
         [input.lg_tool_call],
         // Pass only the tool output to completion handling; the
         // HumanMessage isn't a tool result.
@@ -3001,21 +3174,21 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const directOutputs: (BaseMessage | Command)[] =
           directCalls.length > 0
             ? await Promise.all(
-              directCalls.map((call, i) =>
-                this.runDirectToolWithLifecycleHooks(call, config, {
-                  batchIndex: directIndices[i],
-                  turn,
-                  batchScopeId,
-                  resolvedArgsByCallId,
-                  preBatchSnapshot,
-                  additionalContextsSink: directAdditionalContexts,
-                })
+                directCalls.map((call, i) =>
+                  this.runDirectToolWithLifecycleHooks(call, config, {
+                    batchIndex: directIndices[i],
+                    turn,
+                    batchScopeId,
+                    resolvedArgsByCallId,
+                    preBatchSnapshot,
+                    additionalContextsSink: directAdditionalContexts,
+                  })
+                )
               )
-            )
             : [];
 
         if (directCalls.length > 0 && directOutputs.length > 0) {
-          this.handleRunToolCompletions(
+          await this.handleRunToolCompletions(
             directCalls,
             directOutputs,
             config,
@@ -3026,29 +3199,29 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const eventResult =
           eventCalls.length > 0
             ? await this.dispatchToolEvents(eventCalls, config, {
-              batchIndices: eventIndices,
-              turn,
-              batchScopeId,
-              preResolvedArgs: preResolvedEventArgs,
-              preBatchSnapshot,
-            })
+                batchIndices: eventIndices,
+                turn,
+                batchScopeId,
+                preResolvedArgs: preResolvedEventArgs,
+                preBatchSnapshot,
+              })
             : {
-              toolMessages: [] as ToolMessage[],
-              injected: [] as BaseMessage[],
-            };
+                toolMessages: [] as ToolMessage[],
+                injected: [] as BaseMessage[],
+              };
 
         const directInjected: BaseMessage[] =
           directAdditionalContexts.length > 0
             ? [
-              new HumanMessage({
-                content: directAdditionalContexts.join('\n\n'),
-                // System-role metadata to match the event-driven
-                // path so policy/recovery guidance is treated
-                // consistently regardless of whether the tool ran
-                // direct or dispatched. Codex P2 [46].
-                additional_kwargs: { role: 'system', source: 'hook' },
-              }),
-            ]
+                new HumanMessage({
+                  content: directAdditionalContexts.join('\n\n'),
+                  // System-role metadata to match the event-driven
+                  // path so policy/recovery guidance is treated
+                  // consistently regardless of whether the tool ran
+                  // direct or dispatched. Codex P2 [46].
+                  additional_kwargs: { role: 'system', source: 'hook' },
+                }),
+              ]
             : [];
         outputs = [
           ...directOutputs,
@@ -3076,7 +3249,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             })
           )
         );
-        this.handleRunToolCompletions(
+        await this.handleRunToolCompletions(
           filteredCalls,
           toolOutputs,
           config,
@@ -3087,15 +3260,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         outputs =
           directAdditionalContexts.length > 0
             ? [
-              ...toolOutputs,
-              new HumanMessage({
-                content: directAdditionalContexts.join('\n\n'),
-                // Same system-role marker the event-driven path
-                // uses so direct vs dispatched is invisible to
-                // downstream consumers. Codex P2 [46].
-                additional_kwargs: { role: 'system', source: 'hook' },
-              }),
-            ]
+                ...toolOutputs,
+                new HumanMessage({
+                  content: directAdditionalContexts.join('\n\n'),
+                  // Same system-role marker the event-driven path
+                  // uses so direct vs dispatched is invisible to
+                  // downstream consumers. Codex P2 [46].
+                  additional_kwargs: { role: 'system', source: 'hook' },
+                }),
+              ]
             : toolOutputs;
       }
     }