@librechat/agents 3.2.44 → 3.2.45

package/src/langfuseConfig.ts

@@ -0,0 +1,214 @@
+import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
+import type * as t from '@/types';
+import { parseBooleanEnv } from '@/utils/misc';
+
+export const LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = '[tool output redacted]';
+
+function isPresent(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+export 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 = parseBooleanEnv(
+    process.env.LANGFUSE_TRACE_TOOL_OUTPUTS
+  );
+  if (traceToolOutputs != null) {
+    return traceToolOutputs;
+  }
+
+  const redactToolOutputs = parseBooleanEnv(
+    process.env.LANGFUSE_REDACT_TOOL_OUTPUTS
+  );
+  if (redactToolOutputs != null) {
+    return !redactToolOutputs;
+  }
+
+  return parseBooleanEnv(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 hasEnvToolOutputTracingConfig(): boolean {
+  return (
+    getEnvToolOutputTracingEnabled() != null ||
+    getEnvRedactedToolNames() != null ||
+    getEnvRedactionText() != null ||
+    getEnvToolNameMatchMode() != null
+  );
+}
+
+function resolveToolOutputTracingEnabled(
+  runConfig?: t.LangfuseToolOutputTracingConfig,
+  agentConfig?: t.LangfuseToolOutputTracingConfig
+): boolean {
+  return (
+    agentConfig?.enabled ??
+    runConfig?.enabled ??
+    getEnvToolOutputTracingEnabled() ??
+    true
+  );
+}
+
+function resolveRedactedToolNames(
+  runConfig?: t.LangfuseToolOutputTracingConfig,
+  agentConfig?: t.LangfuseToolOutputTracingConfig
+): Set<string> {
+  return normalizeToolNames([
+    ...(getEnvRedactedToolNames() ?? []),
+    ...(runConfig?.redactedToolNames ?? []),
+    ...(agentConfig?.redactedToolNames ?? []),
+  ]);
+}
+
+function resolveToolNameMatchMode(
+  runConfig?: t.LangfuseToolOutputTracingConfig,
+  agentConfig?: t.LangfuseToolOutputTracingConfig
+): 'exact' | 'partial' {
+  const modes = [
+    getEnvToolNameMatchMode(),
+    runConfig?.redactedToolNameMatchMode,
+    agentConfig?.redactedToolNameMatchMode,
+  ];
+  return modes.includes('partial') ? 'partial' : 'exact';
+}
+
+export function hasToolOutputTracingConfig(
+  runLangfuse?: t.LangfuseConfig,
+  agentLangfuse?: t.LangfuseConfig
+): boolean {
+  return (
+    runLangfuse?.toolOutputTracing != null ||
+    agentLangfuse?.toolOutputTracing != null ||
+    hasEnvToolOutputTracingConfig()
+  );
+}
+
+export function resolveToolOutputTracingConfig(
+  runLangfuse?: t.LangfuseConfig,
+  agentLangfuse?: t.LangfuseConfig
+): ResolvedLangfuseToolOutputTracingConfig {
+  const runConfig = runLangfuse?.toolOutputTracing;
+  const agentConfig = agentLangfuse?.toolOutputTracing;
+
+  return {
+    enabled: resolveToolOutputTracingEnabled(runConfig, agentConfig),
+    redactedToolNames: resolveRedactedToolNames(runConfig, agentConfig),
+    redactedToolNameMatchMode: resolveToolNameMatchMode(runConfig, agentConfig),
+    redactionText:
+      agentConfig?.redactionText ??
+      runConfig?.redactionText ??
+      getEnvRedactionText() ??
+      LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT,
+  };
+}
+
+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 librechatTraceAttributes =
+    runLangfuse.librechatTraceAttributes != null ||
+    agentLangfuse.librechatTraceAttributes != null
+      ? {
+        ...runLangfuse.librechatTraceAttributes,
+        ...agentLangfuse.librechatTraceAttributes,
+      }
+      : undefined;
+  const tags =
+    runLangfuse.tags != null || agentLangfuse.tags != null
+      ? [
+        ...new Set([
+          ...(runLangfuse.tags ?? []),
+          ...(agentLangfuse.tags ?? []),
+        ]),
+      ]
+      : undefined;
+
+  return {
+    ...runLangfuse,
+    ...agentLangfuse,
+    ...(metadata != null ? { metadata } : {}),
+    ...(librechatTraceAttributes != null ? { librechatTraceAttributes } : {}),
+    ...(tags != null ? { tags } : {}),
+    ...(toolNodeTracing != null ? { toolNodeTracing } : {}),
+    ...(toolOutputTracing != null ? { toolOutputTracing } : {}),
+  };
+}

package/src/langfuseRuntimeContext.ts

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type * as t from '@/types';
+
+export type ResolvedLangfuseToolOutputTracingConfig = {
+  enabled: boolean;
+  redactedToolNames: Set<string>;
+  redactedToolNameMatchMode: 'exact' | 'partial';
+  redactionText: string;
+};
+
+export type LangfuseRuntimeContext = {
+  langfuse?: t.LangfuseConfig;
+  traceIdSeed?: string;
+  toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
+};
+
+const langfuseRuntimeContextStore =
+  new AsyncLocalStorage<LangfuseRuntimeContext>();
+
+function hasText(value: string | undefined): value is string {
+  return value != null && value.trim() !== '';
+}
+
+export function hasLangfuseRuntimeContextValue(
+  context: LangfuseRuntimeContext
+): boolean {
+  return (
+    context.langfuse != null ||
+    hasText(context.traceIdSeed) ||
+    context.toolOutputTracing != null
+  );
+}
+
+/** sha256(seed) -> first 32 hex chars; matches `@langfuse/tracing` `createTraceId`. */
+export function traceIdFromSeed(seed: string): string {
+  return createHash('sha256').update(seed, 'utf8').digest('hex').slice(0, 32);
+}
+
+export function getLangfuseRuntimeContext():
+  | LangfuseRuntimeContext
+  | undefined {
+  return langfuseRuntimeContextStore.getStore();
+}
+
+export function getLangfuseRuntimeConfig(): t.LangfuseConfig | undefined {
+  return getLangfuseRuntimeContext()?.langfuse;
+}
+
+export function getTraceIdSeed(): string | undefined {
+  return getLangfuseRuntimeContext()?.traceIdSeed;
+}
+
+export function getLangfuseRuntimeToolOutputTracingConfig():
+  | ResolvedLangfuseToolOutputTracingConfig
+  | undefined {
+  return getLangfuseRuntimeContext()?.toolOutputTracing;
+}
+
+/**
+ * Runs `fn` with a merged Langfuse runtime context. Undefined fields inherit
+ * from the parent scope; callers intentionally cannot clear parent values by
+ * passing `undefined`.
+ */
+export function runWithLangfuseRuntimeContext<T>(
+  context: LangfuseRuntimeContext,
+  fn: () => T
+): T {
+  const current = getLangfuseRuntimeContext();
+  const next = {
+    ...(current ?? {}),
+    ...(context.langfuse !== undefined ? { langfuse: context.langfuse } : {}),
+    ...(hasText(context.traceIdSeed)
+      ? { traceIdSeed: context.traceIdSeed }
+      : {}),
+    ...(context.toolOutputTracing !== undefined
+      ? { toolOutputTracing: context.toolOutputTracing }
+      : {}),
+  };
+
+  return hasLangfuseRuntimeContextValue(next)
+    ? langfuseRuntimeContextStore.run(next, fn)
+    : fn();
+}
+
+export function runWithTraceIdSeed<T>(
+  seed: string | undefined,
+  fn: () => T
+): T {
+  return hasText(seed)
+    ? runWithLangfuseRuntimeContext({ traceIdSeed: seed }, fn)
+    : fn();
+}

package/src/langfuseRuntimeScope.ts

@@ -0,0 +1,135 @@
+import { context, createContextKey } from '@opentelemetry/api';
+import type { Context } from '@opentelemetry/api';
+import type {
+  LangfuseRuntimeContext,
+  ResolvedLangfuseToolOutputTracingConfig,
+} from '@/langfuseRuntimeContext';
+import type * as t from '@/types';
+import {
+  getLangfuseRuntimeConfig,
+  getLangfuseRuntimeToolOutputTracingConfig,
+  getTraceIdSeed,
+  hasLangfuseRuntimeContextValue,
+  runWithLangfuseRuntimeContext,
+} from '@/langfuseRuntimeContext';
+import {
+  hasToolOutputTracingConfig,
+  resolveLangfuseConfig,
+  resolveToolOutputTracingConfig,
+} from '@/langfuseConfig';
+
+export type LangfuseRuntimeScope = LangfuseRuntimeContext;
+
+export type ResolveLangfuseRuntimeScopeParams = {
+  runLangfuse?: t.LangfuseConfig;
+  langfuseOverlay?: t.LangfuseConfig;
+  traceIdSeed?: string;
+};
+
+const langfuseToolOutputTracingConfigKey = createContextKey(
+  'librechat.langfuse.tool-output-tracing'
+);
+const langfuseConfigKey = createContextKey('librechat.langfuse.config');
+const langfuseTraceIdSeedKey = createContextKey(
+  'librechat.langfuse.trace-id-seed'
+);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasText(value: string | undefined): value is string {
+  return value != null && value.trim() !== '';
+}
+
+export function getOtelLangfuseConfig(
+  activeContext: Context
+): t.LangfuseConfig | undefined {
+  const value = activeContext.getValue(langfuseConfigKey);
+  return isRecord(value) ? (value as t.LangfuseConfig) : undefined;
+}
+
+export function getOtelTraceIdSeed(activeContext: Context): string | undefined {
+  const value = activeContext.getValue(langfuseTraceIdSeedKey);
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+
+export function getOtelToolOutputTracingConfig(
+  activeContext: Context
+): ResolvedLangfuseToolOutputTracingConfig | undefined {
+  const value = activeContext.getValue(langfuseToolOutputTracingConfigKey);
+  return isRecord(value)
+    ? (value as ResolvedLangfuseToolOutputTracingConfig)
+    : undefined;
+}
+
+export function resolveLangfuseConfigForSpan(
+  activeContext: Context
+): t.LangfuseConfig | undefined {
+  return getLangfuseRuntimeConfig() ?? getOtelLangfuseConfig(activeContext);
+}
+
+export function resolveTraceIdSeedForSpan(
+  activeContext: Context
+): string | undefined {
+  return getTraceIdSeed() ?? getOtelTraceIdSeed(activeContext);
+}
+
+export function resolveToolOutputTracingConfigForSpan(
+  activeContext: Context
+): ResolvedLangfuseToolOutputTracingConfig | undefined {
+  return (
+    getLangfuseRuntimeToolOutputTracingConfig() ??
+    getOtelToolOutputTracingConfig(activeContext)
+  );
+}
+
+export function withLangfuseRuntimeScope<T>(
+  scope: LangfuseRuntimeScope,
+  action: () => T
+): T {
+  if (!hasLangfuseRuntimeContextValue(scope)) {
+    return action();
+  }
+
+  let activeContext = context.active();
+  if (scope.langfuse != null) {
+    activeContext = activeContext.setValue(langfuseConfigKey, scope.langfuse);
+  }
+  if (scope.toolOutputTracing != null) {
+    activeContext = activeContext.setValue(
+      langfuseToolOutputTracingConfigKey,
+      scope.toolOutputTracing
+    );
+  }
+  if (hasText(scope.traceIdSeed)) {
+    activeContext = activeContext.setValue(
+      langfuseTraceIdSeedKey,
+      scope.traceIdSeed
+    );
+  }
+
+  // Span processors receive the OTel parent context in `onStart`, while
+  // LangChain callback handlers may run outside that context and need ALS.
+  // The trace id generator reads the seed from ALS or OTel context so SDK
+  // callbacks that preserve only one of those contexts still keep trace/score
+  // cohesion.
+  return runWithLangfuseRuntimeContext(scope, () =>
+    context.with(activeContext, action)
+  );
+}
+
+export function resolveLangfuseRuntimeScope({
+  runLangfuse,
+  langfuseOverlay,
+  traceIdSeed,
+}: ResolveLangfuseRuntimeScopeParams): LangfuseRuntimeScope {
+  const langfuse = resolveLangfuseConfig(runLangfuse, langfuseOverlay);
+  const toolOutputTracing = !hasToolOutputTracingConfig(
+    runLangfuse,
+    langfuseOverlay
+  )
+    ? undefined
+    : resolveToolOutputTracingConfig(runLangfuse, langfuseOverlay);
+  return { langfuse, traceIdSeed, toolOutputTracing };
+}