@librechat/agents 3.2.44 → 3.2.46

package/dist/esm/utils/misc.mjs

@@ -2,6 +2,22 @@
 function isPresent(value) {
 	return value != null && value !== "";
 }
+function parseBooleanEnv(value) {
+	if (value == null) return;
+	const normalized = value.trim().toLowerCase();
+	if ([
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes(normalized)) return true;
+	if ([
+		"0",
+		"false",
+		"no",
+		"off"
+	].includes(normalized)) return false;
+}
 /**
 * Unescapes a c-escaped string
 * @param str The string to unescape
@@ -34,6 +50,6 @@ function unescapeObject(obj, key) {
 	return obj;
 }
 //#endregion
-export { isPresent, unescapeObject };
+export { isPresent, parseBooleanEnv, unescapeObject };
 
 //# sourceMappingURL=misc.mjs.map

package/dist/esm/utils/misc.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"misc.mjs","names":[],"sources":["../../../src/utils/misc.ts"],"sourcesContent":["export function isPresent(value: string | null | undefined): value is string {\n  return value != null && value !== '';\n}\n\n/**\n * Unescapes a c-escaped string\n * @param str The string to unescape\n * @returns The unescaped string\n */\nconst unescapeString = (string: string): string =>\n  string.replace(/\\\\(.)/g, (_, char) => {\n    switch (char) {\n    case 'n':\n      return '\\n';\n    case 't':\n      return '\\t';\n    case 'r':\n      return '\\r';\n    case '\"':\n      return '\"';\n    case '\\'':\n      return '\\'';\n    case '\\\\':\n      return '\\\\';\n    default:\n      return char;\n    }\n  });\n\n/**\n * Recursively unescapes all string values in an object\n * @param obj The object to unescape\n * @returns The unescaped object\n */\nexport function unescapeObject(obj: unknown, key?: string): unknown {\n  if (typeof obj === 'string') {\n    let unescaped = unescapeString(obj);\n    if (key === 'filePath' && unescaped.match(/^\"(.+)\"$/)) {\n      unescaped = unescaped.substring(1, unescaped.length - 1);\n    }\n    return unescaped;\n  }\n  if (Array.isArray(obj)) {\n    return obj.map((value) =>\n      unescapeObject(value, key === 'contextPaths' ? 'filePath' : '')\n    );\n  }\n  if (typeof obj === 'object' && obj !== null) {\n    return Object.fromEntries(\n      Object.entries(obj).map(([key, value]) => [\n        key,\n        unescapeObject(value, key),\n      ])\n    );\n  }\n  return obj;\n}\n"],"mappings":";AAAA,SAAgB,UAAU,OAAmD;CAC3E,OAAO,SAAS,QAAQ,UAAU;AACpC;;;;;;AAOA,MAAM,kBAAkB,WACtB,OAAO,QAAQ,WAAW,GAAG,SAAS;CACpC,QAAQ,MAAR;EACA,KAAK,KACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,MACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,MACH,OAAO;EACT,SACE,OAAO;CACT;AACF,CAAC;;;;;;AAOH,SAAgB,eAAe,KAAc,KAAuB;CAClE,IAAI,OAAO,QAAQ,UAAU;EAC3B,IAAI,YAAY,eAAe,GAAG;EAClC,IAAI,QAAQ,cAAc,UAAU,MAAM,UAAU,GAClD,YAAY,UAAU,UAAU,GAAG,UAAU,SAAS,CAAC;EAEzD,OAAO;CACT;CACA,IAAI,MAAM,QAAQ,GAAG,GACnB,OAAO,IAAI,KAAK,UACd,eAAe,OAAO,QAAQ,iBAAiB,aAAa,EAAE,CAChE;CAEF,IAAI,OAAO,QAAQ,YAAY,QAAQ,MACrC,OAAO,OAAO,YACZ,OAAO,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACxC,KACA,eAAe,OAAO,GAAG,CAC3B,CAAC,CACH;CAEF,OAAO;AACT"}
+{"version":3,"file":"misc.mjs","names":[],"sources":["../../../src/utils/misc.ts"],"sourcesContent":["export function isPresent(value: string | null | undefined): value is string {\n  return value != null && value !== '';\n}\n\nexport function parseBooleanEnv(\n  value: string | undefined\n): boolean | undefined {\n  if (value == null) {\n    return undefined;\n  }\n\n  const normalized = value.trim().toLowerCase();\n  if (['1', 'true', 'yes', 'on'].includes(normalized)) {\n    return true;\n  }\n  if (['0', 'false', 'no', 'off'].includes(normalized)) {\n    return false;\n  }\n\n  return undefined;\n}\n\n/**\n * Unescapes a c-escaped string\n * @param str The string to unescape\n * @returns The unescaped string\n */\nconst unescapeString = (string: string): string =>\n  string.replace(/\\\\(.)/g, (_, char) => {\n    switch (char) {\n    case 'n':\n      return '\\n';\n    case 't':\n      return '\\t';\n    case 'r':\n      return '\\r';\n    case '\"':\n      return '\"';\n    case '\\'':\n      return '\\'';\n    case '\\\\':\n      return '\\\\';\n    default:\n      return char;\n    }\n  });\n\n/**\n * Recursively unescapes all string values in an object\n * @param obj The object to unescape\n * @returns The unescaped object\n */\nexport function unescapeObject(obj: unknown, key?: string): unknown {\n  if (typeof obj === 'string') {\n    let unescaped = unescapeString(obj);\n    if (key === 'filePath' && unescaped.match(/^\"(.+)\"$/)) {\n      unescaped = unescaped.substring(1, unescaped.length - 1);\n    }\n    return unescaped;\n  }\n  if (Array.isArray(obj)) {\n    return obj.map((value) =>\n      unescapeObject(value, key === 'contextPaths' ? 'filePath' : '')\n    );\n  }\n  if (typeof obj === 'object' && obj !== null) {\n    return Object.fromEntries(\n      Object.entries(obj).map(([key, value]) => [\n        key,\n        unescapeObject(value, key),\n      ])\n    );\n  }\n  return obj;\n}\n"],"mappings":";AAAA,SAAgB,UAAU,OAAmD;CAC3E,OAAO,SAAS,QAAQ,UAAU;AACpC;AAEA,SAAgB,gBACd,OACqB;CACrB,IAAI,SAAS,MACX;CAGF,MAAM,aAAa,MAAM,KAAK,CAAC,CAAC,YAAY;CAC5C,IAAI;EAAC;EAAK;EAAQ;EAAO;CAAI,CAAC,CAAC,SAAS,UAAU,GAChD,OAAO;CAET,IAAI;EAAC;EAAK;EAAS;EAAM;CAAK,CAAC,CAAC,SAAS,UAAU,GACjD,OAAO;AAIX;;;;;;AAOA,MAAM,kBAAkB,WACtB,OAAO,QAAQ,WAAW,GAAG,SAAS;CACpC,QAAQ,MAAR;EACA,KAAK,KACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,MACH,OAAO;EACT,KAAK,KACH,OAAO;EACT,KAAK,MACH,OAAO;EACT,SACE,OAAO;CACT;AACF,CAAC;;;;;;AAOH,SAAgB,eAAe,KAAc,KAAuB;CAClE,IAAI,OAAO,QAAQ,UAAU;EAC3B,IAAI,YAAY,eAAe,GAAG;EAClC,IAAI,QAAQ,cAAc,UAAU,MAAM,UAAU,GAClD,YAAY,UAAU,UAAU,GAAG,UAAU,SAAS,CAAC;EAEzD,OAAO;CACT;CACA,IAAI,MAAM,QAAQ,GAAG,GACnB,OAAO,IAAI,KAAK,UACd,eAAe,OAAO,QAAQ,iBAAiB,aAAa,EAAE,CAChE;CAEF,IAAI,OAAO,QAAQ,YAAY,QAAQ,MACrC,OAAO,OAAO,YACZ,OAAO,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACxC,KACA,eAAe,OAAO,GAAG,CAC3B,CAAC,CACH;CAEF,OAAO;AACT"}

package/dist/types/instrumentation.d.ts

@@ -1,6 +1,5 @@
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 import type * as t from '@/types';
-export declare function runWithTraceIdSeed<T>(seed: string | undefined, fn: () => T): T;
 export declare function ensureOpenTelemetryContextManager(): void;
 export declare function initializeLangfuseTracing(langfuse?: t.LangfuseConfig): BasicTracerProvider | undefined;
 export declare function initializeLangfuseTracingFromEnv(): BasicTracerProvider | undefined;

package/dist/types/langfuse.d.ts

@@ -1,11 +1,14 @@
 import { CallbackHandler } from '@langfuse/langchain';
 import type * as t from '@/types';
 export type LangfuseTraceMetadata = Record<string, string>;
+export type LangfuseTraceAttributes = Record<string, string | number | boolean>;
+type LangfuseConfigTraceAttributes = NonNullable<t.LangfuseConfig['librechatTraceAttributes']>;
 type LangfuseHandlerParams = {
     userId?: string;
     sessionId?: string;
     traceMetadata?: LangfuseTraceMetadata;
     tags?: string[];
+    traceIdSeed?: string;
 };
 type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
     langfuse?: t.LangfuseConfig;
@@ -18,6 +21,7 @@ export declare function hasLangfuseConfigCredentials(langfuse?: t.LangfuseConfig
     secretKey: string;
 };
 export declare function isExplicitLangfuseConfig(langfuse?: t.LangfuseConfig): boolean;
+export declare function createLibreChatTraceAttributes(attributes: LangfuseConfigTraceAttributes): LangfuseTraceAttributes;
 export declare function createLangfuseTraceMetadata({ messageId, parentMessageId, agentId, agentName, }: {
     messageId?: unknown;
     parentMessageId?: unknown;
@@ -29,7 +33,7 @@ export declare function hasLangfuseEnvConfig(): boolean;
 export declare function hasLangfuseEnvCredentials(): boolean;
 export declare function shouldCreateLangfuseHandler(langfuse?: t.LangfuseConfig): boolean;
 export declare function createLegacyLangfuseHandler(params: LangfuseHandlerParams): CallbackHandler;
-export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
+export declare function createLangfuseHandler({ langfuse, userId, sessionId, traceMetadata, tags, traceIdSeed, }: AgentLangfuseHandlerParams): CallbackHandler | undefined;
 export declare function withLangfuseAttributes<T>(params: LangfuseAttributeParams, action: () => T): T;
 export declare function hasExplicitLangfuseConfig(contexts: Iterable<{
     langfuse?: t.LangfuseConfig;

package/dist/types/langfuseConfig.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
+import type * as t from '@/types';
+export declare const LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = "[tool output redacted]";
+export declare function normalizeToolName(name: string): string;
+export declare function hasToolOutputTracingConfig(runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): boolean;
+export declare function resolveToolOutputTracingConfig(runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): ResolvedLangfuseToolOutputTracingConfig;
+export declare function resolveLangfuseConfig(runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): t.LangfuseConfig | undefined;

package/dist/types/langfuseRuntimeContext.d.ts

@@ -0,0 +1,26 @@
+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;
+};
+export declare function hasLangfuseRuntimeContextValue(context: LangfuseRuntimeContext): boolean;
+/** sha256(seed) -> first 32 hex chars; matches `@langfuse/tracing` `createTraceId`. */
+export declare function traceIdFromSeed(seed: string): string;
+export declare function getLangfuseRuntimeContext(): LangfuseRuntimeContext | undefined;
+export declare function getLangfuseRuntimeConfig(): t.LangfuseConfig | undefined;
+export declare function getTraceIdSeed(): string | undefined;
+export declare function getLangfuseRuntimeToolOutputTracingConfig(): ResolvedLangfuseToolOutputTracingConfig | undefined;
+/**
+ * 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 declare function runWithLangfuseRuntimeContext<T>(context: LangfuseRuntimeContext, fn: () => T): T;
+export declare function runWithTraceIdSeed<T>(seed: string | undefined, fn: () => T): T;

package/dist/types/langfuseRuntimeScope.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@opentelemetry/api';
+import type { LangfuseRuntimeContext, ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
+import type * as t from '@/types';
+export type LangfuseRuntimeScope = LangfuseRuntimeContext;
+export type ResolveLangfuseRuntimeScopeParams = {
+    runLangfuse?: t.LangfuseConfig;
+    langfuseOverlay?: t.LangfuseConfig;
+    traceIdSeed?: string;
+};
+export declare function getOtelLangfuseConfig(activeContext: Context): t.LangfuseConfig | undefined;
+export declare function getOtelTraceIdSeed(activeContext: Context): string | undefined;
+export declare function getOtelToolOutputTracingConfig(activeContext: Context): ResolvedLangfuseToolOutputTracingConfig | undefined;
+export declare function resolveLangfuseConfigForSpan(activeContext: Context): t.LangfuseConfig | undefined;
+export declare function resolveTraceIdSeedForSpan(activeContext: Context): string | undefined;
+export declare function resolveToolOutputTracingConfigForSpan(activeContext: Context): ResolvedLangfuseToolOutputTracingConfig | undefined;
+export declare function withLangfuseRuntimeScope<T>(scope: LangfuseRuntimeScope, action: () => T): T;
+export declare function resolveLangfuseRuntimeScope({ runLangfuse, langfuseOverlay, traceIdSeed, }: ResolveLangfuseRuntimeScopeParams): LangfuseRuntimeScope;

package/dist/types/langfuseToolOutputTracing.d.ts

@@ -1,20 +1,13 @@
 import type { ReadableSpan, SpanProcessor } 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';
-export declare const LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT = "[tool output redacted]";
-export type ResolvedLangfuseToolOutputTracingConfig = {
-    enabled: boolean;
-    redactedToolNames: Set<string>;
-    redactedToolNameMatchMode: 'exact' | 'partial';
-    redactionText: string;
-};
+import { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig } from '@/langfuseConfig';
+export { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig };
+export declare function classifyLangfuseToolNodeSpan(span: ReadableSpan): void;
 export declare function redactLangfuseSpanToolOutputs(span: ReadableSpan, config: ResolvedLangfuseToolOutputTracingConfig): void;
-export declare function getContextLangfuseConfig(activeContext: Context): t.LangfuseConfig | undefined;
 export declare function createLangfuseSpanProcessor(params?: LangfuseSpanProcessorParams, runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): SpanProcessor;
-export declare function withLangfuseToolOutputTracingConfig<T>(runLangfuse: t.LangfuseConfig | undefined, action: () => T, agentLangfuse?: t.LangfuseConfig): T;
 export declare function shouldTraceToolNodeForLangfuse({ runLangfuse, agentLangfuse, }: {
     runLangfuse?: t.LangfuseConfig;
     agentLangfuse?: t.LangfuseConfig;
 }): boolean;
-export declare function resolveLangfuseConfig(runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): t.LangfuseConfig | undefined;

package/dist/types/messages/format.d.ts

@@ -91,6 +91,10 @@ interface LangChainMessage {
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
 interface FormatAgentMessagesOptions {
     provider?: Providers;
+    /** Reconstruct hidden `reasoning_content` from `THINK` parts onto prior
+     *  tool-call messages. Explicit opt-in for OpenAI-compatible endpoints that
+     *  replay reasoning across turns; defaults to on for DeepSeek thinking-mode. */
+    preserveReasoningContent?: boolean;
     /** Skill names already primed fresh this turn (manual/always-apply). Their
      *  historical `skill` tool_calls are not reconstructed into a HumanMessage,
      *  so the same SKILL.md body is not injected twice in one request. */

package/dist/types/types/graph.d.ts

@@ -408,6 +408,12 @@ 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/dist/types/utils/misc.d.ts

@@ -1,4 +1,5 @@
 export declare function isPresent(value: string | null | undefined): value is string;
+export declare function parseBooleanEnv(value: string | undefined): boolean | undefined;
 /**
  * Recursively unescapes all string values in an object
  * @param obj The object to unescape

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.2.44",
+  "version": "3.2.46",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -34,11 +34,6 @@ import {
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
 } from '@/messages';
-import {
-  resolveLangfuseConfig,
-  shouldTraceToolNodeForLangfuse,
-  withLangfuseToolOutputTracingConfig,
-} from '@/langfuseToolOutputTracing';
 import {
   createLangfuseHandler,
   createLangfuseTraceMetadata,
@@ -54,6 +49,10 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
+import {
+  resolveLangfuseRuntimeScope,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
 import {
   GraphNodeKeys,
   ContentTypes,
@@ -67,6 +66,7 @@ import {
   type CallbackEntry,
 } from '@/utils/callbacks';
 import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
+import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
@@ -81,6 +81,7 @@ import { shouldTriggerSummarization } from '@/summarization';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
 import { messagesStateReducer } from '@/messages/reducer';
+import { resolveLangfuseConfig } from '@/langfuseConfig';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
@@ -2079,6 +2080,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           sessionId: config.configurable?.thread_id as string | undefined,
           traceMetadata,
           tags: ['librechat', 'agent'],
+          traceIdSeed:
+            langfuse?.deterministicTraceId === true ? this.runId : undefined,
         });
         if (langfuseHandler != null) {
           invokeConfig = {
@@ -2092,8 +2095,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const metadata = config.metadata as Record<string, unknown>;
 
       try {
-        result = await withLangfuseToolOutputTracingConfig(
-          this.langfuse,
+        result = await withLangfuseRuntimeScope(
+          resolveLangfuseRuntimeScope({
+            runLangfuse: this.langfuse,
+            langfuseOverlay: agentContext.langfuse,
+          }),
           () =>
             attemptInvoke(
               {
@@ -2103,16 +2109,18 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 context: this,
               },
               invokeConfig
-            ),
-          agentContext.langfuse
+            )
         );
       } catch (primaryError) {
         clearCurrentDeltaStepMarkers({
           graph: this,
           metadata,
         });
-        result = await withLangfuseToolOutputTracingConfig(
-          this.langfuse,
+        result = await withLangfuseRuntimeScope(
+          resolveLangfuseRuntimeScope({
+            runLangfuse: this.langfuse,
+            langfuseOverlay: agentContext.langfuse,
+          }),
           () =>
             tryFallbackProviders({
               fallbacks,
@@ -2121,8 +2129,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               config: invokeConfig,
               primaryError,
               context: this,
-            }),
-          agentContext.langfuse
+            })
         );
       } finally {
         await disposeLangfuseHandler(langfuseHandler);

package/src/instrumentation.ts

@@ -1,4 +1,3 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash, randomBytes } from 'node:crypto';
 import { setLangfuseTracerProvider } from '@langfuse/tracing';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
@@ -14,43 +13,33 @@ import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
 import type { Context } from '@opentelemetry/api';
 import type * as t from '@/types';
 import {
+  createLibreChatTraceAttributes,
   hasLangfuseConfigCredentials,
   hasLangfuseEnvCredentials,
   hasLangfuseEnvConfig,
 } from '@/langfuse';
 import {
-  createLangfuseSpanProcessor,
-  getContextLangfuseConfig,
-} from '@/langfuseToolOutputTracing';
+  resolveLangfuseConfigForSpan,
+  resolveTraceIdSeedForSpan,
+} from '@/langfuseRuntimeScope';
+import { createLangfuseSpanProcessor } from '@/langfuseToolOutputTracing';
+import { traceIdFromSeed } from '@/langfuseRuntimeContext';
 import { isPresent } from '@/utils/misc';
 
 /**
  * Per-run seed for deterministic Langfuse trace ids. When a run opts in
  * (`LangfuseConfig.deterministicTraceId`), it executes its stream inside
- * `runWithTraceIdSeed(runId, …)` and the IdGenerator below derives the root
- * trace id from that seed instead of a random one. This lets external systems
- * (e.g. a host app recording user feedback after the fact) attach scores or
- * observations to the trace by regenerating the same id from the run/message
- * id — no trace lookup required. With no active seed it falls back to random
- * ids, so default behavior is unchanged.
+ * `runWithTraceIdSeed(runId, ...)` from `./langfuseRuntimeContext`, and the
+ * IdGenerator below derives the root trace id from that seed instead of a
+ * random one. This lets external systems (e.g. a host app recording user
+ * feedback after the fact) attach scores or observations to the trace by
+ * regenerating the same id from the run/message id; no trace lookup required.
+ * With no active seed it falls back to random ids, so default behavior is
+ * unchanged.
  */
-const traceIdSeedStore = new AsyncLocalStorage<string>();
-
-export function runWithTraceIdSeed<T>(
-  seed: string | undefined,
-  fn: () => T
-): T {
-  return isPresent(seed) ? traceIdSeedStore.run(seed, fn) : fn();
-}
-
-/** sha256(seed) → first 32 hex chars; matches `@langfuse/tracing` `createTraceId`. */
-function traceIdFromSeed(seed: string): string {
-  return createHash('sha256').update(seed, 'utf8').digest('hex').slice(0, 32);
-}
-
 class SeededTraceIdGenerator implements IdGenerator {
   generateTraceId(): string {
-    const seed = traceIdSeedStore.getStore();
+    const seed = resolveTraceIdSeedForSpan(context.active());
     return isPresent(seed)
       ? traceIdFromSeed(seed)
       : randomBytes(16).toString('hex');
@@ -120,13 +109,19 @@ function getLangfuseSpanProcessorParams(
   return undefined;
 }
 
+function hashCacheKeyValue(value: string | undefined): string | undefined {
+  return isPresent(value)
+    ? createHash('sha256').update(value, 'utf8').digest('hex')
+    : undefined;
+}
+
 function getLangfuseTracerProviderKey(
   params: LangfuseSpanProcessorParams,
   langfuse?: t.LangfuseConfig
 ): string {
   return JSON.stringify({
     publicKey: params.publicKey,
-    secretKey: params.secretKey,
+    secretKeyHash: hashCacheKeyValue(params.secretKey),
     baseUrl: params.baseUrl,
     environment: params.environment,
     toolOutputTracing: langfuse?.toolOutputTracing,
@@ -134,6 +129,9 @@ function getLangfuseTracerProviderKey(
 }
 
 class RoutingLangfuseSpanProcessor implements SpanProcessor {
+  // Processors live for the process lifetime. LibreChat tenant Langfuse
+  // destinations are expected to be a bounded admin-managed set, and shutdown
+  // drains every cached processor when the provider is disposed.
   private readonly processors = new Map<string, SpanProcessor>();
   private readonly spanProcessors = new WeakMap<object, SpanProcessor>();
 
@@ -155,13 +153,19 @@ class RoutingLangfuseSpanProcessor implements SpanProcessor {
   }
 
   onStart(span: Span, parentContext: Context): void {
-    const processor = this.ensureProcessor(
-      getContextLangfuseConfig(parentContext)
-    );
+    const langfuse = resolveLangfuseConfigForSpan(parentContext);
+    const processor = this.ensureProcessor(langfuse);
     if (processor == null) {
       return;
     }
 
+    const librechatTraceAttributes = createLibreChatTraceAttributes(
+      langfuse?.librechatTraceAttributes ?? {}
+    );
+    if (Object.keys(librechatTraceAttributes).length > 0) {
+      span.setAttributes(librechatTraceAttributes);
+    }
+
     this.spanProcessors.set(span, processor);
     processor.onStart(span, parentContext);
   }

package/src/langfuse.ts

@@ -1,23 +1,34 @@
 import { CallbackHandler } from '@langfuse/langchain';
+import { context as otelContext } from '@opentelemetry/api';
 import {
   getLangfuseTracerProvider,
   propagateAttributes,
 } from '@langfuse/tracing';
 import type { PropagateAttributesParams } from '@langfuse/tracing';
 import type * as t from '@/types';
-import { isPresent } from '@/utils/misc';
+import {
+  resolveLangfuseConfigForSpan,
+  resolveTraceIdSeedForSpan,
+  withLangfuseRuntimeScope,
+} from '@/langfuseRuntimeScope';
+import { isPresent, parseBooleanEnv } from '@/utils/misc';
 
 const TRACE_METADATA_MAX_LENGTH = 200;
 const LANGFUSE_FORCE_FLUSH_ON_DISPOSE = 'LANGFUSE_FORCE_FLUSH_ON_DISPOSE';
 
 export type LangfuseTraceMetadata = Record<string, string>;
+export type LangfuseTraceAttributes = Record<string, string | number | boolean>;
 type LangfuseMetadata = NonNullable<t.LangfuseConfig['metadata']>;
+type LangfuseConfigTraceAttributes = NonNullable<
+  t.LangfuseConfig['librechatTraceAttributes']
+>;
 
 type LangfuseHandlerParams = {
   userId?: string;
   sessionId?: string;
   traceMetadata?: LangfuseTraceMetadata;
   tags?: string[];
+  traceIdSeed?: string;
 };
 
 type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
@@ -32,11 +43,81 @@ type FlushableTracerProvider = {
   forceFlush?: () => Promise<void> | void;
 };
 
-function parseBooleanEnv(value?: string): boolean {
-  if (value == null) {
-    return false;
+class ScopedLangfuseCallbackHandler extends CallbackHandler {
+  private readonly langfuse?: t.LangfuseConfig;
+  private readonly traceIdSeed?: string;
+
+  constructor(params?: AgentLangfuseHandlerParams) {
+    const { langfuse, traceIdSeed, ...handlerParams } = params ?? {};
+    super(handlerParams);
+    this.langfuse = langfuse;
+    this.traceIdSeed = traceIdSeed;
+  }
+
+  private getDeterministicTraceSeed(): string | undefined {
+    return this.langfuse?.deterministicTraceId === true
+      ? this.traceIdSeed
+      : undefined;
+  }
+
+  private withRuntimeContext<T>(action: () => T): T {
+    const activeContext = otelContext.active();
+    const langfuse =
+      resolveLangfuseConfigForSpan(activeContext) ?? this.langfuse;
+    const seed = this.getDeterministicTraceSeed();
+    return withLangfuseRuntimeScope(
+      {
+        langfuse,
+        traceIdSeed: resolveTraceIdSeedForSpan(activeContext) ?? seed,
+      },
+      action
+    );
+  }
+
+  // LangChain may invoke callback handlers outside the caller's OTEL context.
+  // Re-enter tenant scope only for callbacks that start Langfuse observations;
+  // end/error/token callbacks use spans already bound to a processor at start.
+  override handleChainStart(
+    ...args: Parameters<CallbackHandler['handleChainStart']>
+  ): ReturnType<CallbackHandler['handleChainStart']> {
+    return this.withRuntimeContext(() => super.handleChainStart(...args));
+  }
+
+  override handleAgentAction(
+    ...args: Parameters<CallbackHandler['handleAgentAction']>
+  ): ReturnType<CallbackHandler['handleAgentAction']> {
+    return this.withRuntimeContext(() => super.handleAgentAction(...args));
+  }
+
+  override handleGenerationStart(
+    ...args: Parameters<CallbackHandler['handleGenerationStart']>
+  ): ReturnType<CallbackHandler['handleGenerationStart']> {
+    return this.withRuntimeContext(() => super.handleGenerationStart(...args));
+  }
+
+  override handleChatModelStart(
+    ...args: Parameters<CallbackHandler['handleChatModelStart']>
+  ): ReturnType<CallbackHandler['handleChatModelStart']> {
+    return this.withRuntimeContext(() => super.handleChatModelStart(...args));
+  }
+
+  override handleLLMStart(
+    ...args: Parameters<CallbackHandler['handleLLMStart']>
+  ): ReturnType<CallbackHandler['handleLLMStart']> {
+    return this.withRuntimeContext(() => super.handleLLMStart(...args));
+  }
+
+  override handleToolStart(
+    ...args: Parameters<CallbackHandler['handleToolStart']>
+  ): ReturnType<CallbackHandler['handleToolStart']> {
+    return this.withRuntimeContext(() => super.handleToolStart(...args));
+  }
+
+  override handleRetrieverStart(
+    ...args: Parameters<CallbackHandler['handleRetrieverStart']>
+  ): ReturnType<CallbackHandler['handleRetrieverStart']> {
+    return this.withRuntimeContext(() => super.handleRetrieverStart(...args));
   }
-  return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
 }
 
 function hasLangfuseTracingConfig(langfuse?: t.LangfuseConfig): boolean {
@@ -48,6 +129,9 @@ function hasLangfuseTracingConfig(langfuse?: t.LangfuseConfig): boolean {
 function hasLangfuseTraceAttributes(langfuse?: t.LangfuseConfig): boolean {
   return (
     Object.keys(createTraceMetadata(langfuse?.metadata ?? {})).length > 0 ||
+    Object.keys(
+      createLibreChatTraceAttributes(langfuse?.librechatTraceAttributes ?? {})
+    ).length > 0 ||
     (mergeLangfuseTags(undefined, langfuse?.tags)?.length ?? 0) > 0
   );
 }
@@ -100,6 +184,26 @@ function createTraceMetadata(
   return traceMetadata;
 }
 
+export function createLibreChatTraceAttributes(
+  attributes: LangfuseConfigTraceAttributes
+): LangfuseTraceAttributes {
+  const librechatTraceAttributes: LangfuseTraceAttributes = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null || key.trim() === '') {
+      continue;
+    }
+    if (typeof value === 'string') {
+      if (value.trim() === '' || value.length > TRACE_METADATA_MAX_LENGTH) {
+        continue;
+      }
+      librechatTraceAttributes[key] = value;
+      continue;
+    }
+    librechatTraceAttributes[key] = value;
+  }
+  return librechatTraceAttributes;
+}
+
 export function createLangfuseTraceMetadata({
   messageId,
   parentMessageId,
@@ -175,7 +279,7 @@ export function shouldCreateLangfuseHandler(
 export function createLegacyLangfuseHandler(
   params: LangfuseHandlerParams
 ): CallbackHandler {
-  return new CallbackHandler(params);
+  return new ScopedLangfuseCallbackHandler(params);
 }
 
 export function createLangfuseHandler({
@@ -184,11 +288,12 @@ export function createLangfuseHandler({
   sessionId,
   traceMetadata,
   tags,
+  traceIdSeed,
 }: AgentLangfuseHandlerParams): CallbackHandler | undefined {
   if (!shouldCreateLangfuseHandler(langfuse)) {
     return undefined;
   }
-  return new CallbackHandler({
+  return new ScopedLangfuseCallbackHandler({
     userId,
     sessionId,
     traceMetadata: mergeLangfuseTraceMetadata(
@@ -196,6 +301,8 @@ export function createLangfuseHandler({
       langfuse?.metadata
     ),
     tags: mergeLangfuseTags(tags, langfuse?.tags),
+    langfuse,
+    traceIdSeed,
   });
 }