@librechat/agents 3.2.44 → 3.2.45

package/src/langfuseToolOutputTracing.ts

@@ -1,6 +1,4 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
-import { context, createContextKey } from '@opentelemetry/api';
 import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
 import type {
   ReadableSpan,
@@ -9,17 +7,19 @@ import type {
 } from '@opentelemetry/sdk-trace-base';
 import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
 import type { Context } from '@opentelemetry/api';
+import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
 import type * as t from '@/types';
+import {
+  LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT,
+  hasToolOutputTracingConfig,
+  normalizeToolName,
+  resolveLangfuseConfig,
+  resolveToolOutputTracingConfig,
+} from '@/langfuseConfig';
+import { resolveToolOutputTracingConfigForSpan } from '@/langfuseRuntimeScope';
 
-export const LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = '[tool output redacted]';
+export { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig };
 
-const langfuseToolOutputTracingConfigKey = createContextKey(
-  'librechat.langfuse.tool-output-tracing'
-);
-const langfuseConfigKey = createContextKey('librechat.langfuse.config');
-const toolOutputTracingStorage =
-  new AsyncLocalStorage<ResolvedLangfuseToolOutputTracingConfig>();
-const langfuseConfigStorage = new AsyncLocalStorage<t.LangfuseConfig>();
 const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
 
 const CHAT_ROLES = new Set([
@@ -30,13 +30,6 @@ const CHAT_ROLES = new Set([
   'user',
 ]);
 
-export type ResolvedLangfuseToolOutputTracingConfig = {
-  enabled: boolean;
-  redactedToolNames: Set<string>;
-  redactedToolNameMatchMode: 'exact' | 'partial';
-  redactionText: string;
-};
-
 type SpanWithAttributes = ReadableSpan & {
   attributes: Record<string, unknown>;
 };
@@ -60,122 +53,6 @@ function isPresent(value: unknown): value is string {
   return typeof value === 'string' && value.trim() !== '';
 }
 
-function parseBoolean(value: string | undefined): boolean | undefined {
-  if (value == null) {
-    return undefined;
-  }
-
-  const normalized = value.trim().toLowerCase();
-  if (['1', 'true', 'yes', 'on'].includes(normalized)) {
-    return true;
-  }
-  if (['0', 'false', 'no', 'off'].includes(normalized)) {
-    return false;
-  }
-
-  return undefined;
-}
-
-function normalizeToolName(name: string): string {
-  return name.trim().toLowerCase();
-}
-
-function normalizeToolNames(names: string[] | undefined): Set<string> {
-  const normalized = new Set<string>();
-  for (const name of names ?? []) {
-    if (isPresent(name)) {
-      normalized.add(normalizeToolName(name));
-    }
-  }
-  return normalized;
-}
-
-function parseToolNames(value: string | undefined): string[] | undefined {
-  if (!isPresent(value)) {
-    return undefined;
-  }
-
-  return value
-    .split(',')
-    .map((name) => name.trim())
-    .filter((name) => name !== '');
-}
-
-function getEnvToolOutputTracingEnabled(): boolean | undefined {
-  const traceToolOutputs = parseBoolean(
-    process.env.LANGFUSE_TRACE_TOOL_OUTPUTS
-  );
-  if (traceToolOutputs != null) {
-    return traceToolOutputs;
-  }
-
-  const redactToolOutputs = parseBoolean(
-    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS
-  );
-  if (redactToolOutputs != null) {
-    return !redactToolOutputs;
-  }
-
-  return parseBoolean(process.env.LANGFUSE_TOOL_OUTPUT_TRACING_ENABLED);
-}
-
-function getEnvRedactedToolNames(): string[] | undefined {
-  return (
-    parseToolNames(process.env.LANGFUSE_REDACT_TOOL_OUTPUT_NAMES) ??
-    parseToolNames(process.env.LANGFUSE_REDACT_TOOL_NAMES)
-  );
-}
-
-function getEnvRedactionText(): string | undefined {
-  return isPresent(process.env.LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT)
-    ? process.env.LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT
-    : undefined;
-}
-
-function getEnvToolNameMatchMode(): 'exact' | 'partial' | undefined {
-  const mode = (
-    process.env.LANGFUSE_REDACT_TOOL_OUTPUT_NAME_MATCH_MODE ??
-    process.env.LANGFUSE_REDACT_TOOL_NAME_MATCH_MODE
-  )
-    ?.trim()
-    .toLowerCase();
-  if (mode === 'exact' || mode === 'partial') {
-    return mode;
-  }
-  return undefined;
-}
-
-function resolveToolOutputTracingConfig(
-  runLangfuse?: t.LangfuseConfig,
-  agentLangfuse?: t.LangfuseConfig
-): ResolvedLangfuseToolOutputTracingConfig {
-  const runConfig = runLangfuse?.toolOutputTracing;
-  const agentConfig = agentLangfuse?.toolOutputTracing;
-
-  return {
-    enabled:
-      agentConfig?.enabled ??
-      runConfig?.enabled ??
-      getEnvToolOutputTracingEnabled() ??
-      true,
-    redactedToolNames: normalizeToolNames(
-      agentConfig?.redactedToolNames ??
-        runConfig?.redactedToolNames ??
-        getEnvRedactedToolNames()
-    ),
-    redactedToolNameMatchMode:
-      agentConfig?.redactedToolNameMatchMode ??
-      runConfig?.redactedToolNameMatchMode ??
-      getEnvToolNameMatchMode() ??
-      'exact',
-    redactionText:
-      agentConfig?.redactionText ??
-      runConfig?.redactionText ??
-      getEnvRedactionText() ??
-      LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT,
-  };
-}
-
 function shouldApplyToolOutputRedaction(
   config: ResolvedLangfuseToolOutputTracingConfig
 ): boolean {
@@ -467,6 +344,10 @@ function classifyLangGraphToolNodeSpan(
   }
 }
 
+export function classifyLangfuseToolNodeSpan(span: ReadableSpan): void {
+  classifyLangGraphToolNodeSpan((span as SpanWithAttributes).attributes);
+}
+
 function redactToolObservationOutput(
   span: ReadableSpan,
   attributes: Record<string, unknown>,
@@ -491,7 +372,7 @@ export function redactLangfuseSpanToolOutputs(
   config: ResolvedLangfuseToolOutputTracingConfig
 ): void {
   const attributes = (span as SpanWithAttributes).attributes;
-  classifyLangGraphToolNodeSpan(attributes);
+  classifyLangfuseToolNodeSpan(span);
 
   if (!shouldApplyToolOutputRedaction(config)) {
     return;
@@ -509,32 +390,6 @@ export function redactLangfuseSpanToolOutputs(
   }
 }
 
-function getContextToolOutputTracingConfig(
-  activeContext: Context
-): ResolvedLangfuseToolOutputTracingConfig | undefined {
-  const asyncConfig = toolOutputTracingStorage.getStore();
-  if (asyncConfig != null) {
-    return asyncConfig;
-  }
-
-  const value = activeContext.getValue(langfuseToolOutputTracingConfigKey);
-  return isRecord(value)
-    ? (value as ResolvedLangfuseToolOutputTracingConfig)
-    : undefined;
-}
-
-export function getContextLangfuseConfig(
-  activeContext: Context
-): t.LangfuseConfig | undefined {
-  const asyncConfig = langfuseConfigStorage.getStore();
-  if (asyncConfig != null) {
-    return asyncConfig;
-  }
-
-  const value = activeContext.getValue(langfuseConfigKey);
-  return isRecord(value) ? (value as t.LangfuseConfig) : undefined;
-}
-
 class ToolOutputRedactingLangfuseSpanProcessor implements SpanProcessor {
   private readonly processor: LangfuseSpanProcessor;
   private readonly fallbackConfig?: ResolvedLangfuseToolOutputTracingConfig;
@@ -553,7 +408,8 @@ class ToolOutputRedactingLangfuseSpanProcessor implements SpanProcessor {
 
   onStart(span: Span, parentContext: Context): void {
     const config =
-      getContextToolOutputTracingConfig(parentContext) ?? this.fallbackConfig;
+      resolveToolOutputTracingConfigForSpan(parentContext) ??
+      this.fallbackConfig;
     if (config != null) {
       this.spanConfigs.set(span, config);
     }
@@ -561,12 +417,11 @@ class ToolOutputRedactingLangfuseSpanProcessor implements SpanProcessor {
   }
 
   onEnd(span: ReadableSpan): void {
-    const config =
-      this.spanConfigs.get(span) ??
-      toolOutputTracingStorage.getStore() ??
-      this.fallbackConfig ??
-      resolveToolOutputTracingConfig();
-    redactLangfuseSpanToolOutputs(span, config);
+    classifyLangfuseToolNodeSpan(span);
+    const config = this.spanConfigs.get(span) ?? this.fallbackConfig;
+    if (config != null) {
+      redactLangfuseSpanToolOutputs(span, config);
+    }
     this.processor.onEnd(span);
   }
 
@@ -584,52 +439,12 @@ export function createLangfuseSpanProcessor(
   runLangfuse?: t.LangfuseConfig,
   agentLangfuse?: t.LangfuseConfig
 ): SpanProcessor {
-  const fallbackConfig =
-    runLangfuse != null || agentLangfuse != null
-      ? resolveToolOutputTracingConfig(runLangfuse, agentLangfuse)
-      : undefined;
+  const fallbackConfig = hasToolOutputTracingConfig(runLangfuse, agentLangfuse)
+    ? resolveToolOutputTracingConfig(runLangfuse, agentLangfuse)
+    : undefined;
   return new ToolOutputRedactingLangfuseSpanProcessor(params, fallbackConfig);
 }
 
-export function withLangfuseToolOutputTracingConfig<T>(
-  runLangfuse: t.LangfuseConfig | undefined,
-  action: () => T,
-  agentLangfuse?: t.LangfuseConfig
-): T {
-  const langfuse = resolveLangfuseConfig(runLangfuse, agentLangfuse);
-  const hasNoToolOutputConfig =
-    runLangfuse?.toolOutputTracing == null &&
-    agentLangfuse?.toolOutputTracing == null;
-
-  if (langfuse == null && hasNoToolOutputConfig) {
-    return action();
-  }
-
-  const config = hasNoToolOutputConfig
-    ? undefined
-    : resolveToolOutputTracingConfig(runLangfuse, agentLangfuse);
-  let activeContext = context.active();
-  if (langfuse != null) {
-    activeContext = activeContext.setValue(langfuseConfigKey, langfuse);
-  }
-  if (config != null) {
-    activeContext = activeContext.setValue(
-      langfuseToolOutputTracingConfigKey,
-      config
-    );
-  }
-
-  const runWithContext = (): T => context.with(activeContext, action);
-  const runWithToolOutputConfig = (): T =>
-    config != null
-      ? toolOutputTracingStorage.run(config, runWithContext)
-      : runWithContext();
-
-  return langfuse != null
-    ? langfuseConfigStorage.run(langfuse, runWithToolOutputConfig)
-    : runWithToolOutputConfig();
-}
-
 function hasLangfuseEnvKeys(): boolean {
   return (
     isPresent(process.env.LANGFUSE_SECRET_KEY) &&
@@ -665,56 +480,3 @@ export function shouldTraceToolNodeForLangfuse({
 
   return hasLangfuseConfigKeys(langfuse) || hasLangfuseEnvKeys();
 }
-
-export function resolveLangfuseConfig(
-  runLangfuse?: t.LangfuseConfig,
-  agentLangfuse?: t.LangfuseConfig
-): t.LangfuseConfig | undefined {
-  if (runLangfuse == null) {
-    return agentLangfuse;
-  }
-  if (agentLangfuse == null) {
-    return runLangfuse;
-  }
-
-  const toolNodeTracing =
-    runLangfuse.toolNodeTracing != null || agentLangfuse.toolNodeTracing != null
-      ? {
-        ...runLangfuse.toolNodeTracing,
-        ...agentLangfuse.toolNodeTracing,
-      }
-      : undefined;
-  const toolOutputTracing =
-    runLangfuse.toolOutputTracing != null ||
-    agentLangfuse.toolOutputTracing != null
-      ? {
-        ...runLangfuse.toolOutputTracing,
-        ...agentLangfuse.toolOutputTracing,
-      }
-      : undefined;
-  const metadata =
-    runLangfuse.metadata != null || agentLangfuse.metadata != null
-      ? {
-        ...runLangfuse.metadata,
-        ...agentLangfuse.metadata,
-      }
-      : undefined;
-  const tags =
-    runLangfuse.tags != null || agentLangfuse.tags != null
-      ? [
-        ...new Set([
-          ...(runLangfuse.tags ?? []),
-          ...(agentLangfuse.tags ?? []),
-        ]),
-      ]
-      : undefined;
-
-  return {
-    ...runLangfuse,
-    ...agentLangfuse,
-    ...(metadata != null ? { metadata } : {}),
-    ...(tags != null ? { tags } : {}),
-    ...(toolNodeTracing != null ? { toolNodeTracing } : {}),
-    ...(toolOutputTracing != null ? { toolOutputTracing } : {}),
-  };
-}

package/src/run.ts

@@ -27,9 +27,9 @@ import {
   withLangfuseAttributes,
 } from '@/langfuse';
 import {
-  resolveLangfuseConfig,
-  withLangfuseToolOutputTracingConfig,
-} from '@/langfuseToolOutputTracing';
+  resolveLangfuseRuntimeScope,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
 import {
   appendCallbacks,
   findCallback,
@@ -39,13 +39,11 @@ import {
   createCompletionTitleRunnable,
   createTitleRunnable,
 } from '@/utils/title';
-import {
-  initializeLangfuseTracing,
-  runWithTraceIdSeed,
-} from './instrumentation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
+import { initializeLangfuseTracing } from './instrumentation';
 import { GraphEvents, Callback, TitleMethod } from '@/common';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { resolveLangfuseConfig } from '@/langfuseConfig';
 import { StandardGraph } from '@/graphs/Graph';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
@@ -746,6 +744,10 @@ export class Run<_T extends t.BaseGraphState> {
       sessionId,
       traceMetadata,
       tags: ['librechat', 'agent'],
+      traceIdSeed:
+        streamLangfuseConfig?.deterministicTraceId === true
+          ? this.id
+          : undefined,
     });
     if (langfuseHandler != null) {
       config.runName = traceName;
@@ -915,26 +917,26 @@ export class Run<_T extends t.BaseGraphState> {
       // When opted in, seed the root trace id from this run's id so feedback /
       // other external signals can be attached to the trace later without a
       // lookup (see SeededTraceIdGenerator in ./instrumentation).
-      await runWithTraceIdSeed(
-        streamLangfuseConfig?.deterministicTraceId === true
-          ? this.id
-          : undefined,
+      await withLangfuseRuntimeScope(
+        resolveLangfuseRuntimeScope({
+          runLangfuse: streamLangfuseConfig,
+          langfuseOverlay: this.getStreamToolOutputTracingLangfuseConfig(graph),
+          traceIdSeed:
+            streamLangfuseConfig?.deterministicTraceId === true
+              ? this.id
+              : undefined,
+        }),
         () =>
-          withLangfuseToolOutputTracingConfig(
-            streamLangfuseConfig,
-            () =>
-              withLangfuseAttributes(
-                {
-                  langfuse: streamLangfuseConfig,
-                  userId,
-                  sessionId,
-                  traceName,
-                  traceMetadata,
-                  tags: ['librechat', 'agent'],
-                },
-                consumeStream
-              ),
-            this.getStreamToolOutputTracingLangfuseConfig(graph)
+          withLangfuseAttributes(
+            {
+              langfuse: streamLangfuseConfig,
+              userId,
+              sessionId,
+              traceName,
+              traceMetadata,
+              tags: ['librechat', 'agent'],
+            },
+            consumeStream
           )
       );
     } catch (err) {
@@ -1312,6 +1314,10 @@ export class Run<_T extends t.BaseGraphState> {
         sessionId: titleSessionId,
         traceMetadata,
         tags: ['librechat', 'title'],
+        traceIdSeed:
+          titleLangfuseConfig?.deterministicTraceId === true
+            ? 'title-' + this.id
+            : undefined,
       });
 
       if (titleLangfuseHandler != null) {
@@ -1404,10 +1410,12 @@ export class Run<_T extends t.BaseGraphState> {
 
     try {
       try {
-        return await withLangfuseToolOutputTracingConfig(
-          this.langfuse,
-          () => invokeTitleChain(invokeConfig),
-          titleContext?.langfuse
+        return await withLangfuseRuntimeScope(
+          resolveLangfuseRuntimeScope({
+            runLangfuse: this.langfuse,
+            langfuseOverlay: titleContext?.langfuse,
+          }),
+          () => invokeTitleChain(invokeConfig)
         );
       } catch (_e) {
         // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments
@@ -1420,10 +1428,12 @@ export class Run<_T extends t.BaseGraphState> {
         const safeConfig = Object.assign({}, rest, {
           callbacks: langfuseHandler ? [langfuseHandler] : [],
         });
-        return await withLangfuseToolOutputTracingConfig(
-          this.langfuse,
-          () => invokeTitleChain(safeConfig as Partial<RunnableConfig>),
-          titleContext?.langfuse
+        return await withLangfuseRuntimeScope(
+          resolveLangfuseRuntimeScope({
+            runLangfuse: this.langfuse,
+            langfuseOverlay: titleContext?.langfuse,
+          }),
+          () => invokeTitleChain(safeConfig as Partial<RunnableConfig>)
         );
       }
     } finally {

package/src/specs/deterministic-trace-id.test.ts

@@ -1,8 +1,5 @@
-import { createHash } from 'node:crypto';
-import {
-  initializeLangfuseTracing,
-  runWithTraceIdSeed,
-} from '@/instrumentation';
+import { runWithTraceIdSeed, traceIdFromSeed } from '@/langfuseRuntimeContext';
+import { initializeLangfuseTracing } from '@/instrumentation';
 
 const langfuse = {
   publicKey: 'pk-lf-test',
@@ -10,10 +7,6 @@ const langfuse = {
   baseUrl: 'http://localhost:3999',
 };
 
-/** sha256(seed) → first 32 hex chars; what `@langfuse/tracing` `createTraceId` produces. */
-const expectedTraceId = (seed: string): string =>
-  createHash('sha256').update(seed, 'utf8').digest('hex').slice(0, 32);
-
 describe('deterministic Langfuse trace ids', () => {
   it('derives the root trace id from the seed when run inside runWithTraceIdSeed', () => {
     const provider = initializeLangfuseTracing(langfuse);
@@ -28,7 +21,7 @@ describe('deterministic Langfuse trace ids', () => {
       span.end();
     });
 
-    expect(traceId).toBe(expectedTraceId(seed));
+    expect(traceId).toBe(traceIdFromSeed(seed));
   });
 
   it('falls back to a random trace id when no seed is active', () => {
@@ -40,7 +33,7 @@ describe('deterministic Langfuse trace ids', () => {
     span.end();
 
     expect(traceId).toMatch(/^[0-9a-f]{32}$/);
-    expect(traceId).not.toBe(expectedTraceId('response-message-id-1234'));
+    expect(traceId).not.toBe(traceIdFromSeed('response-message-id-1234'));
   });
 
   it('runWithTraceIdSeed is a passthrough when the seed is undefined', () => {