@librechat/agents 3.6.7 → 3.6.9

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);
   }

package/src/langfuseTraceShaping.ts

@@ -1,9 +1,21 @@
 import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { Constants } from '@/common';
+import {
+  Constants,
+  STANDARD_GRAPH_RUN_NAME,
+  MULTI_AGENT_GRAPH_RUN_NAME,
+  AGENT_MODEL_CALL_RUN_NAME,
+  ACTIVITY_LABEL_RUN_NAME,
+  REASONING_LABEL_RUN_NAME,
+  ACTIVITY_PHASE_RUN_NAME,
+  ACTIVITY_PHASE_LABEL_RUN_NAME,
+} from '@/common';
+import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 
 const LANGGRAPH_START_NODE = '__start__';
+const LANGGRAPH_RUN_NAME = 'LangGraph';
 const ANONYMOUS_LAMBDA_NAME = 'RunnableLambda';
+const RUNNABLE_SEQUENCE_NAME = 'RunnableSequence';
 const LANGGRAPH_AGENT_NODE_PREFIX = 'agent=';
 const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
 const AGENT_NODE_SPAN_NAME = 'agent';
@@ -14,11 +26,15 @@ const CHAIN_OBSERVATION_TYPE = 'chain';
 const TOOL_OBSERVATION_TYPE = 'tool';
 const AGENT_TRACE_TAG = 'agent';
 const TITLE_TRACE_TAG = 'title';
+const ACTIVITY_LABEL_TRACE_TAG = 'activity-label';
+const REASONING_LABEL_TRACE_TAG = 'reasoning-label';
 const ACTIVITY_PHASE_TRACE_TAG = 'activity-phase';
-const ACTIVITY_PHASE_ROOT_NAME = 'summarize-activity-phase';
 const EPHEMERAL_AGENT_SENDER_SEPARATOR = '___';
 const EPHEMERAL_AGENT_INDEX_SEPARATOR = '____';
+const DEPRECATED_TRACE_INPUT_ATTRIBUTE = 'langfuse.trace.input';
+const DEPRECATED_TRACE_OUTPUT_ATTRIBUTE = 'langfuse.trace.output';
 const OBSERVATION_METADATA_LANGGRAPH_NODE = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`;
+const OBSERVATION_METADATA_OPERATION = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.${LANGFUSE_OPERATION_METADATA_KEY}`;
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -192,9 +208,7 @@ function getMessageToolCalls(
  */
 /** Tool-result ids present in the serialized state — ToolNode's
  *  `!toolMessageIds.has(id)` execution filter, mirrored for the span. */
-function getToolResultIds(
-  messages: Record<string, unknown>[]
-): Set<string> {
+function getToolResultIds(messages: Record<string, unknown>[]): Set<string> {
   const ids = new Set<string>();
   for (const message of messages) {
     if (getMessageRole(message) !== 'tool') {
@@ -217,7 +231,9 @@ function getMessageInvalidToolCalls(
 ): SerializedToolCall[] {
   const rawCalls =
     message.invalid_tool_calls ??
-    (isRecord(message.kwargs) ? message.kwargs.invalid_tool_calls : undefined) ??
+    (isRecord(message.kwargs)
+      ? message.kwargs.invalid_tool_calls
+      : undefined) ??
     (isRecord(message.data) ? message.data.invalid_tool_calls : undefined);
   if (!Array.isArray(rawCalls)) {
     return [];
@@ -345,7 +361,80 @@ function shapeAgentNodeSpan(span: MutableSpan): void {
     ROOT_OBSERVATION_TYPE;
 }
 
-function shapeRootSpan(span: MutableSpan): void {
+function shapeGraphSpan(span: MutableSpan): void {
+  if (span.name === LANGGRAPH_RUN_NAME) {
+    span.name = STANDARD_GRAPH_RUN_NAME;
+  }
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    ROOT_OBSERVATION_TYPE;
+}
+
+function isAgentModelCallSpan(span: MutableSpan): boolean {
+  if (
+    span.name !== RUNNABLE_SEQUENCE_NAME &&
+    span.name !== AGENT_MODEL_CALL_RUN_NAME
+  ) {
+    return false;
+  }
+  const node = span.attributes[OBSERVATION_METADATA_LANGGRAPH_NODE];
+  return (
+    typeof node === 'string' && node.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)
+  );
+}
+
+function shapeAgentModelCallSpan(span: MutableSpan): void {
+  span.name = AGENT_MODEL_CALL_RUN_NAME;
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    CHAIN_OBSERVATION_TYPE;
+}
+
+function shapeActivityPhaseSpan(span: MutableSpan): void {
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    CHAIN_OBSERVATION_TYPE;
+}
+
+function shapeGenerationSpan(span: MutableSpan): void {
+  if (
+    hasTraceTag(span, ACTIVITY_LABEL_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] === ACTIVITY_LABEL_RUN_NAME
+  ) {
+    span.name = ACTIVITY_LABEL_RUN_NAME;
+    return;
+  }
+  if (
+    hasTraceTag(span, REASONING_LABEL_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] === REASONING_LABEL_RUN_NAME
+  ) {
+    span.name = REASONING_LABEL_RUN_NAME;
+    return;
+  }
+  if (
+    hasTraceTag(span, ACTIVITY_PHASE_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] ===
+      ACTIVITY_PHASE_LABEL_RUN_NAME
+  ) {
+    span.name = ACTIVITY_PHASE_LABEL_RUN_NAME;
+    return;
+  }
+  span.name = GENERATION_SPAN_NAME;
+}
+
+function isGraphSpan(span: MutableSpan): boolean {
+  if (
+    span.name !== LANGGRAPH_RUN_NAME &&
+    span.name !== STANDARD_GRAPH_RUN_NAME &&
+    span.name !== MULTI_AGENT_GRAPH_RUN_NAME
+  ) {
+    return false;
+  }
+  return (
+    isRootSpan(span) ||
+    typeof span.attributes[OBSERVATION_METADATA_LANGGRAPH_NODE] === 'string' ||
+    hasTraceTag(span, AGENT_TRACE_TAG)
+  );
+}
+
+function shapeConversationPayload(span: MutableSpan): void {
   const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
   const outputKey = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
   const question = findLastMessageText(
@@ -361,8 +450,7 @@ function shapeRootSpan(span: MutableSpan): void {
    *  observation carrying its own prompt: reducing its observation input
    *  would discard the SystemMessage from the one place it is traced.
    *  Chain/agent roots keep the full reduction; their child generations
-   *  still record the complete prompt. Trace-level input/output reduce
-   *  either way, so the trace list keeps showing question and answer. */
+   *  still record the complete prompt. */
   if (!isGenerationSpan(span)) {
     if (question != null) {
       span.attributes[inputKey] = question;
@@ -371,14 +459,6 @@ function shapeRootSpan(span: MutableSpan): void {
       span.attributes[outputKey] = answer;
     }
   }
-  const traceInput = question ?? span.attributes[inputKey];
-  const traceOutput = answer ?? span.attributes[outputKey];
-  if (traceInput != null) {
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = traceInput;
-  }
-  if (traceOutput != null) {
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = traceOutput;
-  }
 }
 
 function isGenerationSpan(span: MutableSpan): boolean {
@@ -477,7 +557,7 @@ function shapeRootObservationType(span: MutableSpan): void {
   }
   if (
     hasTraceTag(span, TITLE_TRACE_TAG) ||
-    (span.name === ACTIVITY_PHASE_ROOT_NAME &&
+    (span.name === ACTIVITY_PHASE_RUN_NAME &&
       hasTraceTag(span, ACTIVITY_PHASE_TRACE_TAG))
   ) {
     span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
@@ -496,32 +576,46 @@ function shapeRootObservationType(span: MutableSpan): void {
  *   (`provider__model`) — strip it so switching models doesn't break
  *   name-based logic (item 1). The outer workflow node is named with the
  *   bare agent id; ephemeral ids reduce to their stable sender name.
+ * - Graph and prompt-to-model framework names become stable SDK operations:
+ *   `AgentGraph` / `MultiAgentGraph` and `AgentModelCall`.
  * - LLM generation spans keep the provider client class name (`ChatOpenAI`,
- *   `AzureChatOpenAI`, …); rename them to a provider-agnostic `llm` so the
- *   name reflects the operation, not the model (the model stays on the
- *   generation's model attribute).
+ *   `AzureChatOpenAI`, …); rename ordinary calls to a provider-agnostic `llm`
+ *   and label calls by their activity/reasoning role. The model stays on the
+ *   generation's model attribute.
  * - Agent nodes become `agent` observations, while tool-dispatch nodes become
  *   stable `chain` observations whose input is scoped to the pending calls.
  *   Individual child calls remain `tool` observations (items 3 & 4).
  * - Agent trace roots become `agent` observations, while title and activity
- *   summary roots become `chain` observations. Root and trace input/output are
- *   reduced to the user question and assistant response when chat messages are
- *   available (item 2).
+ *   summary operations become `chain` observations. Root-observation
+ *   input/output are reduced to the user question and assistant response when
+ *   chat messages are available (item 2).
  */
 export function shapeLangfuseSpan(span: ReadableSpan): void {
   const mutable = span as MutableSpan;
+  delete mutable.attributes[DEPRECATED_TRACE_INPUT_ATTRIBUTE];
+  delete mutable.attributes[DEPRECATED_TRACE_OUTPUT_ATTRIBUTE];
+  const isGraphObservation = isGraphSpan(mutable);
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
     shapeAgentNodeSpan(mutable);
   } else if (mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX)) {
     shapeToolNodeSpan(mutable);
+  } else if (isGraphObservation) {
+    shapeGraphSpan(mutable);
+  } else if (isAgentModelCallSpan(mutable)) {
+    shapeAgentModelCallSpan(mutable);
+  } else if (mutable.name === ACTIVITY_PHASE_RUN_NAME) {
+    shapeActivityPhaseSpan(mutable);
   } else if (isGenerationSpan(mutable)) {
-    mutable.name = GENERATION_SPAN_NAME;
+    shapeGenerationSpan(mutable);
   } else {
     shapeEphemeralAgentNodeSpan(mutable);
   }
   if (!isRootSpan(span)) {
+    if (isGraphObservation) {
+      shapeConversationPayload(mutable);
+    }
     return;
   }
   shapeRootObservationType(mutable);
-  shapeRootSpan(mutable);
+  shapeConversationPayload(mutable);
 }

package/src/llm/openai/index.ts

@@ -58,14 +58,14 @@ import {
   STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY,
   OPENAI_CHAT_SEQUENTIAL_STREAMED_TOOL_CALL_ADAPTER,
 } from '@/tools/streamedToolCallSeals';
-import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
-import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
-import { smoothStream, resolveStreamDelay } from '@/llm/stream/smoother';
 import {
   hasReasoningKwargs,
   hasToolCallChunks,
   getReasoningKwargsText,
 } from '@/llm/stream/chunkAdapters';
+import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
+import { smoothStream, resolveStreamDelay } from '@/llm/stream/smoother';
+import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
 import { dropRepeatedScalarMetadata } from './streamMetadata';
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -919,6 +919,33 @@ function attachResponsesReplayPosition(
   chunk.message.lc_kwargs.additional_kwargs = additionalKwargs;
 }
 
+function getResponsesStreamError(
+  event: OpenAIClient.Responses.ResponseStreamEvent
+): Error | undefined {
+  if (event.type === 'error') {
+    return new OpenAIClient.APIError(
+      undefined,
+      event,
+      event.message,
+      undefined
+    );
+  }
+  if (event.type !== 'response.failed') {
+    return;
+  }
+  if (event.response.error != null) {
+    return new OpenAIClient.APIError(
+      undefined,
+      event.response.error,
+      event.response.error.message,
+      undefined
+    );
+  }
+  return new OpenAIClient.OpenAIError(
+    `Response ${event.response.id} failed without error details.`
+  );
+}
+
 async function* convertLibreChatResponsesStream(
   stream: AsyncIterable<OpenAIClient.Responses.ResponseStreamEvent>,
   options: ResponsesStreamChunkOptions,
@@ -929,6 +956,10 @@ async function* convertLibreChatResponsesStream(
   try {
     for await (const event of stream) {
       options.signal?.throwIfAborted();
+      const streamError = getResponsesStreamError(event);
+      if (streamError != null) {
+        throw streamError;
+      }
       const convertedChunk =
         convertResponsesDeltaToChatGenerationChunk(event) ??
         convertDroppedResponsesReplayOutput(event);