@librechat/agents 3.1.86 → 3.1.87

package/src/events.ts

@@ -21,6 +21,35 @@ export class HandlerRegistry {
   }
 }
 
+export function composeEventHandlers(
+  ...handlerSets: Array<Record<string, t.EventHandler> | undefined>
+): Record<string, t.EventHandler> {
+  const composed: Partial<Record<string, t.EventHandler>> = {};
+
+  for (const handlerSet of handlerSets) {
+    if (!handlerSet) {
+      continue;
+    }
+    for (const [eventType, handler] of Object.entries(handlerSet)) {
+      const previous = composed[eventType];
+      if (previous === undefined) {
+        composed[eventType] = handler;
+        continue;
+      }
+      composed[eventType] = {
+        handle: async (
+          ...args: Parameters<t.EventHandler['handle']>
+        ): Promise<void> => {
+          await previous.handle(...args);
+          await handler.handle(...args);
+        },
+      };
+    }
+  }
+
+  return composed as Record<string, t.EventHandler>;
+}
+
 export class ModelEndHandler implements t.EventHandler {
   collectedUsage?: UsageMetadata[];
   constructor(collectedUsage?: UsageMetadata[]) {

package/src/graphs/Graph.ts

@@ -70,6 +70,13 @@ const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
 
+function getHandlerDispatchedEventKey(
+  eventName: string,
+  stepId: string
+): string {
+  return `${eventName}:${stepId}`;
+}
+
 export abstract class Graph<
   T extends t.BaseGraphState = t.BaseGraphState,
   _TNodeName extends string = string,
@@ -99,15 +106,18 @@ export abstract class Graph<
   ): Promise<string>;
   abstract dispatchRunStepDelta(
     id: string,
-    delta: t.ToolCallDelta
+    delta: t.ToolCallDelta,
+    metadata?: Record<string, unknown>
   ): Promise<void>;
   abstract dispatchMessageDelta(
     id: string,
-    delta: t.MessageDelta
+    delta: t.MessageDelta,
+    metadata?: Record<string, unknown>
   ): Promise<void>;
   abstract dispatchReasoningDelta(
     stepId: string,
-    delta: t.ReasoningDelta
+    delta: t.ReasoningDelta,
+    metadata?: Record<string, unknown>
   ): Promise<void>;
   abstract createCallModel(
     agentId?: string,
@@ -125,11 +135,12 @@ export abstract class Graph<
   contentIndexMap: Map<string, number> = new Map();
   toolCallStepIds: Map<string, string> = new Map();
   /**
-   * Step IDs that have been dispatched via handler registry directly
-   * (in dispatchRunStep).  Used by the custom event callback to skip
-   * duplicate dispatch through the LangGraph callback chain.
+   * Step IDs dispatched through the handler registry during this run.
+   * Event echo suppression is tracked separately so repeated deltas for
+   * the same step are scoped to the active custom event dispatch.
    */
   handlerDispatchedStepIds: Set<string> = new Set();
+  protected handlerDispatchedEventCounts: Map<string, number> = new Map();
   signal?: AbortSignal;
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
@@ -148,6 +159,20 @@ export abstract class Graph<
    * graph compiles.
    */
   toolOutputReferences: t.ToolOutputReferencesConfig | undefined;
+  /**
+   * Run-scoped opt-in for eager event-driven tool execution. The stream
+   * handler may prestart eligible event-driven tools; ToolNode later
+   * consumes the settled promises while preserving final ToolMessage order.
+   */
+  eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
+  eagerEventToolExecutions: Map<string, t.EagerEventToolExecution> = new Map();
+  eagerEventToolUsageCount: Map<string, number> = new Map();
+  private eagerEventToolUsageCountsByAgentId: Map<
+    string,
+    Map<string, number>
+  > = new Map();
+  eagerEventToolCallChunks: Map<string, t.EagerEventToolCallChunkState> =
+    new Map();
   /**
    * Run-scoped execution backend for built-in code tools. Defaults to the
    * remote Code API sandbox when unset.
@@ -187,7 +212,12 @@ export abstract class Graph<
     this.hookRegistry = undefined;
     this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
+    this.eagerEventToolExecution = undefined;
+    this.eagerEventToolExecutions.clear();
+    this.clearEagerEventToolUsageCounts();
+    this.eagerEventToolCallChunks.clear();
     this.toolExecution = undefined;
+    this.handlerDispatchedEventCounts.clear();
     /**
      * ToolNodes compiled from this graph captured the registry
      * instance at construction time, so simply dropping the Graph's
@@ -218,6 +248,46 @@ export abstract class Graph<
     this.sessions.clear();
   }
 
+  getEagerEventToolUsageCount(agentId?: string): Map<string, number> {
+    if (agentId == null || agentId === '') {
+      return this.eagerEventToolUsageCount;
+    }
+    let usageCount = this.eagerEventToolUsageCountsByAgentId.get(agentId);
+    if (usageCount == null) {
+      usageCount = new Map<string, number>();
+      this.eagerEventToolUsageCountsByAgentId.set(agentId, usageCount);
+    }
+    return usageCount;
+  }
+
+  protected clearEagerEventToolUsageCounts(): void {
+    this.eagerEventToolUsageCount.clear();
+    for (const usageCount of this.eagerEventToolUsageCountsByAgentId.values()) {
+      usageCount.clear();
+    }
+  }
+
+  markHandlerDispatchedEvent(eventName: string, stepId: string): () => void {
+    const key = getHandlerDispatchedEventKey(eventName, stepId);
+    this.handlerDispatchedEventCounts.set(
+      key,
+      (this.handlerDispatchedEventCounts.get(key) ?? 0) + 1
+    );
+    return () => {
+      const count = this.handlerDispatchedEventCounts.get(key) ?? 0;
+      if (count <= 1) {
+        this.handlerDispatchedEventCounts.delete(key);
+        return;
+      }
+      this.handlerDispatchedEventCounts.set(key, count - 1);
+    };
+  }
+
+  hasHandlerDispatchedEvent(eventName: string, stepId: string): boolean {
+    const key = getHandlerDispatchedEventKey(eventName, stepId);
+    return (this.handlerDispatchedEventCounts.get(key) ?? 0) > 0;
+  }
+
   /**
    * Subclass hook to register a freshly compiled ToolNode so
    * `clearHeavyState` can flush its per-Run direct-path turn cache
@@ -279,9 +349,7 @@ export abstract class Graph<
   private _compiledToolNodes: Set<{
     clearDirectPathTurns(): void;
   }> = new Set();
-  public getOrCreateFileCheckpointer():
-    | t.LocalFileCheckpointer
-    | undefined {
+  public getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined {
     // Return the cached instance unconditionally if one exists. The
     // toolExecution check below decides whether to *create* a new
     // one — `clearHeavyState` nulls `this.toolExecution` at end-of-
@@ -301,9 +369,7 @@ export abstract class Graph<
     // cleanup hooks fire). The bundle factory itself accepts a pre-
     // supplied checkpointer when present, so re-injecting this one
     // into every ToolNode is idempotent.
-    const bundle = createLocalCodingToolBundle(
-      this.toolExecution.local ?? {}
-    );
+    const bundle = createLocalCodingToolBundle(this.toolExecution.local ?? {});
     this._fileCheckpointer = bundle.checkpointer;
     return this._fileCheckpointer;
   }
@@ -381,10 +447,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
      * a stale reference on 2nd+ processStream calls.
      */
     this.toolCallStepIds.clear();
+    this.eagerEventToolExecutions.clear();
+    this.clearEagerEventToolUsageCounts();
+    this.eagerEventToolCallChunks.clear();
     this.handlerDispatchedStepIds = resetIfNotEmpty(
       this.handlerDispatchedStepIds,
       new Set()
     );
+    this.handlerDispatchedEventCounts = resetIfNotEmpty(
+      this.handlerDispatchedEventCounts,
+      new Map()
+    );
     this.messageIdsByStepKey = resetIfNotEmpty(
       this.messageIdsByStepKey,
       new Map()
@@ -679,6 +752,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
+        eagerEventToolExecution: this.eagerEventToolExecution,
+        eagerEventToolExecutions: this.eagerEventToolExecutions,
+        eagerEventToolUsageCount: this.getEagerEventToolUsageCount(
+          agentContext?.agentId
+        ),
         toolExecution: this.toolExecution,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
@@ -1307,9 +1385,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             );
             const stepId = this.getStepIdByKey(stepKey);
             if (typeof content === 'string') {
-              await this.dispatchMessageDelta(stepId, {
-                content: [{ type: ContentTypes.TEXT, text: content }],
-              });
+              await this.dispatchMessageDelta(
+                stepId,
+                {
+                  content: [{ type: ContentTypes.TEXT, text: content }],
+                },
+                metadata
+              );
             } else if (
               Array.isArray(content) &&
               content.every(
@@ -1320,9 +1402,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                   c.type.startsWith('text')
               )
             ) {
-              await this.dispatchMessageDelta(stepId, {
-                content: content as t.MessageDelta['content'],
-              });
+              await this.dispatchMessageDelta(
+                stepId,
+                {
+                  content: content as t.MessageDelta['content'],
+                },
+                metadata
+              );
             }
           }
         }
@@ -1360,9 +1446,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const stepId = this.getStepIdByKey(stepKey);
           const content = responseMessage.content;
           if (typeof content === 'string') {
-            await this.dispatchMessageDelta(stepId, {
-              content: [{ type: ContentTypes.TEXT, text: content }],
-            });
+            await this.dispatchMessageDelta(
+              stepId,
+              {
+                content: [{ type: ContentTypes.TEXT, text: content }],
+              },
+              metadata
+            );
           } else if (
             Array.isArray(content) &&
             content.every(
@@ -1373,9 +1463,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 c.type.startsWith('text')
             )
           ) {
-            await this.dispatchMessageDelta(stepId, {
-              content: content as t.MessageDelta['content'],
-            });
+            await this.dispatchMessageDelta(
+              stepId,
+              {
+                content: content as t.MessageDelta['content'],
+              },
+              metadata
+            );
           }
         }
       }
@@ -1613,12 +1707,22 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 this.handlerDispatchedStepIds.add(runStep.id);
               }
 
-              if (resolvedConfig) {
-                await safeDispatchCustomEvent(
+              const unmarkHandlerDispatchedEvent = handler
+                ? this.markHandlerDispatchedEvent(
                   GraphEvents.ON_RUN_STEP,
-                  runStep,
-                  resolvedConfig
-                );
+                  runStep.id
+                )
+                : undefined;
+              try {
+                if (resolvedConfig) {
+                  await safeDispatchCustomEvent(
+                    GraphEvents.ON_RUN_STEP,
+                    runStep,
+                    resolvedConfig
+                  );
+                }
+              } finally {
+                unmarkHandlerDispatchedEvent?.();
               }
             },
             dispatchRunStepCompleted: async (
@@ -1663,7 +1767,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const StateAnnotation = Annotation.Root({
       messages: Annotation<BaseMessage[]>({
         reducer: (a, b) => {
-          if (!a.length) {
+          if (!this.messages.length) {
             this.startIndex = a.length + b.length;
           }
           const result = messagesStateReducer(a, b);
@@ -1782,11 +1886,18 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     // but the primary dispatch above guarantees the event reaches the handler.
     // The customEventCallback in run.ts skips events already dispatched above
     // to prevent double handling.
-    await safeDispatchCustomEvent(
-      GraphEvents.ON_RUN_STEP,
-      runStep,
-      this.config
-    );
+    const unmarkHandlerDispatchedEvent = handler
+      ? this.markHandlerDispatchedEvent(GraphEvents.ON_RUN_STEP, stepId)
+      : undefined;
+    try {
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_RUN_STEP,
+        runStep,
+        this.config
+      );
+    } finally {
+      unmarkHandlerDispatchedEvent?.();
+    }
     return stepId;
   }
 
@@ -1858,7 +1969,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
   async dispatchRunStepDelta(
     id: string,
-    delta: t.ToolCallDelta
+    delta: t.ToolCallDelta,
+    metadata?: Record<string, unknown>
   ): Promise<void> {
     if (!this.config) {
       throw new Error('No config provided');
@@ -1869,14 +1981,37 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       id,
       delta,
     };
-    await safeDispatchCustomEvent(
-      GraphEvents.ON_RUN_STEP_DELTA,
-      runStepDelta,
-      this.config
+    const handler = this.handlerRegistry?.getHandler(
+      GraphEvents.ON_RUN_STEP_DELTA
     );
+    if (handler) {
+      await handler.handle(
+        GraphEvents.ON_RUN_STEP_DELTA,
+        runStepDelta,
+        metadata,
+        this
+      );
+      this.handlerDispatchedStepIds.add(id);
+    }
+    const unmarkHandlerDispatchedEvent = handler
+      ? this.markHandlerDispatchedEvent(GraphEvents.ON_RUN_STEP_DELTA, id)
+      : undefined;
+    try {
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_RUN_STEP_DELTA,
+        runStepDelta,
+        this.config
+      );
+    } finally {
+      unmarkHandlerDispatchedEvent?.();
+    }
   }
 
-  async dispatchMessageDelta(id: string, delta: t.MessageDelta): Promise<void> {
+  async dispatchMessageDelta(
+    id: string,
+    delta: t.MessageDelta,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
     if (!this.config) {
       throw new Error('No config provided');
     }
@@ -1884,16 +2019,36 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       id,
       delta,
     };
-    await safeDispatchCustomEvent(
-      GraphEvents.ON_MESSAGE_DELTA,
-      messageDelta,
-      this.config
+    const handler = this.handlerRegistry?.getHandler(
+      GraphEvents.ON_MESSAGE_DELTA
     );
+    if (handler) {
+      await handler.handle(
+        GraphEvents.ON_MESSAGE_DELTA,
+        messageDelta,
+        metadata,
+        this
+      );
+      this.handlerDispatchedStepIds.add(id);
+    }
+    const unmarkHandlerDispatchedEvent = handler
+      ? this.markHandlerDispatchedEvent(GraphEvents.ON_MESSAGE_DELTA, id)
+      : undefined;
+    try {
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_MESSAGE_DELTA,
+        messageDelta,
+        this.config
+      );
+    } finally {
+      unmarkHandlerDispatchedEvent?.();
+    }
   }
 
   dispatchReasoningDelta = async (
     stepId: string,
-    delta: t.ReasoningDelta
+    delta: t.ReasoningDelta,
+    metadata?: Record<string, unknown>
   ): Promise<void> => {
     if (!this.config) {
       throw new Error('No config provided');
@@ -1902,10 +2057,29 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       id: stepId,
       delta,
     };
-    await safeDispatchCustomEvent(
-      GraphEvents.ON_REASONING_DELTA,
-      reasoningDelta,
-      this.config
+    const handler = this.handlerRegistry?.getHandler(
+      GraphEvents.ON_REASONING_DELTA
     );
+    if (handler) {
+      await handler.handle(
+        GraphEvents.ON_REASONING_DELTA,
+        reasoningDelta,
+        metadata,
+        this
+      );
+      this.handlerDispatchedStepIds.add(stepId);
+    }
+    const unmarkHandlerDispatchedEvent = handler
+      ? this.markHandlerDispatchedEvent(GraphEvents.ON_REASONING_DELTA, stepId)
+      : undefined;
+    try {
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_REASONING_DELTA,
+        reasoningDelta,
+        this.config
+      );
+    } finally {
+      unmarkHandlerDispatchedEvent?.();
+    }
   };
 }

package/src/graphs/MultiAgentGraph.ts

@@ -723,7 +723,7 @@ export class MultiAgentGraph extends StandardGraph {
     const StateAnnotation = Annotation.Root({
       messages: Annotation<BaseMessage[]>({
         reducer: (a, b) => {
-          if (!a.length) {
+          if (!this.messages.length) {
             this.startIndex = a.length + b.length;
           }
           const result = messagesStateReducer(a, b);

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -73,6 +73,36 @@ const expectCompiledWorkflow = (
 };
 
 describe('LangGraph composition smoke tests', () => {
+  it('clears run-scoped eager tool state on reset', () => {
+    const graph = new StandardGraph({
+      runId: 'standard-eager-reset',
+      agents: [makeAgent('agent')],
+    });
+    const executions = graph.eagerEventToolExecutions;
+    const usageCount = graph.eagerEventToolUsageCount;
+    const scopedUsageCount = graph.getEagerEventToolUsageCount('agent');
+    const chunks = graph.eagerEventToolCallChunks;
+
+    graph.eagerEventToolExecutions.set(
+      'call_weather',
+      {} as t.EagerEventToolExecution
+    );
+    graph.eagerEventToolUsageCount.set('weather', 1);
+    scopedUsageCount.set('weather', 1);
+    graph.eagerEventToolCallChunks.set('0', { argsText: '{"city":"NYC"}' });
+
+    graph.resetValues();
+
+    expect(graph.eagerEventToolExecutions).toBe(executions);
+    expect(graph.eagerEventToolUsageCount).toBe(usageCount);
+    expect(graph.getEagerEventToolUsageCount('agent')).toBe(scopedUsageCount);
+    expect(graph.eagerEventToolCallChunks).toBe(chunks);
+    expect(graph.eagerEventToolExecutions.size).toBe(0);
+    expect(graph.eagerEventToolUsageCount.size).toBe(0);
+    expect(scopedUsageCount.size).toBe(0);
+    expect(graph.eagerEventToolCallChunks.size).toBe(0);
+  });
+
   it('compiles and invokes the standard single-agent graph', async () => {
     const graph = new StandardGraph({
       runId: 'standard-smoke',

package/src/index.ts

@@ -36,6 +36,9 @@ export * from './utils';
 /* Hooks */
 export * from './hooks';
 
+/* Programmatic sessions */
+export * from './session';
+
 /* HITL helpers */
 export * from './hitl';