@librechat/agents 3.3.7 → 3.3.9

package/src/graphs/Graph.ts

@@ -1,4 +1,5 @@
 /* eslint-disable no-console */
+import { v4 } from 'uuid';
 import { nanoid } from 'nanoid';
 import { tool } from '@langchain/core/tools';
 import { ToolNode } from '@langchain/langgraph/prebuilt';
@@ -53,6 +54,14 @@ import {
   appendPredecessorHandoffCue,
   removePredecessorHandoffCue,
 } from '@/messages';
+import {
+  attemptInvoke,
+  tryFallbackProviders,
+  getFallbackErrorContext,
+  getFallbackOverflowCandidates,
+  projectMessagesForProvider,
+  resolveServingModelId,
+} from '@/llm/invoke';
 import {
   resetIfNotEmpty,
   isAnthropicLike,
@@ -64,14 +73,14 @@ import {
   sleep,
 } from '@/utils';
 import {
-  attemptInvoke,
-  tryFallbackProviders,
-  getFallbackErrorContext,
-  getFallbackOverflowCandidates,
-  projectMessagesForProvider,
-  resolveServingModelId,
-} from '@/llm/invoke';
-import { v4 } from 'uuid';
+  Constants,
+  GraphNodeKeys,
+  ContentTypes,
+  GraphEvents,
+  Providers,
+  StepTypes,
+  PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS,
+} from '@/common';
 import {
   createLangfuseHandler,
   createLangfuseTraceMetadata,
@@ -83,21 +92,16 @@ import {
   planContextOverflowRecovery,
   translateRecoveryBudget,
 } from '@/llm/contextOverflowRecovery';
+import {
+  hasToolOutputTracingConfig,
+  resolveLangfuseConfig,
+  resolveToolOutputTracingConfig,
+} from '@/langfuseConfig';
 import {
   compactToolContent,
   getToolContentCharLength,
   serializeToolContentBounded,
 } from '@/utils/toolContent';
-import { resolveMaxSeals } from '@/llm/preempt';
-import {
-  Constants,
-  GraphNodeKeys,
-  ContentTypes,
-  GraphEvents,
-  Providers,
-  StepTypes,
-  PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS,
-} from '@/common';
 import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
@@ -125,12 +129,12 @@ import { shouldTriggerSummarization } from '@/summarization';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
 import { messagesStateReducer } from '@/messages/reducer';
-import { resolveLangfuseConfig } from '@/langfuseConfig';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
 import { handleToolCalls } from '@/tools/handlers';
 import { isThinkingEnabled } from '@/llm/request';
+import { resolveMaxSeals } from '@/llm/preempt';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
@@ -762,6 +766,15 @@ export abstract class Graph<
     new Map();
   eagerEventToolCallChunks: Map<string, t.EagerEventToolCallChunkState> =
     new Map();
+  /**
+   * Per-run eager prestart circuit breaker, shared by reference with every
+   * ToolNode this graph compiles. When a prestarted execution's args turn
+   * out to differ from the final request, ToolNode records the tool name
+   * here and the stream handler stops prestarting that tool for the rest of
+   * the run — the retry then executes normally instead of re-diverging in a
+   * loop (LibreChat#14371).
+   */
+  eagerEventToolSuppressions: Set<string> = new Set();
   /**
    * Run-scoped execution backend for built-in code tools. Defaults to the
    * remote Code API sandbox when unset.
@@ -811,6 +824,7 @@ export abstract class Graph<
     this.eagerEventToolExecutions.clear();
     this.clearEagerEventToolUsageCounts();
     this.eagerEventToolCallChunks.clear();
+    this.eagerEventToolSuppressions.clear();
     this.toolExecution = undefined;
     this.handlerDispatchedEventCounts.clear();
     /**
@@ -997,6 +1011,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /** Checkpoint scope whose messages match index-keyed tool snapshots. */
   private originalToolContentCheckpointScope?: string;
   runId: string | undefined;
+  /**
+   * Identity used to stamp Langfuse runtime scopes and handlers (see
+   * `LangfuseRuntimeContext.runId`). Carries an opaque per-instance
+   * component: public run ids are unrestricted and may repeat across
+   * concurrently executing runs (retries, duplicate submissions,
+   * tenant-local message ids), and equal stamps would let those runs adopt
+   * each other's scopes. One graph instance = one execution's stamp, shared
+   * by the stream handler and every graph-level scope of that execution.
+   */
+  readonly langfuseScopeRunId: string;
   /**
    * Boundary between historical messages (loaded from conversation state)
    * and messages produced during the current run.  Set once in the state
@@ -1081,6 +1105,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   }: t.StandardGraphInput) {
     super();
     this.runId = runId;
+    this.langfuseScopeRunId = `${runId ?? 'graph'}:${nanoid()}`;
     this.signal = signal;
     this.langfuse = langfuse;
     this.subagentUsageSink = subagentUsageSink;
@@ -1129,6 +1154,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.eagerEventToolExecutions.clear();
     this.clearEagerEventToolUsageCounts();
     this.eagerEventToolCallChunks.clear();
+    this.eagerEventToolSuppressions.clear();
     this.handlerDispatchedStepIds = resetIfNotEmpty(
       this.handlerDispatchedStepIds,
       new Set()
@@ -1657,6 +1683,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         eagerEventToolUsageCount: this.getEagerEventToolUsageCount(
           agentContext?.agentId
         ),
+        eagerEventToolSuppressions: this.eagerEventToolSuppressions,
         toolExecution: this.toolExecution,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         interruptingToolNames:
@@ -3057,6 +3084,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         metadata: {
           ...(config.metadata ?? {}),
           ...traceMetadata,
+          /** Canonical agent identity, stamped OUTSIDE trace-metadata
+           *  filtering: `createLangfuseTraceMetadata` drops values over its
+           *  length cap, but scope trust (`isForeignScope`) needs the id
+           *  verbatim regardless of length. */
+          agentId,
         },
       };
       initializeLangfuseTracing(langfuse);
@@ -3069,6 +3101,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           tags: ['librechat', 'agent'],
           traceIdSeed:
             langfuse?.deterministicTraceId === true ? this.runId : undefined,
+          runId: this.langfuseScopeRunId,
+          toolOutputTracing: hasToolOutputTracingConfig(
+            this.langfuse,
+            agentContext.langfuse
+          )
+            ? resolveToolOutputTracingConfig(
+              this.langfuse,
+              agentContext.langfuse
+            )
+            : undefined,
         });
         if (langfuseHandler != null) {
           invokeConfig = {
@@ -3089,6 +3131,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           resolveLangfuseRuntimeScope({
             runLangfuse: this.langfuse,
             langfuseOverlay: agentContext.langfuse,
+            runId: this.langfuseScopeRunId,
+            agentId,
           }),
           () =>
             attemptInvoke(
@@ -3251,6 +3295,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             resolveLangfuseRuntimeScope({
               runLangfuse: this.langfuse,
               langfuseOverlay: agentContext.langfuse,
+              runId: this.langfuseScopeRunId,
+              agentId,
             }),
             () =>
               tryFallbackProviders({
@@ -3673,7 +3719,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
      * the same run — `haltRun` is first-write-wins — is left alone.
      */
     const halt = this.hookRegistry.getHaltSignal(runId);
-    if (result.preventContinuation === true && halt?.source === 'PreemptBoundary') {
+    if (
+      result.preventContinuation === true &&
+      halt?.source === 'PreemptBoundary'
+    ) {
       this.preemptHaltReason = halt.reason;
       this.hookRegistry.clearHaltSignal(runId);
     }

package/src/graphs/MultiAgentGraph.ts

@@ -27,6 +27,20 @@ import { Constants } from '@/common';
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
 const HANDOFF_INSTRUCTIONS_KEY = 'handoff_instructions';
 
+/**
+ * Handoff and fan-in prompts that route work between agents. Built in-run and
+ * never persisted as standalone payload entries, so they are marked synthetic:
+ * `messagesStateReducer` would otherwise give them a plain UUID and downstream
+ * consumers — compaction coverage anchors — could not tell them apart from a
+ * message replayed out of the payload.
+ */
+function buildRoutingPrompt(content: string): HumanMessage {
+  return new HumanMessage({
+    content,
+    additional_kwargs: { role: 'user', isMeta: true, source: 'routing' },
+  });
+}
+
 function getHandoffInstructions(
   input: Record<string, unknown>,
   promptKey: string,
@@ -66,6 +80,46 @@ function extractLegacyHandoffInstructions(
   return content.match(HANDOFF_INSTRUCTIONS_PATTERN)?.[1]?.trim() ?? null;
 }
 
+/** Whether a tool name marks a handoff transfer (static or conditional). */
+function isTransferToolName(name: unknown): boolean {
+  return (
+    typeof name === 'string' &&
+    (name.startsWith(Constants.LC_TRANSFER_TO_) ||
+      name === 'conditional_transfer')
+  );
+}
+
+/**
+ * Drop transfer `tool_use` content blocks from an AI message's array content.
+ * Companion to the reception's tool-call filtering: array-content providers
+ * (Anthropic) serialize retained blocks verbatim, so a transfer block whose
+ * call/result the reception stripped — or a parallel sibling's transfer block,
+ * whose result never reaches this recipient's state — would replay as an
+ * unmatched `tool_use`. Matched by the gathered ids AND by transfer name
+ * (sibling blocks have no collectable id here). String content passes through.
+ */
+function filterTransferToolUseBlocks(
+  content: AIMessage['content'],
+  transferToolCallIds: ReadonlySet<string>
+): AIMessage['content'] {
+  if (!Array.isArray(content)) {
+    return content;
+  }
+  return content.filter((block) => {
+    if (
+      typeof block !== 'object' ||
+      (block as { type?: string } | null)?.type !== 'tool_use'
+    ) {
+      return true;
+    }
+    const toolUse = block as { id?: string; name?: string };
+    if (toolUse.id != null && transferToolCallIds.has(toolUse.id)) {
+      return false;
+    }
+    return !isTransferToolName(toolUse.name);
+  });
+}
+
 function isValidHandoffGroupId(value: unknown): value is number {
   return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
 }
@@ -828,9 +882,23 @@ export class MultiAgentGraph extends StandardGraph {
               remainingToolCalls.length > 0 ||
               (typeof aiMsg.content === 'string' && aiMsg.content.trim())
             ) {
-              /** Keep the message but without transfer tool calls */
+              /**
+               * Keep the message but without transfer tool calls — AND
+               * without their `tool_use` content blocks. Array-content
+               * providers (Anthropic) serialize the retained blocks
+               * verbatim, so a transfer block whose call/result this
+               * filter just stripped would reach the receiving agent as
+               * an unmatched `tool_use` and the provider rejects the
+               * request. Filtered by transfer NAME as well as the
+               * gathered ids: a parallel sibling's transfer block has no
+               * result in THIS recipient's state, so its id is never
+               * collected, but its name still marks it.
+               */
               const filteredAiMsg = new AIMessage({
-                content: aiMsg.content,
+                content: filterTransferToolUseBlocks(
+                  aiMsg.content,
+                  transferToolCallIds
+                ),
                 tool_calls: remainingToolCalls,
                 id: aiMsg.id,
               });
@@ -986,12 +1054,12 @@ export class MultiAgentGraph extends StandardGraph {
                 new AIMessage(
                   `[Processed tool result and transferring to ${agentId}]`
                 ),
-                new HumanMessage(instructions),
+                buildRoutingPrompt(instructions),
               ];
             } else {
               messagesForAgent = [
                 ...filteredMessages,
-                new HumanMessage(instructions),
+                buildRoutingPrompt(instructions),
               ];
             }
           }
@@ -1204,7 +1272,7 @@ export class MultiAgentGraph extends StandardGraph {
               effectiveExcludeResults === false
             ) {
               return {
-                messages: [new HumanMessage(promptText)],
+                messages: [buildRoutingPrompt(promptText)],
               };
             }
 
@@ -1212,7 +1280,7 @@ export class MultiAgentGraph extends StandardGraph {
              * to pass filtered messages + prompt to the destination agent
              */
             const filteredMessages = state.messages.slice(0, this.startIndex);
-            const promptMessage = new HumanMessage(promptText);
+            const promptMessage = buildRoutingPrompt(promptText);
             return {
               messages: [promptMessage],
               agentMessages: messagesStateReducer(filteredMessages, [

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

@@ -135,6 +135,7 @@ describe('LangGraph composition smoke tests', () => {
     const usageCount = graph.eagerEventToolUsageCount;
     const scopedUsageCount = graph.getEagerEventToolUsageCount('agent');
     const chunks = graph.eagerEventToolCallChunks;
+    const suppressions = graph.eagerEventToolSuppressions;
 
     graph.eagerEventToolExecutions.set(
       'call_weather',
@@ -143,6 +144,7 @@ describe('LangGraph composition smoke tests', () => {
     graph.eagerEventToolUsageCount.set('weather', 1);
     scopedUsageCount.set('weather', 1);
     graph.eagerEventToolCallChunks.set('0', { argsText: '{"city":"NYC"}' });
+    graph.eagerEventToolSuppressions.add('weather');
 
     graph.resetValues();
 
@@ -150,10 +152,12 @@ describe('LangGraph composition smoke tests', () => {
     expect(graph.eagerEventToolUsageCount).toBe(usageCount);
     expect(graph.getEagerEventToolUsageCount('agent')).toBe(scopedUsageCount);
     expect(graph.eagerEventToolCallChunks).toBe(chunks);
+    expect(graph.eagerEventToolSuppressions).toBe(suppressions);
     expect(graph.eagerEventToolExecutions.size).toBe(0);
     expect(graph.eagerEventToolUsageCount.size).toBe(0);
     expect(scopedUsageCount.size).toBe(0);
     expect(graph.eagerEventToolCallChunks.size).toBe(0);
+    expect(graph.eagerEventToolSuppressions.size).toBe(0);
   });
 
   it('compiles and invokes the standard single-agent graph', async () => {

package/src/hitl/askUserQuestion.ts

@@ -60,11 +60,24 @@ import type {
  * ```
  */
 export function askUserQuestion(
-  question: AskUserQuestionRequest
+  question: AskUserQuestionRequest,
+  options?: {
+    /**
+     * The calling tool's `tool_call_id`, surfaced on the interrupt payload
+     * as `tool_call_id` so hosts can attribute the question (and answer) to
+     * the exact tool-call content part. Tool bodies created with
+     * `tool(fn, …)` receive it as `config.toolCall.id` — LangChain stamps
+     * the full ToolCall onto the config when a tool is invoked with one.
+     * Optional: positional hosts and custom nodes can omit it.
+     */
+    toolCallId?: string;
+  }
 ): AskUserQuestionResolution {
   const payload: AskUserQuestionInterruptPayload = {
     type: 'ask_user_question',
     question,
+    ...(options?.toolCallId != null &&
+      options.toolCallId !== '' && { tool_call_id: options.toolCallId }),
   };
   return interrupt<AskUserQuestionInterruptPayload, AskUserQuestionResolution>(
     payload

package/src/instrumentation.ts

@@ -1,4 +1,4 @@
-import { createHash, randomBytes } from 'node:crypto';
+import { randomBytes } from 'node:crypto';
 import { setLangfuseTracerProvider } from '@langfuse/tracing';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 import { context, ROOT_CONTEXT, createContextKey } from '@opentelemetry/api';
@@ -13,16 +13,16 @@ import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
 import type { Context } from '@opentelemetry/api';
 import type * as t from '@/types';
 import {
-  createLibreChatTraceAttributes,
-  hasLangfuseConfigCredentials,
-  hasLangfuseEnvCredentials,
-  hasLangfuseEnvConfig,
-} from '@/langfuse';
+  getLangfuseDestinationKey,
+  getLangfuseSpanProcessorParams,
+  registerLangfuseManagedSpan,
+} from '@/langfuseSpanRegistry';
 import {
   resolveLangfuseConfigForSpan,
   resolveTraceIdSeedForSpan,
 } from '@/langfuseRuntimeScope';
 import { createLangfuseSpanProcessor } from '@/langfuseToolOutputTracing';
+import { createLibreChatTraceAttributes } from '@/langfuse';
 import { traceIdFromSeed } from '@/langfuseRuntimeContext';
 import { isPresent } from '@/utils/misc';
 
@@ -75,75 +75,15 @@ export function ensureOpenTelemetryContextManager(): void {
   }
 }
 
-function resolveLangfuseEnvironment(
-  langfuse?: t.LangfuseConfig
-): string | undefined {
-  const candidates = [
-    langfuse?.environment,
-    process.env.LANGFUSE_TRACING_ENVIRONMENT,
-    process.env.NODE_ENV,
-  ];
-  for (const candidate of candidates) {
-    if (candidate != null && candidate.trim() !== '') {
-      return candidate.trim();
-    }
-  }
-  return undefined;
-}
-
-function getLangfuseSpanProcessorParams(
-  langfuse?: t.LangfuseConfig
-): LangfuseSpanProcessorParams | undefined {
-  if (langfuse?.enabled === false) {
-    return undefined;
-  }
-  const environment = resolveLangfuseEnvironment(langfuse);
-  if (hasLangfuseConfigCredentials(langfuse)) {
-    return {
-      publicKey: langfuse.publicKey,
-      secretKey: langfuse.secretKey,
-      ...(isPresent(langfuse.baseUrl) ? { baseUrl: langfuse.baseUrl } : {}),
-      ...(isPresent(environment) ? { environment } : {}),
-    };
-  }
-  if (hasLangfuseEnvConfig()) {
-    const baseUrl =
-      langfuse?.baseUrl ??
-      process.env.LANGFUSE_BASE_URL ??
-      process.env.LANGFUSE_BASEURL;
-    return {
-      publicKey: process.env.LANGFUSE_PUBLIC_KEY as string,
-      secretKey: process.env.LANGFUSE_SECRET_KEY as string,
-      ...(isPresent(baseUrl) ? { baseUrl } : {}),
-      ...(isPresent(environment) ? { environment } : {}),
-    };
-  }
-  if (isPresent(langfuse?.baseUrl) && hasLangfuseEnvCredentials()) {
-    return {
-      publicKey: process.env.LANGFUSE_PUBLIC_KEY as string,
-      secretKey: process.env.LANGFUSE_SECRET_KEY as string,
-      baseUrl: langfuse.baseUrl,
-      ...(isPresent(environment) ? { environment } : {}),
-    };
-  }
-  return undefined;
-}
-
-function hashCacheKeyValue(value: string | undefined): string | undefined {
-  return isPresent(value)
-    ? createHash('sha256').update(value, 'utf8').digest('hex')
-    : undefined;
-}
-
-function getLangfuseTracerProviderKey(
-  params: LangfuseSpanProcessorParams,
+/** Cache key for processor instances: the destination plus processor-level
+ *  policy (`toolOutputTracing` is baked into each processor's redaction
+ *  behavior), unlike the pure destination identity used for span parenting. */
+function getLangfuseProcessorCacheKey(
+  destinationKey: string,
   langfuse?: t.LangfuseConfig
 ): string {
   return JSON.stringify({
-    publicKey: params.publicKey,
-    secretKeyHash: hashCacheKeyValue(params.secretKey),
-    baseUrl: params.baseUrl,
-    environment: params.environment,
+    destinationKey,
     toolOutputTracing: langfuse?.toolOutputTracing,
   });
 }
@@ -160,25 +100,43 @@ class RoutingLangfuseSpanProcessor implements SpanProcessor {
     if (params == null) {
       return undefined;
     }
+    return this.ensureProcessorForKey(
+      getLangfuseProcessorCacheKey(getLangfuseDestinationKey(params), langfuse),
+      params,
+      langfuse
+    );
+  }
 
-    const processorKey = getLangfuseTracerProviderKey(params, langfuse);
-    const existing = this.processors.get(processorKey);
+  private ensureProcessorForKey(
+    processorCacheKey: string,
+    params: LangfuseSpanProcessorParams,
+    langfuse?: t.LangfuseConfig
+  ): SpanProcessor {
+    const existing = this.processors.get(processorCacheKey);
     if (existing != null) {
       return existing;
     }
 
     const processor = createLangfuseSpanProcessor(params, langfuse);
-    this.processors.set(processorKey, processor);
+    this.processors.set(processorCacheKey, processor);
     return processor;
   }
 
   onStart(span: Span, parentContext: Context): void {
     const langfuse = resolveLangfuseConfigForSpan(parentContext);
-    const processor = this.ensureProcessor(langfuse);
-    if (processor == null) {
+    const params = getLangfuseSpanProcessorParams(langfuse);
+    if (params == null) {
       return;
     }
 
+    const destinationKey = getLangfuseDestinationKey(params);
+    const processor = this.ensureProcessorForKey(
+      getLangfuseProcessorCacheKey(destinationKey, langfuse),
+      params,
+      langfuse
+    );
+    registerLangfuseManagedSpan(span, destinationKey);
+
     const librechatTraceAttributes = createLibreChatTraceAttributes(
       langfuse?.librechatTraceAttributes ?? {}
     );