@librechat/agents 3.2.21 → 3.2.31

package/src/agents/__tests__/promptCacheLiveHelpers.ts

@@ -2,12 +2,12 @@ import { expect } from '@jest/globals';
 import { HumanMessage } from '@langchain/core/messages';
 import type { UsageMetadata } from '@langchain/core/messages';
 import type { ClientOptions } from '@langchain/openai';
+import type { ChatOpenRouterInput } from '@/llm/openrouter';
 import type * as t from '@/types';
 import { GraphEvents, Providers } from '@/common';
 import { AgentContext } from '../AgentContext';
 import { ModelEndHandler } from '@/events';
 import { Run } from '@/run';
-import type { ChatOpenRouterInput } from '@/llm/openrouter';
 
 type LivePromptCacheProvider =
   | Providers.ANTHROPIC

package/src/events.ts

@@ -4,8 +4,8 @@ import type {
   BaseMessageFields,
   UsageMetadata,
 } from '@langchain/core/messages';
-import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type { Logger } from 'winston';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 import { Constants } from '@/common';
 

package/src/graphs/Graph.ts

@@ -11,6 +11,7 @@ import type {
   MessageContent,
 } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 import {
   formatAnthropicArtifactContent,
@@ -29,12 +30,16 @@ import {
   partitionAndMarkAnthropicToolCache,
 } from '@/messages';
 import {
-  GraphNodeKeys,
-  ContentTypes,
-  GraphEvents,
-  Providers,
-  StepTypes,
-} from '@/common';
+  resolveLangfuseConfig,
+  shouldTraceToolNodeForLangfuse,
+  withLangfuseToolOutputTracingConfig,
+} from '@/langfuseToolOutputTracing';
+import {
+  createLangfuseHandler,
+  createLangfuseTraceMetadata,
+  disposeLangfuseHandler,
+  isLangfuseCallbackHandler,
+} from '@/langfuse';
 import {
   resetIfNotEmpty,
   isAnthropicLike,
@@ -43,46 +48,41 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
-import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
-import { buildSubagentToolParams } from '@/tools/SubagentTool';
+import {
+  GraphNodeKeys,
+  ContentTypes,
+  GraphEvents,
+  Providers,
+  StepTypes,
+} from '@/common';
+import {
+  appendCallbacks,
+  findCallback,
+  type CallbackEntry,
+} from '@/utils/callbacks';
+import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
+import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
 import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import { partitionAndMarkBedrockToolCache } from '@/llm/bedrock/toolCache';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
+import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
+import { buildSubagentToolParams } from '@/tools/SubagentTool';
+import { initializeLangfuseTracing } from '@/instrumentation';
 import { shouldTriggerSummarization } from '@/summarization';
+import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
 import { messagesStateReducer } from '@/messages/reducer';
-import {
-  appendCallbacks,
-  findCallback,
-  type CallbackEntry,
-} from '@/utils/callbacks';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
 import { handleToolCalls } from '@/tools/handlers';
-import { resolveLocalToolsForBinding } from '@/tools/local';
-import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
-import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
 import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
-import {
-  createLangfuseHandler,
-  createLangfuseTraceMetadata,
-  disposeLangfuseHandler,
-  isLangfuseCallbackHandler,
-} from '@/langfuse';
-import { initializeLangfuseTracing } from '@/instrumentation';
-import {
-  resolveLangfuseConfig,
-  shouldTraceToolNodeForLangfuse,
-  withLangfuseToolOutputTracingConfig,
-} from '@/langfuseToolOutputTracing';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
-import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
-import { partitionAndMarkBedrockToolCache } from '@/llm/bedrock/toolCache';
-import type { HookRegistry } from '@/hooks';
 
 const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 
@@ -177,7 +177,42 @@ function getResponseReasoningContent({
   );
 }
 
-function getTextMessageDeltaContent(
+function isTextMessageContentPart(
+  contentPart: MessageContent[number] | t.MessageContentComplex
+): boolean {
+  return (
+    typeof contentPart === 'object' &&
+    'type' in contentPart &&
+    typeof contentPart.type === 'string' &&
+    contentPart.type.startsWith('text')
+  );
+}
+
+function isGoogleServerSideToolMessageContentPart(
+  contentPart: MessageContent[number] | t.MessageContentComplex
+): boolean {
+  return (
+    typeof contentPart === 'object' &&
+    'type' in contentPart &&
+    (contentPart.type === 'toolCall' || contentPart.type === 'toolResponse')
+  );
+}
+
+function hasGoogleServerSideToolDeltaContent(
+  provider: Providers | undefined,
+  content: t.MessageDelta['content']
+): content is t.MessageContentComplex[] {
+  return (
+    isGoogleLike(provider) &&
+    Array.isArray(content) &&
+    content.some((contentPart) =>
+      isGoogleServerSideToolMessageContentPart(contentPart)
+    )
+  );
+}
+
+function getMessageDeltaContent(
+  provider: Providers | undefined,
   content: MessageContent | undefined
 ): t.MessageDelta['content'] | undefined {
   if (content == null) {
@@ -191,28 +226,142 @@ function getTextMessageDeltaContent(
   if (content.length === 0) {
     return undefined;
   }
-  if (
-    !content.every(
-      (contentPart) =>
-        typeof contentPart === 'object' &&
-        'type' in contentPart &&
-        typeof contentPart.type === 'string' &&
-        contentPart.type.startsWith('text')
-    )
-  ) {
+
+  const hasGoogleServerSideToolPart =
+    isGoogleLike(provider) &&
+    content.some((contentPart) =>
+      isGoogleServerSideToolMessageContentPart(contentPart)
+    );
+  if (content.every((contentPart) => isTextMessageContentPart(contentPart))) {
+    return content as t.MessageDelta['content'];
+  }
+  if (!hasGoogleServerSideToolPart) {
     return undefined;
   }
-  return content as t.MessageDelta['content'];
+  const messageContent = content.filter(
+    (contentPart) =>
+      isTextMessageContentPart(contentPart) ||
+      isGoogleServerSideToolMessageContentPart(contentPart)
+  );
+  return messageContent.length > 0
+    ? (messageContent as t.MessageDelta['content'])
+    : undefined;
+}
+
+function hasTextDeltaContent(
+  content: t.MessageDelta['content'] | undefined
+): boolean {
+  if (content == null) {
+    return false;
+  }
+  return content.some((contentPart) => {
+    if (contentPart.type?.startsWith(ContentTypes.TEXT) !== true) {
+      return false;
+    }
+    const text = (contentPart as Partial<{ text: string }>).text;
+    return typeof text === 'string' && text !== '';
+  });
+}
+
+function hasReasoningDeltaContent(
+  content: t.ReasoningDelta['content'] | undefined
+): boolean {
+  if (content == null) {
+    return false;
+  }
+  return content.some(
+    (contentPart) =>
+      contentPart.type === ContentTypes.THINK && contentPart.think !== ''
+  );
+}
+
+function getCurrentStepIds({
+  graph,
+  metadata,
+}: {
+  graph: Graph<t.BaseGraphState>;
+  metadata: Record<string, unknown>;
+}): string[] {
+  const baseStepKey = graph.getStepBaseKey(metadata);
+  const currentStepIds: string[] = [];
+  for (const [stepKey, stepIds] of graph.stepKeyIds) {
+    if (stepKey !== baseStepKey && !stepKey.startsWith(`${baseStepKey}_`)) {
+      continue;
+    }
+    currentStepIds.push(...stepIds);
+  }
+  return currentStepIds;
+}
+
+function hasCurrentTextDeltaStep({
+  graph,
+  metadata,
+}: {
+  graph: Graph<t.BaseGraphState>;
+  metadata: Record<string, unknown>;
+}): boolean {
+  return getCurrentStepIds({ graph, metadata }).some((stepId) =>
+    graph.messageStepHasTextDeltas.has(stepId)
+  );
+}
+
+function hasCurrentReasoningDeltaStep({
+  graph,
+  metadata,
+}: {
+  graph: Graph<t.BaseGraphState>;
+  metadata: Record<string, unknown>;
+}): boolean {
+  return getCurrentStepIds({ graph, metadata }).some((stepId) =>
+    graph.reasoningStepHasDeltas.has(stepId)
+  );
+}
+
+function clearCurrentDeltaStepMarkers({
+  graph,
+  metadata,
+}: {
+  graph: Graph<t.BaseGraphState>;
+  metadata: Record<string, unknown>;
+}): void {
+  for (const stepId of getCurrentStepIds({ graph, metadata })) {
+    graph.messageStepHasTextDeltas.delete(stepId);
+    graph.reasoningStepHasDeltas.delete(stepId);
+  }
+}
+
+async function dispatchMessageCreationStep({
+  graph,
+  stepKey,
+  messageId,
+  metadata,
+}: {
+  graph: Graph<t.BaseGraphState>;
+  stepKey: string;
+  messageId: string;
+  metadata: Record<string, unknown>;
+}): Promise<string> {
+  await graph.dispatchRunStep(
+    stepKey,
+    {
+      type: StepTypes.MESSAGE_CREATION,
+      message_creation: { message_id: messageId },
+    },
+    metadata
+  );
+  return graph.getStepIdByKey(stepKey);
 }
 
 async function dispatchTextMessageContent({
   graph,
   stepKey,
+  provider,
   content,
   metadata,
 }: {
   graph: Graph<t.BaseGraphState>;
   stepKey: string;
+  provider?: Providers;
   content: t.MessageDelta['content'];
   metadata: Record<string, unknown>;
 }): Promise<boolean> {
@@ -220,15 +369,28 @@ async function dispatchTextMessageContent({
   if (!messageId) {
     return false;
   }
-  await graph.dispatchRunStep(
+  if (hasGoogleServerSideToolDeltaContent(provider, content)) {
+    for (const contentPart of content) {
+      const stepId = await dispatchMessageCreationStep({
+        graph,
+        stepKey,
+        messageId,
+        metadata,
+      });
+      await graph.dispatchMessageDelta(
+        stepId,
+        { content: [contentPart] },
+        metadata
+      );
+    }
+    return true;
+  }
+  const stepId = await dispatchMessageCreationStep({
+    graph,
     stepKey,
-    {
-      type: StepTypes.MESSAGE_CREATION,
-      message_creation: { message_id: messageId },
-    },
-    metadata
-  );
-  const stepId = graph.getStepIdByKey(stepKey);
+    messageId,
+    metadata,
+  });
   await graph.dispatchMessageDelta(stepId, { content }, metadata);
   return true;
 }
@@ -291,6 +453,29 @@ function markPostReasoningContent(agentContext: AgentContext): void {
   agentContext.reasoningTransitionCount++;
 }
 
+function getDispatchableFinalReasoningContent({
+  agentContext,
+  responseReasoningContent,
+  hasStreamedTextDeltaStep,
+  hasStreamedReasoningDeltaStep,
+}: {
+  agentContext: AgentContext;
+  responseReasoningContent: string | undefined;
+  hasStreamedTextDeltaStep: boolean;
+  hasStreamedReasoningDeltaStep: boolean;
+}): string | undefined {
+  if (responseReasoningContent == null || hasStreamedReasoningDeltaStep) {
+    return undefined;
+  }
+  if (
+    agentContext.provider === Providers.OPENROUTER &&
+    hasStreamedTextDeltaStep
+  ) {
+    return undefined;
+  }
+  return responseReasoningContent;
+}
+
 export abstract class Graph<
   T extends t.BaseGraphState = t.BaseGraphState,
   _TNodeName extends string = string,
@@ -309,6 +494,9 @@ export abstract class Graph<
   abstract getKeyList(
     metadata: Record<string, unknown> | undefined
   ): (string | number | undefined)[];
+  abstract getStepBaseKey(
+    metadata: Record<string, unknown> | undefined
+  ): string;
   abstract getStepKey(metadata: Record<string, unknown> | undefined): string;
   abstract checkKeyList(keyList: (string | number | undefined)[]): boolean;
   abstract getStepIdByKey(stepKey: string, index?: number): string;
@@ -340,6 +528,7 @@ export abstract class Graph<
     state: t.AgentSubgraphState,
     config?: RunnableConfig
   ) => Promise<Partial<t.AgentSubgraphState>>;
+  messageStepHasTextDeltas: Set<string> = new Set();
   messageStepHasToolCalls: Map<string, boolean> = new Map();
   messageIdsByStepKey: Map<string, string> = new Map();
   prelimMessageIdsByStepKey: Map<string, string> = new Map();
@@ -354,6 +543,7 @@ export abstract class Graph<
    * the same step are scoped to the active custom event dispatch.
    */
   handlerDispatchedStepIds: Set<string> = new Set();
+  reasoningStepHasDeltas: 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 */
@@ -429,6 +619,8 @@ export abstract class Graph<
     this.stepKeyIds = new Map();
     this.toolCallStepIds.clear();
     this.messageIdsByStepKey = new Map();
+    this.messageStepHasTextDeltas = new Set();
+    this.reasoningStepHasDeltas = new Set();
     this.messageStepHasToolCalls = new Map();
     this.prelimMessageIdsByStepKey = new Map();
     this.invokedToolIds = undefined;
@@ -705,6 +897,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       this.messageStepHasToolCalls,
       new Map()
     );
+    this.messageStepHasTextDeltas = resetIfNotEmpty(
+      this.messageStepHasTextDeltas,
+      new Set()
+    );
+    this.reasoningStepHasDeltas = resetIfNotEmpty(
+      this.reasoningStepHasDeltas,
+      new Set()
+    );
     this.prelimMessageIdsByStepKey = resetIfNotEmpty(
       this.prelimMessageIdsByStepKey,
       new Map()
@@ -764,6 +964,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return agentContext;
   }
 
+  getStepBaseKey(metadata: Record<string, unknown> | undefined): string {
+    if (!metadata) return '';
+
+    const keyList = this.getInvocationKeyList(metadata);
+    if (this.checkKeyList(keyList)) {
+      throw new Error('Missing metadata');
+    }
+
+    return joinKeys(keyList);
+  }
+
   getStepKey(metadata: Record<string, unknown> | undefined): string {
     if (!metadata) return '';
 
@@ -810,6 +1021,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   ): (string | number | undefined)[] {
     if (!metadata) return [];
 
+    const keyList = this.getInvocationKeyList(metadata);
+    const agentContext = this.getAgentContext(metadata);
+    if (
+      agentContext.currentTokenType === ContentTypes.THINK ||
+      agentContext.currentTokenType === 'think_and_text'
+    ) {
+      keyList.push('reasoning');
+    } else if (agentContext.tokenTypeSwitch === 'content') {
+      keyList.push(`post-reasoning-${agentContext.reasoningTransitionCount}`);
+    }
+
+    return keyList;
+  }
+
+  private getInvocationKeyList(
+    metadata: Record<string, unknown>
+  ): (string | number | undefined)[] {
+    const keyList = this.getBaseKeyList(metadata);
+    if (this.invokedToolIds != null && this.invokedToolIds.size > 0) {
+      keyList.push(this.invokedToolIds.size + '');
+    }
+    return keyList;
+  }
+
+  private getBaseKeyList(
+    metadata: Record<string, unknown>
+  ): (string | number | undefined)[] {
     const configurable = this.config?.configurable;
     const runId =
       (metadata.run_id as string | undefined) ??
@@ -831,20 +1069,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       checkpointNs,
     ];
 
-    const agentContext = this.getAgentContext(metadata);
-    if (
-      agentContext.currentTokenType === ContentTypes.THINK ||
-      agentContext.currentTokenType === 'think_and_text'
-    ) {
-      keyList.push('reasoning');
-    } else if (agentContext.tokenTypeSwitch === 'content') {
-      keyList.push(`post-reasoning-${agentContext.reasoningTransitionCount}`);
-    }
-
-    if (this.invokedToolIds != null && this.invokedToolIds.size > 0) {
-      keyList.push(this.invokedToolIds.size + '');
-    }
-
     return keyList;
   }
 
@@ -994,6 +1218,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         sessions: this.sessions,
         toolDefinitions: toolDefMap,
         agentId: agentContext?.agentId,
+        executingAgentId: agentContext?.agentId,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
@@ -1038,6 +1263,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       trace: traceToolNode,
       runLangfuse: this.langfuse,
       agentLangfuse: agentContext?.langfuse,
+      // `agentId` is intentionally left unset on this path (it is the
+      // subagent-scope marker); `executingAgentId` always identifies the owning
+      // agent so hooks can attribute the batch even at the top level.
+      executingAgentId: agentContext?.agentId,
       toolCallStepIds: this.toolCallStepIds,
       errorHandler: (data, metadata): Promise<void> =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
@@ -1610,6 +1839,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           };
         }
       }
+      const metadata = config.metadata as Record<string, unknown>;
 
       try {
         result = await withLangfuseToolOutputTracingConfig(
@@ -1627,6 +1857,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           agentContext.langfuse
         );
       } catch (primaryError) {
+        clearCurrentDeltaStepMarkers({
+          graph: this,
+          metadata,
+        });
         result = await withLangfuseToolOutputTracingConfig(
           this.langfuse,
           () =>
@@ -1667,32 +1901,48 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const toolCalls = (responseMessage as AIMessageChunk | undefined)
         ?.tool_calls;
       const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
-      const metadata = config.metadata as Record<string, unknown>;
       const responseReasoningContent = getResponseReasoningContent({
         responseMessage: responseMessage as Partial<AIMessageChunk> | undefined,
         reasoningKey: agentContext.reasoningKey,
       });
-      const textMessageContent = getTextMessageDeltaContent(
+      const textMessageContent = getMessageDeltaContent(
+        agentContext.provider,
         responseMessage?.content as MessageContent | undefined
       );
+      const hasStreamedTextDeltaStep = hasCurrentTextDeltaStep({
+        graph: this,
+        metadata,
+      });
+      const hasStreamedReasoningDeltaStep = hasCurrentReasoningDeltaStep({
+        graph: this,
+        metadata,
+      });
+      const dispatchableFinalReasoningContent =
+        getDispatchableFinalReasoningContent({
+          agentContext,
+          responseReasoningContent,
+          hasStreamedTextDeltaStep,
+          hasStreamedReasoningDeltaStep,
+        });
 
       if (hasToolCalls) {
         const dispatchedReasoning =
-          responseReasoningContent != null &&
+          dispatchableFinalReasoningContent != null &&
           (await dispatchReasoningContent({
             graph: this,
             agentContext,
-            reasoningContent: responseReasoningContent,
+            reasoningContent: dispatchableFinalReasoningContent,
             metadata,
           }));
         if (dispatchedReasoning) {
           markPostReasoningContent(agentContext);
         }
-        if (textMessageContent != null) {
+        if (textMessageContent != null && !hasStreamedTextDeltaStep) {
           const stepKey = this.getStepKey(metadata);
           const dispatchedText = await dispatchTextMessageContent({
             graph: this,
             stepKey,
+            provider: agentContext.provider,
             content: textMessageContent,
             metadata,
           });
@@ -1711,21 +1961,22 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
        */
       if (!hasToolCalls && responseMessage != null) {
         const dispatchedReasoning =
-          responseReasoningContent != null &&
+          dispatchableFinalReasoningContent != null &&
           (await dispatchReasoningContent({
             graph: this,
             agentContext,
-            reasoningContent: responseReasoningContent,
+            reasoningContent: dispatchableFinalReasoningContent,
             metadata,
           }));
         if (dispatchedReasoning && textMessageContent != null) {
           markPostReasoningContent(agentContext);
         }
-        if (textMessageContent != null) {
+        if (textMessageContent != null && !hasStreamedTextDeltaStep) {
           const stepKey = this.getStepKey(metadata);
           await dispatchTextMessageContent({
             graph: this,
             stepKey,
+            provider: agentContext.provider,
             content: textMessageContent,
             metadata,
           });
@@ -2294,6 +2545,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       id,
       delta,
     };
+    if (hasTextDeltaContent(delta.content)) {
+      this.messageStepHasTextDeltas.add(id);
+    }
     const handler = this.handlerRegistry?.getHandler(
       GraphEvents.ON_MESSAGE_DELTA
     );
@@ -2332,6 +2586,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       id: stepId,
       delta,
     };
+    if (hasReasoningDeltaContent(delta.content)) {
+      this.reasoningStepHasDeltas.add(stepId);
+    }
     const handler = this.handlerRegistry?.getHandler(
       GraphEvents.ON_REASONING_DELTA
     );

package/src/graphs/MultiAgentGraph.ts

@@ -15,8 +15,8 @@ import {
   getCurrentTaskInput,
   messagesStateReducer,
 } from '@langchain/langgraph';
-import type { LangGraphRunnableConfig } from '@langchain/langgraph';
 import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
+import type { LangGraphRunnableConfig } from '@langchain/langgraph';
 import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';