@librechat/agents 3.2.44 → 3.2.45

package/src/specs/langfuse-tool-output-tracing.test.ts

@@ -1,15 +1,31 @@
+import { context } from '@opentelemetry/api';
 import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
 import { AIMessage, ToolMessage, HumanMessage } from '@langchain/core/messages';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { BaseMessage } from '@langchain/core/messages';
+import type { Context } from '@opentelemetry/api';
 import type { TPayload } from '@/types';
 import {
   LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT,
+  classifyLangfuseToolNodeSpan,
   redactLangfuseSpanToolOutputs,
-  resolveLangfuseConfig,
   shouldTraceToolNodeForLangfuse,
-  type ResolvedLangfuseToolOutputTracingConfig,
 } from '@/langfuseToolOutputTracing';
+import {
+  resolveLangfuseConfigForSpan,
+  resolveLangfuseRuntimeScope,
+  resolveToolOutputTracingConfigForSpan,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
+import {
+  runWithLangfuseRuntimeContext,
+  type ResolvedLangfuseToolOutputTracingConfig,
+} from '@/langfuseRuntimeContext';
+import {
+  resolveLangfuseConfig,
+  resolveToolOutputTracingConfig,
+} from '@/langfuseConfig';
+import { ensureOpenTelemetryContextManager } from '@/instrumentation';
 import { formatAgentMessages } from '@/messages/format';
 import { ContentTypes } from '@/common';
 
@@ -194,6 +210,20 @@ describe('Langfuse tool output tracing redaction', () => {
     );
   });
 
+  it('classifies LangGraph tool-node spans without requiring redaction config', () => {
+    const span = createSpan('tool_batch', {
+      [LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: 'span',
+      [`${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`]:
+        'tools=agent_1',
+    });
+
+    classifyLangfuseToolNodeSpan(span);
+
+    expect(span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE]).toBe(
+      'tool'
+    );
+  });
+
   it('does not reclassify non-tool LangGraph spans', () => {
     const span = createSpan('agent=agent_1', {
       [LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: 'span',
@@ -587,7 +617,12 @@ describe('Langfuse tool output tracing redaction', () => {
         secretKey: 'sk-run',
         baseUrl: 'https://langfuse.test',
         metadata: { tenantId: 'tenant-run' },
+        librechatTraceAttributes: {
+          'librechat.langfuse.destination': 'eu',
+          'librechat.langfuse.tenant_export.enabled': true,
+        },
         tags: ['tenant:tenant-run', 'shared'],
+        deterministicTraceId: true,
         toolNodeTracing: { enabled: true },
         toolOutputTracing: {
           enabled: true,
@@ -595,7 +630,13 @@ describe('Langfuse tool output tracing redaction', () => {
         },
       },
       {
+        publicKey: 'pk-agent',
+        secretKey: 'sk-agent',
+        baseUrl: 'https://langfuse.agent',
         metadata: { agentId: 'agent-1' },
+        librechatTraceAttributes: {
+          'librechat.langfuse.public_key': 'pk-agent',
+        },
         tags: ['shared', 'agent:agent-1'],
         toolOutputTracing: {
           enabled: false,
@@ -606,11 +647,17 @@ describe('Langfuse tool output tracing redaction', () => {
 
     expect(resolved).toMatchObject({
       enabled: true,
-      publicKey: 'pk-run',
-      secretKey: 'sk-run',
-      baseUrl: 'https://langfuse.test',
+      publicKey: 'pk-agent',
+      secretKey: 'sk-agent',
+      baseUrl: 'https://langfuse.agent',
       metadata: { tenantId: 'tenant-run', agentId: 'agent-1' },
+      librechatTraceAttributes: {
+        'librechat.langfuse.destination': 'eu',
+        'librechat.langfuse.tenant_export.enabled': true,
+        'librechat.langfuse.public_key': 'pk-agent',
+      },
       tags: ['tenant:tenant-run', 'shared', 'agent:agent-1'],
+      deterministicTraceId: true,
       toolNodeTracing: { enabled: true },
       toolOutputTracing: {
         enabled: false,
@@ -619,4 +666,305 @@ describe('Langfuse tool output tracing redaction', () => {
       },
     });
   });
+
+  it('inherits deterministic trace ids when tenant config only supplies connection settings', () => {
+    const resolved = resolveLangfuseConfig(
+      {
+        deterministicTraceId: true,
+      },
+      {
+        publicKey: 'pk-tenant',
+        secretKey: 'sk-tenant',
+        baseUrl: 'https://langfuse.tenant',
+      }
+    );
+
+    expect(resolved).toMatchObject({
+      publicKey: 'pk-tenant',
+      secretKey: 'sk-tenant',
+      baseUrl: 'https://langfuse.tenant',
+      deterministicTraceId: true,
+    });
+  });
+
+  it('inherits application-level redaction when tenant config does not explicitly opt out', () => {
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS = 'true';
+    process.env.LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = '[app redacted]';
+
+    const config = resolveToolOutputTracingConfig(
+      {
+        publicKey: 'pk-tenant',
+        secretKey: 'sk-tenant',
+        baseUrl: 'https://langfuse.tenant',
+        toolOutputTracing: {
+          redactionText: '[tenant redacted]',
+        },
+      },
+      undefined
+    );
+
+    expect(config).toMatchObject({
+      enabled: false,
+      redactionText: '[tenant redacted]',
+    });
+  });
+
+  it('keeps application redacted tool names when tenant adds its own names', () => {
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUT_NAMES = 'run_sql';
+
+    const config = resolveToolOutputTracingConfig(
+      {
+        toolOutputTracing: {
+          redactedToolNames: ['execute_sql'],
+        },
+      },
+      {
+        toolOutputTracing: {
+          redactedToolNames: ['web_search'],
+        },
+      }
+    );
+
+    expect([...config.redactedToolNames].sort()).toEqual([
+      'execute_sql',
+      'run_sql',
+      'web_search',
+    ]);
+  });
+
+  it('keeps application partial redaction matching when tenant adds exact redaction config', () => {
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUT_NAME_MATCH_MODE = 'partial';
+
+    const config = resolveToolOutputTracingConfig(
+      {
+        toolOutputTracing: {
+          redactedToolNames: ['execute'],
+        },
+      },
+      {
+        toolOutputTracing: {
+          redactedToolNameMatchMode: 'exact',
+          redactedToolNames: ['web_search'],
+        },
+      }
+    );
+
+    expect(config.redactedToolNameMatchMode).toBe('partial');
+
+    const span = createSpan('execute_sql', {
+      [LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: 'tool',
+      [LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]: 'secret rows',
+    });
+
+    redactLangfuseSpanToolOutputs(span, config);
+
+    expect(span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]).toBe(
+      LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT
+    );
+  });
+
+  it('lets tenant explicitly opt out of application-level redact-all outputs', () => {
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS = 'true';
+
+    const config = resolveToolOutputTracingConfig(
+      {
+        publicKey: 'pk-tenant',
+        secretKey: 'sk-tenant',
+        toolOutputTracing: {
+          enabled: true,
+        },
+      },
+      undefined
+    );
+
+    expect(config.enabled).toBe(true);
+    expect(config.redactedToolNames.size).toBe(0);
+  });
+
+  it('applies application-level redaction through tenant runtime scope unless tenant opts out', () => {
+    ensureOpenTelemetryContextManager();
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS = 'true';
+    process.env.LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = '[app redacted]';
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope(
+      resolveLangfuseRuntimeScope({
+        runLangfuse: {
+          publicKey: 'pk-tenant',
+          secretKey: 'sk-tenant',
+          baseUrl: 'https://langfuse.tenant',
+        },
+      }),
+      () => {
+        capturedContext = context.active();
+      }
+    );
+
+    expect(capturedContext).toBeDefined();
+    const config = resolveToolOutputTracingConfigForSpan(capturedContext!);
+    expect(config).toMatchObject({
+      enabled: false,
+      redactionText: '[app redacted]',
+    });
+
+    const span = createSpan('execute_sql', {
+      [LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: 'tool',
+      [LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]: 'tenant secret rows',
+    });
+
+    redactLangfuseSpanToolOutputs(span, config!);
+
+    expect(span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]).toBe(
+      '[app redacted]'
+    );
+  });
+
+  it('keeps OTEL context fallback for spans outside callback runtime scope', () => {
+    ensureOpenTelemetryContextManager();
+    const langfuse = {
+      publicKey: 'pk-context',
+      secretKey: 'sk-context',
+      baseUrl: 'https://langfuse.context',
+    };
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope({ langfuse }, () => {
+      capturedContext = context.active();
+    });
+
+    expect(capturedContext).toBeDefined();
+    expect(resolveLangfuseConfigForSpan(capturedContext!)).toBe(langfuse);
+  });
+
+  it('keeps OTEL tool-output fallback for spans outside callback runtime scope', () => {
+    ensureOpenTelemetryContextManager();
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope(
+      { toolOutputTracing: createConfig({ enabled: false }) },
+      () => {
+        capturedContext = context.active();
+      }
+    );
+
+    expect(capturedContext).toBeDefined();
+    expect(
+      resolveToolOutputTracingConfigForSpan(capturedContext!)
+    ).toMatchObject({
+      enabled: false,
+    });
+  });
+
+  it('honors env-only tool-output redaction in runtime scope', () => {
+    ensureOpenTelemetryContextManager();
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS = 'true';
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope(resolveLangfuseRuntimeScope({}), () => {
+      capturedContext = context.active();
+    });
+
+    expect(capturedContext).toBeDefined();
+    const config = resolveToolOutputTracingConfigForSpan(capturedContext!);
+    expect(config).toMatchObject({
+      enabled: false,
+      redactedToolNameMatchMode: 'exact',
+      redactionText: LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT,
+    });
+    expect(config?.redactedToolNames.size).toBe(0);
+  });
+
+  it('applies agent tool-output redaction override through runtime scope', () => {
+    ensureOpenTelemetryContextManager();
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope(
+      resolveLangfuseRuntimeScope({
+        runLangfuse: {
+          toolOutputTracing: {
+            enabled: true,
+            redactionText: '[agent redacted]',
+          },
+        },
+        langfuseOverlay: {
+          toolOutputTracing: {
+            enabled: false,
+          },
+        },
+      }),
+      () => {
+        capturedContext = context.active();
+      }
+    );
+
+    expect(capturedContext).toBeDefined();
+    const config = resolveToolOutputTracingConfigForSpan(capturedContext!);
+    expect(config).toMatchObject({
+      enabled: false,
+      redactionText: '[agent redacted]',
+    });
+
+    const span = createSpan('execute_sql', {
+      [LangfuseOtelSpanAttributes.OBSERVATION_TYPE]: 'tool',
+      [LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]: 'secret rows',
+    });
+
+    redactLangfuseSpanToolOutputs(span, config!);
+
+    expect(span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]).toBe(
+      '[agent redacted]'
+    );
+  });
+
+  it('prefers ALS runtime tenant config over OTEL fallback config', () => {
+    ensureOpenTelemetryContextManager();
+    const otelLangfuse = {
+      publicKey: 'pk-otel',
+      secretKey: 'sk-otel',
+      baseUrl: 'https://langfuse.otel',
+    };
+    const runtimeLangfuse = {
+      publicKey: 'pk-runtime',
+      secretKey: 'sk-runtime',
+      baseUrl: 'https://langfuse.runtime',
+    };
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope({ langfuse: otelLangfuse }, () => {
+      capturedContext = context.active();
+    });
+
+    runWithLangfuseRuntimeContext({ langfuse: runtimeLangfuse }, () => {
+      expect(resolveLangfuseConfigForSpan(capturedContext!)).toBe(
+        runtimeLangfuse
+      );
+    });
+  });
+
+  it('prefers ALS runtime tool-output config over OTEL fallback config', () => {
+    ensureOpenTelemetryContextManager();
+    const runtimeToolOutputTracing = {
+      enabled: false,
+      redactedToolNames: new Set(['runtime_tool']),
+      redactedToolNameMatchMode: 'exact' as const,
+      redactionText: '[runtime]',
+    };
+    let capturedContext: Context | undefined;
+
+    withLangfuseRuntimeScope(
+      { toolOutputTracing: createConfig({ enabled: true }) },
+      () => {
+        capturedContext = context.active();
+      }
+    );
+
+    runWithLangfuseRuntimeContext(
+      { toolOutputTracing: runtimeToolOutputTracing },
+      () => {
+        expect(resolveToolOutputTracingConfigForSpan(capturedContext!)).toBe(
+          runtimeToolOutputTracing
+        );
+      }
+    );
+  });
 });

package/src/tools/ToolNode.ts

@@ -33,6 +33,10 @@ import type {
   PostToolBatchEntry,
 } from '@/hooks';
 import type * as t from '@/types';
+import {
+  resolveLangfuseRuntimeScope,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
 import {
   buildReferenceKey,
   ToolOutputReferenceRegistry,
@@ -49,7 +53,6 @@ import {
   resolveLocalToolRegistry,
   resolveLocalExecutionTools,
 } from '@/tools/local';
-import { withLangfuseToolOutputTracingConfig } from '@/langfuseToolOutputTracing';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
 import { toLangChainContent } from '@/messages/langchain';
@@ -577,10 +580,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     options?: Partial<RunnableConfig>
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): Promise<any> {
-    return withLangfuseToolOutputTracingConfig(
-      this.runLangfuse,
-      () => super.invoke(input, options),
-      this.agentLangfuse
+    return withLangfuseRuntimeScope(
+      resolveLangfuseRuntimeScope({
+        runLangfuse: this.runLangfuse,
+        langfuseOverlay: this.agentLangfuse,
+      }),
+      () => super.invoke(input, options)
     );
   }
 

package/src/tools/__tests__/ToolNode.langfuse.test.ts

@@ -1,18 +1,25 @@
-const mockWithLangfuseToolOutputTracingConfig = jest.fn(
-  (_runLangfuse: unknown, action: () => unknown, _agentLangfuse: unknown) =>
-    action()
+const mockWithLangfuseRuntimeScope = jest.fn(
+  (_scope: unknown, action: () => unknown) => action()
 );
-
-jest.mock('@/langfuseToolOutputTracing', () => ({
-  ...jest.requireActual('@/langfuseToolOutputTracing'),
-  withLangfuseToolOutputTracingConfig: mockWithLangfuseToolOutputTracingConfig,
+const mockResolvedScope = {
+  langfuse: {
+    toolOutputTracing: { enabled: false },
+  },
+};
+const mockResolveLangfuseRuntimeScope = jest.fn(() => mockResolvedScope);
+
+jest.mock('@/langfuseRuntimeScope', () => ({
+  ...jest.requireActual('@/langfuseRuntimeScope'),
+  resolveLangfuseRuntimeScope: mockResolveLangfuseRuntimeScope,
+  withLangfuseRuntimeScope: mockWithLangfuseRuntimeScope,
 }));
 
 import { ToolNode } from '../ToolNode';
 
 describe('ToolNode Langfuse redaction context', () => {
   beforeEach(() => {
-    mockWithLangfuseToolOutputTracingConfig.mockClear();
+    mockWithLangfuseRuntimeScope.mockClear();
+    mockResolveLangfuseRuntimeScope.mockClear();
   });
 
   it('uses a stable default run name for tracing', () => {
@@ -38,10 +45,13 @@ describe('ToolNode Langfuse redaction context', () => {
       'ToolNode only accepts AIMessages'
     );
 
-    expect(mockWithLangfuseToolOutputTracingConfig).toHaveBeenCalledWith(
+    expect(mockResolveLangfuseRuntimeScope).toHaveBeenCalledWith({
       runLangfuse,
-      expect.any(Function),
-      agentLangfuse
+      langfuseOverlay: agentLangfuse,
+    });
+    expect(mockWithLangfuseRuntimeScope).toHaveBeenCalledWith(
+      mockResolvedScope,
+      expect.any(Function)
     );
   });
 });

package/src/types/graph.ts

@@ -537,6 +537,15 @@ export interface LangfuseConfig {
   secretKey?: string;
   baseUrl?: string;
   metadata?: Record<string, string | number | boolean | null | undefined>;
+  /**
+   * Internal OTLP span attributes to attach to Langfuse observations before
+   * export. Intended for collector-side routing/filtering; strip these in the
+   * collector before forwarding spans to Langfuse.
+   */
+  librechatTraceAttributes?: Record<
+    string,
+    string | number | boolean | null | undefined
+  >;
   tags?: string[];
   toolNodeTracing?: LangfuseToolNodeTracingConfig;
   toolOutputTracing?: LangfuseToolOutputTracingConfig;

package/src/utils/misc.ts

@@ -2,6 +2,24 @@ export function isPresent(value: string | null | undefined): value is string {
   return value != null && value !== '';
 }
 
+export function parseBooleanEnv(
+  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;
+}
+
 /**
  * Unescapes a c-escaped string
  * @param str The string to unescape