@librechat/agents 3.6.7 → 3.6.8

package/src/instrumentation.ts

@@ -16,9 +16,12 @@ import {
   getLangfuseDestinationKey,
   getLangfuseSpanProcessorParams,
   registerLangfuseManagedSpan,
+  registerLangfuseTraceAnchorSpan,
 } from '@/langfuseSpanRegistry';
 import {
   resolveLangfuseConfigForSpan,
+  resolveLangfuseScopeAgentId,
+  resolveLangfuseTraceAnchor,
   resolveTraceIdSeedForSpan,
 } from '@/langfuseRuntimeScope';
 import { createLangfuseSpanProcessor } from '@/langfuseToolOutputTracing';
@@ -137,6 +140,15 @@ class RoutingLangfuseSpanProcessor implements SpanProcessor {
       langfuse
     );
     registerLangfuseManagedSpan(span, destinationKey);
+    const traceAnchor = resolveLangfuseTraceAnchor(parentContext);
+    if (traceAnchor != null) {
+      registerLangfuseTraceAnchorSpan(
+        traceAnchor,
+        span,
+        destinationKey,
+        resolveLangfuseScopeAgentId(parentContext)
+      );
+    }
 
     const librechatTraceAttributes = createLibreChatTraceAttributes(
       langfuse?.librechatTraceAttributes ?? {}

package/src/langfuse.ts

@@ -18,7 +18,7 @@ import type {
   LLMResult,
 } from '@langchain/core/outputs';
 import type { PropagateAttributesParams } from '@langfuse/tracing';
-import type { Context } from '@opentelemetry/api';
+import type { Context, SpanContext } from '@opentelemetry/api';
 import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
 import type * as t from '@/types';
 import {
@@ -36,6 +36,7 @@ import {
 } from '@/langfuseConfig';
 import {
   getLangfuseManagedSpanDestination,
+  registerLangfuseManagedSpan,
   resolveLangfuseDestinationKey,
 } from '@/langfuseSpanRegistry';
 import { isPresent, parseBooleanEnv } from '@/utils/misc';
@@ -66,6 +67,14 @@ type LangfuseHandlerParams = {
   traceMetadata?: LangfuseTraceMetadata;
   tags?: string[];
   traceIdSeed?: string;
+  /** Opaque key used by the span processor to capture this run's parents. */
+  traceAnchor?: object;
+  /** Agent lane this handler owns when ambient callback scope is unavailable. */
+  agentId?: string;
+  /** Exported observation that auxiliary work should be nested beneath. */
+  parentSpanContext?: SpanContext;
+  /** Keep an existing parent trace's user, session, name, and metadata. */
+  inheritTraceIdentity?: boolean;
   /** Identity of the run this handler traces; ambient runtime scopes are
    *  only adopted when stamped with the same run (see
    *  `LangfuseRuntimeContext.runId`). */
@@ -251,7 +260,7 @@ function callbackNodeMatchesAgent(node: string, agentId: string): boolean {
  * 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
+ * Langfuse, which orphans the trace root (root-observation 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,
@@ -280,6 +289,9 @@ function detachForeignAmbientSpan(
 class ScopedLangfuseCallbackHandler extends CallbackHandler {
   private readonly langfuse?: t.LangfuseConfig;
   private readonly traceIdSeed?: string;
+  private readonly traceAnchor?: object;
+  private readonly agentId?: string;
+  private readonly parentSpanContext?: SpanContext;
   private readonly runId?: string;
   private readonly identity: HandlerIdentity;
   private readonly toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
@@ -289,22 +301,40 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     const {
       langfuse,
       traceIdSeed,
+      traceAnchor,
+      agentId,
+      parentSpanContext,
+      inheritTraceIdentity,
       runId,
       toolOutputTracing,
       traceName,
       ...handlerParams
     } = params ?? {};
-    super(handlerParams);
+    super({
+      ...handlerParams,
+      ...(inheritTraceIdentity === true
+        ? {
+          userId: undefined,
+          sessionId: undefined,
+          traceMetadata: undefined,
+        }
+        : {}),
+    });
     this.langfuse = langfuse;
     this.traceIdSeed = traceIdSeed;
+    this.traceAnchor = traceAnchor;
+    this.agentId = agentId;
+    this.parentSpanContext = parentSpanContext;
     this.runId = runId;
     this.toolOutputTracing = toolOutputTracing;
     this.identity = {
-      userId: handlerParams.userId,
-      sessionId: handlerParams.sessionId,
+      userId: inheritTraceIdentity === true ? undefined : handlerParams.userId,
+      sessionId:
+        inheritTraceIdentity === true ? undefined : handlerParams.sessionId,
       tags: handlerParams.tags,
-      metadata: handlerParams.traceMetadata,
-      traceName,
+      metadata:
+        inheritTraceIdentity === true ? undefined : handlerParams.traceMetadata,
+      traceName: inheritTraceIdentity === true ? undefined : traceName,
     };
   }
 
@@ -314,6 +344,22 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
       : undefined;
   }
 
+  private applyExplicitParent(
+    activeContext: Context,
+    langfuse?: t.LangfuseConfig
+  ): Context {
+    if (this.parentSpanContext == null) {
+      return activeContext;
+    }
+    const destinationKey = resolveLangfuseDestinationKey(langfuse);
+    if (destinationKey == null) {
+      return activeContext;
+    }
+    const parentSpan = otelTrace.wrapSpanContext(this.parentSpanContext);
+    registerLangfuseManagedSpan(parentSpan, destinationKey);
+    return otelTrace.setSpan(activeContext, parentSpan);
+  }
+
   /**
    * Mirrors the base handler's `runMap`: a start callback whose `parentRunId`
    * this handler never observed gets no explicit parent span and falls back
@@ -401,12 +447,15 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     }
     const langfuse =
       resolveLangfuseConfigForSpan(currentContext) ?? this.langfuse;
+    const parentedContext = isDetachedRun
+      ? this.applyExplicitParent(currentContext, langfuse)
+      : currentContext;
     const activeContext = isDetachedRun
       ? detachForeignAmbientSpan(
-        currentContext,
+        parentedContext,
         resolveLangfuseDestinationKey(langfuse)
       )
-      : currentContext;
+      : parentedContext;
     const scoped = (): T =>
       withLangfuseRuntimeScope(
         {
@@ -414,7 +463,9 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
           traceIdSeed:
             resolveTraceIdSeedForSpan(activeContext) ??
             this.getDeterministicTraceSeed(),
+          traceAnchor: this.traceAnchor,
           runId: scopeRunId ?? this.runId,
+          agentId: scopeAgentId ?? this.agentId,
         },
         action
       );
@@ -438,12 +489,15 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     for (const key of Object.values(LangfuseOtelContextKeys)) {
       cleanContext = cleanContext.deleteValue(key);
     }
+    cleanContext = this.applyExplicitParent(cleanContext, this.langfuse);
     const scoped = (): T =>
       withLangfuseRuntimeScope(
         {
           langfuse: this.langfuse,
           traceIdSeed: this.getDeterministicTraceSeed(),
+          traceAnchor: this.traceAnchor,
           runId: this.runId,
+          agentId: this.agentId,
           toolOutputTracing:
             this.toolOutputTracing ??
             resolveToolOutputTracingConfig(this.langfuse),
@@ -733,6 +787,10 @@ export function createLangfuseHandler({
   traceMetadata,
   tags,
   traceIdSeed,
+  traceAnchor,
+  agentId,
+  parentSpanContext,
+  inheritTraceIdentity,
   runId,
   toolOutputTracing,
   traceName,
@@ -743,13 +801,17 @@ export function createLangfuseHandler({
   return new ScopedLangfuseCallbackHandler({
     userId,
     sessionId,
-    traceMetadata: mergeLangfuseTraceMetadata(
-      traceMetadata,
-      langfuse?.metadata
-    ),
+    traceMetadata:
+      inheritTraceIdentity === true
+        ? undefined
+        : mergeLangfuseTraceMetadata(traceMetadata, langfuse?.metadata),
     tags: mergeLangfuseTags(tags, langfuse?.tags),
     langfuse,
     traceIdSeed,
+    traceAnchor,
+    agentId,
+    parentSpanContext,
+    inheritTraceIdentity,
     runId,
     toolOutputTracing,
     traceName,
@@ -763,13 +825,17 @@ function createPropagateAttributeParams({
   traceMetadata,
   traceName,
   tags,
+  inheritTraceIdentity,
 }: LangfuseAttributeParams): PropagateAttributesParams {
   return {
-    userId,
-    sessionId,
-    traceName,
+    userId: inheritTraceIdentity === true ? undefined : userId,
+    sessionId: inheritTraceIdentity === true ? undefined : sessionId,
+    traceName: inheritTraceIdentity === true ? undefined : traceName,
     tags: mergeLangfuseTags(tags, langfuse?.tags),
-    metadata: mergeLangfuseTraceMetadata(traceMetadata, langfuse?.metadata),
+    metadata:
+      inheritTraceIdentity === true
+        ? undefined
+        : mergeLangfuseTraceMetadata(traceMetadata, langfuse?.metadata),
   };
 }
 

package/src/langfuseOperation.ts

@@ -0,0 +1,2 @@
+/** Internal observation metadata key used to distinguish SDK operations from public tags. */
+export const LANGFUSE_OPERATION_METADATA_KEY = 'librechat.sdk.operation';

package/src/langfuseRuntimeContext.ts

@@ -12,6 +12,8 @@ export type ResolvedLangfuseToolOutputTracingConfig = {
 export type LangfuseRuntimeContext = {
   langfuse?: t.LangfuseConfig;
   traceIdSeed?: string;
+  /** Opaque run-owned key used to recover the exported trace parent. */
+  traceAnchor?: object;
   toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
   /**
    * Identity of the run this scope belongs to. LangChain executes
@@ -44,6 +46,7 @@ export function hasLangfuseRuntimeContextValue(
   return (
     context.langfuse != null ||
     hasText(context.traceIdSeed) ||
+    context.traceAnchor != null ||
     hasText(context.runId) ||
     hasText(context.agentId) ||
     context.toolOutputTracing != null
@@ -100,6 +103,9 @@ export function runWithLangfuseRuntimeContext<T>(
     ...(hasText(context.traceIdSeed)
       ? { traceIdSeed: context.traceIdSeed }
       : {}),
+    ...(context.traceAnchor != null
+      ? { traceAnchor: context.traceAnchor }
+      : {}),
     ...(hasText(context.runId) ? { runId: context.runId } : {}),
     ...(hasText(context.agentId) ? { agentId: context.agentId } : {}),
     ...(context.toolOutputTracing !== undefined

package/src/langfuseRuntimeScope.ts

@@ -7,6 +7,7 @@ import type {
 import type * as t from '@/types';
 import {
   getLangfuseRuntimeConfig,
+  getLangfuseRuntimeContext,
   getLangfuseRuntimeToolOutputTracingConfig,
   getLangfuseScopeAgentId,
   getLangfuseScopeRunId,
@@ -27,6 +28,7 @@ export type ResolveLangfuseRuntimeScopeParams = {
   runLangfuse?: t.LangfuseConfig;
   langfuseOverlay?: t.LangfuseConfig;
   traceIdSeed?: string;
+  traceAnchor?: object;
   runId?: string;
   agentId?: string;
 };
@@ -46,6 +48,9 @@ const langfuseConfigKey = createContextKey('librechat.langfuse.config');
 const langfuseTraceIdSeedKey = createContextKey(
   'librechat.langfuse.trace-id-seed'
 );
+const langfuseTraceAnchorKey = createContextKey(
+  'librechat.langfuse.trace-anchor'
+);
 const langfuseScopeRunIdKey = createContextKey('librechat.langfuse.run-id');
 const langfuseScopeAgentIdKey = createContextKey('librechat.langfuse.agent-id');
 
@@ -69,6 +74,17 @@ export function getOtelTraceIdSeed(activeContext: Context): string | undefined {
   return typeof value === 'string' && value.trim() !== '' ? value : undefined;
 }
 
+export function resolveLangfuseTraceAnchor(
+  activeContext: Context
+): object | undefined {
+  const runtimeAnchor = getLangfuseRuntimeContext()?.traceAnchor;
+  if (runtimeAnchor != null) {
+    return runtimeAnchor;
+  }
+  const value = activeContext.getValue(langfuseTraceAnchorKey);
+  return typeof value === 'object' && value != null ? value : undefined;
+}
+
 export function getOtelToolOutputTracingConfig(
   activeContext: Context
 ): ResolvedLangfuseToolOutputTracingConfig | undefined {
@@ -166,6 +182,12 @@ export function withLangfuseRuntimeScope<T>(
     hasText(scope.traceIdSeed) ? scope.traceIdSeed : undefined,
     replace
   );
+  activeContext = setOrClearContextValue(
+    activeContext,
+    langfuseTraceAnchorKey,
+    scope.traceAnchor,
+    replace
+  );
   activeContext = setOrClearContextValue(
     activeContext,
     langfuseScopeRunIdKey,
@@ -194,6 +216,7 @@ export function resolveLangfuseRuntimeScope({
   runLangfuse,
   langfuseOverlay,
   traceIdSeed,
+  traceAnchor,
   runId,
   agentId,
 }: ResolveLangfuseRuntimeScopeParams): LangfuseRuntimeScope {
@@ -204,5 +227,12 @@ export function resolveLangfuseRuntimeScope({
   )
     ? undefined
     : resolveToolOutputTracingConfig(runLangfuse, langfuseOverlay);
-  return { langfuse, traceIdSeed, toolOutputTracing, runId, agentId };
+  return {
+    langfuse,
+    traceIdSeed,
+    traceAnchor,
+    toolOutputTracing,
+    runId,
+    agentId,
+  };
 }

package/src/langfuseSpanRegistry.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
+import { context, trace } from '@opentelemetry/api';
 import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
-import type { Span } from '@opentelemetry/api';
+import type { Span, SpanContext } from '@opentelemetry/api';
 import type * as t from '@/types';
 import {
   hasLangfuseConfigCredentials,
@@ -16,7 +17,7 @@ import { isPresent } from '@/utils/misc';
  *
  * - Foreign spans (a host's own OpenTelemetry instrumentation, e.g. HTTP
  *   server spans on the global provider) are never exported to Langfuse —
- *   inheriting one orphans the trace root (its root/trace input-output
+ *   inheriting one orphans the trace root (its root-observation input/output
  *   shaping is skipped), collapses concurrent runs inside one request
  *   context into a single merged trace, and bypasses the seeded
  *   deterministic trace id generator.
@@ -30,6 +31,19 @@ import { isPresent } from '@/utils/misc';
  */
 const managedSpanDestinations = new WeakMap<Span, string>();
 
+type AnchoredSpan = {
+  destinationKey: string;
+  spanContext: SpanContext;
+};
+
+type TraceAnchorState = {
+  spans: Map<string, AnchoredSpan>;
+  spanIds: Set<string>;
+};
+
+const ROOT_TRACE_ANCHOR = '';
+const traceAnchorStates = new WeakMap<object, TraceAnchorState>();
+
 export function registerLangfuseManagedSpan(
   span: Span,
   destinationKey: string
@@ -43,6 +57,68 @@ export function getLangfuseManagedSpanDestination(
   return managedSpanDestinations.get(span);
 }
 
+/** Captures the first exported observation for a run and for each agent lane. */
+export function registerLangfuseTraceAnchorSpan(
+  anchor: object,
+  span: Span,
+  destinationKey: string,
+  agentId?: string
+): void {
+  let state = traceAnchorStates.get(anchor);
+  if (state == null) {
+    state = { spans: new Map<string, AnchoredSpan>(), spanIds: new Set() };
+    traceAnchorStates.set(anchor, state);
+  }
+  const spanContext = span.spanContext();
+  state.spanIds.add(spanContext.spanId);
+  const key = agentId ?? ROOT_TRACE_ANCHOR;
+  if (state.spans.has(key)) {
+    return;
+  }
+  state.spans.set(key, { destinationKey, spanContext });
+}
+
+/**
+ * Resolves the most specific safe parent available for auxiliary work. An
+ * active observation wins so labels emitted inside a tool or reasoning step
+ * stay beside their source; otherwise the run root anchors the label in the
+ * same trace. An agent lane is the fallback when its overlay exports to a
+ * different destination. Cross-destination parents are never returned.
+ */
+export function resolveLangfuseTraceAnchorParent(
+  anchor: object | undefined,
+  destinationKey: string | undefined,
+  agentId?: string
+): SpanContext | undefined {
+  if (anchor == null || destinationKey == null) {
+    return undefined;
+  }
+  const state = traceAnchorStates.get(anchor);
+  if (state == null) {
+    return undefined;
+  }
+  const agentSpan = agentId == null ? undefined : state.spans.get(agentId);
+  const rootSpan = state.spans.get(ROOT_TRACE_ANCHOR);
+  let anchoredSpan = rootSpan;
+  if (anchoredSpan?.destinationKey !== destinationKey) {
+    anchoredSpan = agentSpan;
+  }
+  if (anchoredSpan?.destinationKey !== destinationKey) {
+    return undefined;
+  }
+
+  const activeSpan = trace.getSpan(context.active());
+  if (
+    activeSpan != null &&
+    getLangfuseManagedSpanDestination(activeSpan) === destinationKey &&
+    activeSpan.spanContext().traceId === anchoredSpan.spanContext.traceId &&
+    state.spanIds.has(activeSpan.spanContext().spanId)
+  ) {
+    return activeSpan.spanContext();
+  }
+  return anchoredSpan.spanContext;
+}
+
 function resolveLangfuseEnvironment(
   langfuse?: t.LangfuseConfig
 ): string | undefined {

package/src/langfuseToolOutputTracing.ts

@@ -779,8 +779,6 @@ export function redactLangfuseSpanToolOutputs(
   for (const key of [
     LangfuseOtelSpanAttributes.OBSERVATION_INPUT,
     LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT,
-    LangfuseOtelSpanAttributes.TRACE_INPUT,
-    LangfuseOtelSpanAttributes.TRACE_OUTPUT,
   ]) {
     redactAttribute(attributes, key, config);
   }