@librechat/agents 3.3.8 → 3.3.9

package/src/langfuse.ts

@@ -1,7 +1,8 @@
 import { CallbackHandler } from '@langfuse/langchain';
-import { context as otelContext } from '@opentelemetry/api';
+import { LangfuseOtelContextKeys } from '@langfuse/core';
 import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
 import { isGraphInterrupt, isParentCommand } from '@langchain/langgraph';
+import { context as otelContext, trace as otelTrace } from '@opentelemetry/api';
 import {
   getLangfuseTracerProvider,
   propagateAttributes,
@@ -17,14 +18,34 @@ import type {
   LLMResult,
 } from '@langchain/core/outputs';
 import type { PropagateAttributesParams } from '@langfuse/tracing';
+import type { Context } from '@opentelemetry/api';
+import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
 import type * as t from '@/types';
 import {
   resolveLangfuseConfigForSpan,
+  resolveLangfuseScopeAgentId,
+  resolveLangfuseScopeRunId,
   resolveTraceIdSeedForSpan,
   withLangfuseRuntimeScope,
 } from '@/langfuseRuntimeScope';
+import {
+  hasLangfuseConfigCredentials,
+  hasLangfuseEnvCredentials,
+  resolveToolOutputTracingConfig,
+  hasLangfuseEnvConfig,
+} from '@/langfuseConfig';
+import {
+  getLangfuseManagedSpanDestination,
+  resolveLangfuseDestinationKey,
+} from '@/langfuseSpanRegistry';
 import { isPresent, parseBooleanEnv } from '@/utils/misc';
 
+export {
+  hasLangfuseConfigCredentials,
+  hasLangfuseEnvCredentials,
+  hasLangfuseEnvConfig,
+};
+
 const TRACE_METADATA_MAX_LENGTH = 200;
 const LANGFUSE_FORCE_FLUSH_ON_DISPOSE = 'LANGFUSE_FORCE_FLUSH_ON_DISPOSE';
 const GRAPH_INTERRUPT_CONTROL_FLOW = { controlFlow: 'GraphInterrupt' } as const;
@@ -45,12 +66,32 @@ type LangfuseHandlerParams = {
   traceMetadata?: LangfuseTraceMetadata;
   tags?: string[];
   traceIdSeed?: string;
+  /** Identity of the run this handler traces; ambient runtime scopes are
+   *  only adopted when stamped with the same run (see
+   *  `LangfuseRuntimeContext.runId`). */
+  runId?: string;
+  /** The run's resolved tool-output policy — for multi-agent streams the
+   *  conservative aggregate across agents, which `this.langfuse` (the
+   *  primary agent's config) cannot reproduce. Applied when a foreign
+   *  scope's policy is rejected. */
+  toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
+  /** The run's propagated trace name, re-propagated when a foreign scope's
+   *  attributes are cleared. */
+  traceName?: string;
 };
 
 type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
   langfuse?: t.LangfuseConfig;
 };
 
+type HandlerIdentity = {
+  userId?: string;
+  sessionId?: string;
+  tags?: string[];
+  metadata?: LangfuseTraceMetadata;
+  traceName?: string;
+};
+
 type LangfuseAttributeParams = AgentLangfuseHandlerParams & {
   traceName?: string;
 };
@@ -169,15 +210,102 @@ function normalizeBedrockUsageForLangfuse(output: LLMResult): LLMResult {
   return { ...output, generations };
 }
 
+const LANGGRAPH_NODE_METADATA_KEY = 'langgraph_node';
+/** Explicit agent identity in invoke metadata. Every identity-stamping
+ *  component (graph model path, ToolNode, summarization node) overwrites the
+ *  canonical `agentId` at its own invoke, so spread order guarantees the
+ *  closest stamper wins — key priority alone could not (an inherited key of
+ *  either casing can name the wrong agent). `agent_id` remains a fallback
+ *  for third-party graphs that only stamp the snake-case form. */
+const AGENT_ID_METADATA_KEYS = ['agentId', 'agent_id'];
+const LANGGRAPH_NODE_AGENT_PREFIXES = ['agent=', 'tools=', 'summarize='];
+
+/** The LangGraph node a callback executes under, from its inherited
+ *  `langgraph_node` run metadata. `undefined` when the callback carries no
+ *  node identity. */
+function getCallbackNode(
+  metadata?: Record<string, unknown>
+): string | undefined {
+  const node = metadata?.[LANGGRAPH_NODE_METADATA_KEY];
+  return typeof node === 'string' && node !== '' ? node : undefined;
+}
+
+/** Whether a callback's node identifies the given agent. The outer workflow
+ *  node carries the agent id VERBATIM — including ids that themselves begin
+ *  with an internal prefix (an agent literally named `agent=research`) — so
+ *  an exact match is checked before decoding the inner subgraph prefixes
+ *  (`agent=` / `tools=` / `summarize=`). */
+function callbackNodeMatchesAgent(node: string, agentId: string): boolean {
+  if (node === agentId) {
+    return true;
+  }
+  for (const prefix of LANGGRAPH_NODE_AGENT_PREFIXES) {
+    if (node.startsWith(prefix) && node.slice(prefix.length) === agentId) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Hosts often execute agent code inside their own OpenTelemetry spans (HTTP
+ * server auto-instrumentation on the global provider). Root observations must
+ * not inherit that ambient identity: the foreign parent is never exported to
+ * Langfuse, which orphans the trace root (root/trace input-output shaping is
+ * skipped because the span no longer looks like a root), collapses concurrent
+ * runs inside one request context — an agent run and the previous turn's
+ * title run — into a single merged trace with racing names and unioned tags,
+ * and bypasses the seeded deterministic trace id generator. Only a
+ * Langfuse-managed span bound to the same export destination as the starting
+ * run is a safe parent — that is the sanctioned way for hosts to group runs
+ * under their own Langfuse observations; a managed span from a different
+ * destination (another tenant's project) would leave this run's trace
+ * dangling in its own destination while inheriting the other trace's id.
+ */
+function detachForeignAmbientSpan(
+  activeContext: Context,
+  destinationKey?: string
+): Context {
+  const activeSpan = otelTrace.getSpan(activeContext);
+  if (activeSpan == null) {
+    return activeContext;
+  }
+  const parentDestination = getLangfuseManagedSpanDestination(activeSpan);
+  if (parentDestination != null && parentDestination === destinationKey) {
+    return activeContext;
+  }
+  return otelTrace.deleteSpan(activeContext);
+}
+
 class ScopedLangfuseCallbackHandler extends CallbackHandler {
   private readonly langfuse?: t.LangfuseConfig;
   private readonly traceIdSeed?: string;
+  private readonly runId?: string;
+  private readonly identity: HandlerIdentity;
+  private readonly toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
+  private readonly trackedRunIds = new Set<string>();
 
   constructor(params?: AgentLangfuseHandlerParams) {
-    const { langfuse, traceIdSeed, ...handlerParams } = params ?? {};
+    const {
+      langfuse,
+      traceIdSeed,
+      runId,
+      toolOutputTracing,
+      traceName,
+      ...handlerParams
+    } = params ?? {};
     super(handlerParams);
     this.langfuse = langfuse;
     this.traceIdSeed = traceIdSeed;
+    this.runId = runId;
+    this.toolOutputTracing = toolOutputTracing;
+    this.identity = {
+      userId: handlerParams.userId,
+      sessionId: handlerParams.sessionId,
+      tags: handlerParams.tags,
+      metadata: handlerParams.traceMetadata,
+      traceName,
+    };
   }
 
   private getDeterministicTraceSeed(): string | undefined {
@@ -186,17 +314,157 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
       : undefined;
   }
 
-  private withRuntimeContext<T>(action: () => T): T {
-    const activeContext = otelContext.active();
+  /**
+   * Mirrors the base handler's `runMap`: a start callback whose `parentRunId`
+   * this handler never observed gets no explicit parent span and falls back
+   * to the ambient OTEL context (`startAndRegisterOtelSpan`), so it needs the
+   * same foreign-span detachment as a true root. This happens whenever a
+   * handler is attached mid-graph — e.g. the per-agent handler created for a
+   * detached subagent's model invocations, whose surrounding graph runs were
+   * never traced.
+   */
+  private startsDetachedRun(runId: string, parentRunId?: string): boolean {
+    const detached =
+      parentRunId == null || !this.trackedRunIds.has(parentRunId);
+    this.trackedRunIds.add(runId);
+    return detached;
+  }
+
+  /**
+   * Whether the ambient runtime scope belongs to a different run — or, for
+   * per-agent overlay scopes, to a different concurrently executing agent of
+   * the same run than the one this callback reports via its inherited
+   * `langgraph_node` metadata. Unstamped scopes on unstamped handlers are
+   * never foreign (host-managed handler semantics).
+   */
+  private isForeignScope(
+    scopeRunId: string | undefined,
+    scopeAgentId: string | undefined,
+    callbackMetadata?: Record<string, unknown>
+  ): boolean {
+    if (this.runId == null || scopeRunId == null) {
+      return false;
+    }
+    if (scopeRunId !== this.runId) {
+      return true;
+    }
+    if (scopeAgentId == null) {
+      return false;
+    }
+    // Explicit agent identity (stamped into invoke metadata by the graph's
+    // model path and ToolNode) is unambiguous; node names are a fallback —
+    // an agent literally named `agent=research` makes its outer node
+    // indistinguishable from agent `research`'s inner model node.
+    for (const key of AGENT_ID_METADATA_KEYS) {
+      const explicitAgentId = callbackMetadata?.[key];
+      if (typeof explicitAgentId === 'string' && explicitAgentId !== '') {
+        return explicitAgentId !== scopeAgentId;
+      }
+    }
+    const callbackNode = getCallbackNode(callbackMetadata);
+    return (
+      callbackNode != null &&
+      !callbackNodeMatchesAgent(callbackNode, scopeAgentId)
+    );
+  }
+
+  /**
+   * LangChain executes non-awaited callbacks on a process-wide background
+   * queue (`consumeCallback`), so this callback may be running inside a
+   * DIFFERENT concurrent run's async context. The ambient runtime scope is
+   * therefore only adopted when it belongs to this handler's run (and, for
+   * agent sub-scopes, to this callback's agent): scopes are stamped at their
+   * call sites, and a foreign stamp means the scope's config would route
+   * spans to the wrong destination, its seed would collapse this run's spans
+   * into the foreign trace, and its tool-output policy could leak output the
+   * foreign run permits but this run redacts — so config, seed, AND redaction
+   * policy all fall back to this handler's own run. Unstamped scopes on
+   * unstamped handlers keep scope-first semantics (agent overlays and
+   * per-path seeds like the title/label scopes, host-managed handlers).
+   *
+   * Detached runs (roots, or starts whose parent this handler never tracked)
+   * take their span parent from the ambient OTEL context, so drop any
+   * foreign ambient span first — a run launched from a host's instrumented
+   * request context must start its own trace, not join an unexported
+   * foreign one.
+   */
+  private withRuntimeContext<T>(
+    action: () => T,
+    isDetachedRun = false,
+    callbackMetadata?: Record<string, unknown>
+  ): T {
+    const currentContext = otelContext.active();
+    const scopeRunId = resolveLangfuseScopeRunId(currentContext);
+    const scopeAgentId = resolveLangfuseScopeAgentId(currentContext);
+    if (this.isForeignScope(scopeRunId, scopeAgentId, callbackMetadata)) {
+      return this.withForeignScopeRejected(action);
+    }
     const langfuse =
-      resolveLangfuseConfigForSpan(activeContext) ?? this.langfuse;
-    const seed = this.getDeterministicTraceSeed();
-    return withLangfuseRuntimeScope(
-      {
-        langfuse,
-        traceIdSeed: resolveTraceIdSeedForSpan(activeContext) ?? seed,
-      },
-      action
+      resolveLangfuseConfigForSpan(currentContext) ?? this.langfuse;
+    const activeContext = isDetachedRun
+      ? detachForeignAmbientSpan(
+        currentContext,
+        resolveLangfuseDestinationKey(langfuse)
+      )
+      : currentContext;
+    const scoped = (): T =>
+      withLangfuseRuntimeScope(
+        {
+          langfuse,
+          traceIdSeed:
+            resolveTraceIdSeedForSpan(activeContext) ??
+            this.getDeterministicTraceSeed(),
+          runId: scopeRunId ?? this.runId,
+        },
+        action
+      );
+    return activeContext === currentContext
+      ? scoped()
+      : otelContext.with(activeContext, scoped);
+  }
+
+  /**
+   * A foreign concurrent run's context must be replaced wholesale, not
+   * merged: this library's scope keys (config, seed, tool-output policy,
+   * identity stamps) via the replace-mode runtime scope, `@langfuse/tracing`'s
+   * propagated trace attributes (userId, sessionId, tags, metadata, …) by
+   * deleting their context keys and re-propagating this handler's own
+   * identity, and the foreign active span — removed both so detached runs
+   * root their own trace and so `propagateAttributes` cannot stamp this
+   * run's identity onto the foreign run's still-recording span.
+   */
+  private withForeignScopeRejected<T>(action: () => T): T {
+    let cleanContext = otelTrace.deleteSpan(otelContext.active());
+    for (const key of Object.values(LangfuseOtelContextKeys)) {
+      cleanContext = cleanContext.deleteValue(key);
+    }
+    const scoped = (): T =>
+      withLangfuseRuntimeScope(
+        {
+          langfuse: this.langfuse,
+          traceIdSeed: this.getDeterministicTraceSeed(),
+          runId: this.runId,
+          toolOutputTracing:
+            this.toolOutputTracing ??
+            resolveToolOutputTracingConfig(this.langfuse),
+        },
+        action,
+        { replace: true }
+      );
+    const { userId, sessionId, tags, metadata, traceName } = this.identity;
+    const hasIdentity =
+      userId != null ||
+      sessionId != null ||
+      metadata != null ||
+      traceName != null ||
+      (tags?.length ?? 0) > 0;
+    return otelContext.with(cleanContext, () =>
+      hasIdentity
+        ? propagateAttributes(
+          { userId, sessionId, tags, metadata, traceName },
+          scoped
+        )
+        : scoped()
     );
   }
 
@@ -206,7 +474,11 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleChainStart(
     ...args: Parameters<CallbackHandler['handleChainStart']>
   ): ReturnType<CallbackHandler['handleChainStart']> {
-    return this.withRuntimeContext(() => super.handleChainStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleChainStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[5]
+    );
   }
 
   override handleChainError(
@@ -233,25 +505,40 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleAgentAction(
     ...args: Parameters<CallbackHandler['handleAgentAction']>
   ): ReturnType<CallbackHandler['handleAgentAction']> {
-    return this.withRuntimeContext(() => super.handleAgentAction(...args));
+    return this.withRuntimeContext(
+      () => super.handleAgentAction(...args),
+      this.startsDetachedRun(args[1], args[2])
+    );
   }
 
   override handleGenerationStart(
     ...args: Parameters<CallbackHandler['handleGenerationStart']>
   ): ReturnType<CallbackHandler['handleGenerationStart']> {
-    return this.withRuntimeContext(() => super.handleGenerationStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleGenerationStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[6]
+    );
   }
 
   override handleChatModelStart(
     ...args: Parameters<CallbackHandler['handleChatModelStart']>
   ): ReturnType<CallbackHandler['handleChatModelStart']> {
-    return this.withRuntimeContext(() => super.handleChatModelStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleChatModelStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[6]
+    );
   }
 
   override handleLLMStart(
     ...args: Parameters<CallbackHandler['handleLLMStart']>
   ): ReturnType<CallbackHandler['handleLLMStart']> {
-    return this.withRuntimeContext(() => super.handleLLMStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleLLMStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[6]
+    );
   }
 
   override handleLLMEnd(
@@ -269,7 +556,11 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleToolStart(
     ...args: Parameters<CallbackHandler['handleToolStart']>
   ): ReturnType<CallbackHandler['handleToolStart']> {
-    return this.withRuntimeContext(() => super.handleToolStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleToolStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[5]
+    );
   }
 
   override handleToolError(
@@ -289,7 +580,11 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleRetrieverStart(
     ...args: Parameters<CallbackHandler['handleRetrieverStart']>
   ): ReturnType<CallbackHandler['handleRetrieverStart']> {
-    return this.withRuntimeContext(() => super.handleRetrieverStart(...args));
+    return this.withRuntimeContext(
+      () => super.handleRetrieverStart(...args),
+      this.startsDetachedRun(args[2], args[3]),
+      args[5]
+    );
   }
 }
 
@@ -309,19 +604,6 @@ function hasLangfuseTraceAttributes(langfuse?: t.LangfuseConfig): boolean {
   );
 }
 
-export function hasLangfuseConfigCredentials(
-  langfuse?: t.LangfuseConfig
-): langfuse is t.LangfuseConfig & {
-  publicKey: string;
-  secretKey: string;
-} {
-  return (
-    langfuse != null &&
-    isPresent(langfuse.publicKey) &&
-    isPresent(langfuse.secretKey)
-  );
-}
-
 function hasLangfuseConfigBaseUrl(langfuse?: t.LangfuseConfig): boolean {
   return isPresent(langfuse?.baseUrl);
 }
@@ -425,17 +707,6 @@ export function getLangfuseTraceName(
   return isPresent(agentName) ? `${fallback}: ${agentName}` : fallback;
 }
 
-export function hasLangfuseEnvConfig(): boolean {
-  return hasLangfuseEnvCredentials();
-}
-
-export function hasLangfuseEnvCredentials(): boolean {
-  return (
-    isPresent(process.env.LANGFUSE_SECRET_KEY) &&
-    isPresent(process.env.LANGFUSE_PUBLIC_KEY)
-  );
-}
-
 export function shouldCreateLangfuseHandler(
   langfuse?: t.LangfuseConfig
 ): boolean {
@@ -462,6 +733,9 @@ export function createLangfuseHandler({
   traceMetadata,
   tags,
   traceIdSeed,
+  runId,
+  toolOutputTracing,
+  traceName,
 }: AgentLangfuseHandlerParams): CallbackHandler | undefined {
   if (!shouldCreateLangfuseHandler(langfuse)) {
     return undefined;
@@ -476,6 +750,9 @@ export function createLangfuseHandler({
     tags: mergeLangfuseTags(tags, langfuse?.tags),
     langfuse,
     traceIdSeed,
+    runId,
+    toolOutputTracing,
+    traceName,
   });
 }
 

package/src/langfuseConfig.ts

@@ -12,6 +12,30 @@ export function normalizeToolName(name: string): string {
   return name.trim().toLowerCase();
 }
 
+export function hasLangfuseConfigCredentials(
+  langfuse?: t.LangfuseConfig
+): langfuse is t.LangfuseConfig & {
+  publicKey: string;
+  secretKey: string;
+} {
+  return (
+    langfuse != null &&
+    isPresent(langfuse.publicKey) &&
+    isPresent(langfuse.secretKey)
+  );
+}
+
+export function hasLangfuseEnvCredentials(): boolean {
+  return (
+    isPresent(process.env.LANGFUSE_SECRET_KEY) &&
+    isPresent(process.env.LANGFUSE_PUBLIC_KEY)
+  );
+}
+
+export function hasLangfuseEnvConfig(): boolean {
+  return hasLangfuseEnvCredentials();
+}
+
 function normalizeToolNames(names: string[] | undefined): Set<string> {
   const normalized = new Set<string>();
   for (const name of names ?? []) {

package/src/langfuseRuntimeContext.ts

@@ -13,6 +13,22 @@ export type LangfuseRuntimeContext = {
   langfuse?: t.LangfuseConfig;
   traceIdSeed?: string;
   toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
+  /**
+   * Identity of the run this scope belongs to. LangChain executes
+   * non-awaited callbacks on a shared background queue
+   * (`@langchain/core` `consumeCallback`, a process-wide `p-queue` with
+   * concurrency 1), so a callback can run inside a DIFFERENT concurrent
+   * run's async context. Handlers compare this id against their own run to
+   * decide whether an ambient scope is theirs to adopt.
+   */
+  runId?: string;
+  /**
+   * Identity of the agent whose overlay this scope carries, for per-agent
+   * scopes inside a run. Fan-out agents execute concurrently with distinct
+   * Langfuse overlays, so handlers additionally compare this against the
+   * agent a callback reports via its inherited `langgraph_node` metadata.
+   */
+  agentId?: string;
 };
 
 const langfuseRuntimeContextStore =
@@ -28,6 +44,8 @@ export function hasLangfuseRuntimeContextValue(
   return (
     context.langfuse != null ||
     hasText(context.traceIdSeed) ||
+    hasText(context.runId) ||
+    hasText(context.agentId) ||
     context.toolOutputTracing != null
   );
 }
@@ -51,6 +69,14 @@ export function getTraceIdSeed(): string | undefined {
   return getLangfuseRuntimeContext()?.traceIdSeed;
 }
 
+export function getLangfuseScopeRunId(): string | undefined {
+  return getLangfuseRuntimeContext()?.runId;
+}
+
+export function getLangfuseScopeAgentId(): string | undefined {
+  return getLangfuseRuntimeContext()?.agentId;
+}
+
 export function getLangfuseRuntimeToolOutputTracingConfig():
   | ResolvedLangfuseToolOutputTracingConfig
   | undefined {
@@ -60,7 +86,8 @@ export function getLangfuseRuntimeToolOutputTracingConfig():
 /**
  * Runs `fn` with a merged Langfuse runtime context. Undefined fields inherit
  * from the parent scope; callers intentionally cannot clear parent values by
- * passing `undefined`.
+ * passing `undefined` — use `replaceLangfuseRuntimeContext` when the parent
+ * scope must NOT leak through (a foreign concurrent run's scope).
  */
 export function runWithLangfuseRuntimeContext<T>(
   context: LangfuseRuntimeContext,
@@ -73,6 +100,8 @@ export function runWithLangfuseRuntimeContext<T>(
     ...(hasText(context.traceIdSeed)
       ? { traceIdSeed: context.traceIdSeed }
       : {}),
+    ...(hasText(context.runId) ? { runId: context.runId } : {}),
+    ...(hasText(context.agentId) ? { agentId: context.agentId } : {}),
     ...(context.toolOutputTracing !== undefined
       ? { toolOutputTracing: context.toolOutputTracing }
       : {}),
@@ -83,6 +112,19 @@ export function runWithLangfuseRuntimeContext<T>(
     : fn();
 }
 
+/**
+ * Runs `fn` with EXACTLY the provided context — the surrounding scope's
+ * fields do not leak through. A rejected foreign run's explicit destination
+ * or seed must not survive via merge inheritance when this run has none of
+ * its own (env-credential runs, non-deterministic runs).
+ */
+export function replaceLangfuseRuntimeContext<T>(
+  context: LangfuseRuntimeContext,
+  fn: () => T
+): T {
+  return langfuseRuntimeContextStore.run({ ...context }, fn);
+}
+
 export function runWithTraceIdSeed<T>(
   seed: string | undefined,
   fn: () => T