@librechat/agents 3.6.6 → 3.6.8

package/src/run.ts

@@ -26,6 +26,16 @@ import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
+import {
+  Callback,
+  GraphEvents,
+  TitleMethod,
+  ACTIVITY_LABEL_RUN_NAME,
+  REASONING_LABEL_RUN_NAME,
+  ACTIVITY_PHASE_RUN_NAME,
+  ACTIVITY_PHASE_LABEL_RUN_NAME,
+  DEFAULT_RECURSION_LIMIT,
+} from '@/common';
 import {
   requireValidSubagentResumeManifest,
   stripSubagentResumeManifest,
@@ -58,6 +68,10 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  resolveLangfuseDestinationKey,
+  resolveLangfuseTraceAnchorParent,
+} from '@/langfuseSpanRegistry';
 import {
   appendCallbacks,
   filterCallbacks,
@@ -72,17 +86,12 @@ import {
   getRunStepResumeState,
   stripRunStepResumeState,
 } from '@/tools/runStepResume';
-import {
-  Callback,
-  GraphEvents,
-  TitleMethod,
-  DEFAULT_RECURSION_LIMIT,
-} from '@/common';
 import {
   createCompletionTitleRunnable,
   createTitleRunnable,
 } from '@/utils/title';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
+import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
@@ -986,6 +995,9 @@ export class Run<_T extends t.BaseGraphState> {
      * instead of `inputs.messages`.
      */
     const isResume = inputs instanceof Command;
+    if (!isResume) {
+      graph.startFreshLangfuseExecution();
+    }
     const stateInputs = isResume ? undefined : (inputs as t.IState);
     if (stateInputs != null) {
       this.activityPhaseTraceInput = findActivityPhaseTraceInput(
@@ -1116,6 +1128,7 @@ export class Run<_T extends t.BaseGraphState> {
         streamLangfuseConfig?.deterministicTraceId === true
           ? this.id
           : undefined,
+      traceAnchor: graph.langfuseTraceAnchor,
       // The graph's per-execution stamp, NOT the public run id: public ids
       // may repeat across concurrent executions (retries, tenant-local
       // message ids), and equal stamps defeat foreign-scope rejection.
@@ -1131,6 +1144,7 @@ export class Run<_T extends t.BaseGraphState> {
         streamLangfuseConfig?.deterministicTraceId === true
           ? this.id
           : undefined,
+      traceAnchor: graph.langfuseTraceAnchor,
       runId: graph.langfuseScopeRunId,
       // The aggregate multi-agent policy from the runtime scope — the
       // handler must restore THIS (not the primary agent's config-derived
@@ -1139,7 +1153,6 @@ export class Run<_T extends t.BaseGraphState> {
       traceName,
     });
     if (langfuseHandler != null) {
-      config.runName = traceName;
       config.callbacks = appendCallbacks(config.callbacks, [langfuseHandler]);
     }
 
@@ -1201,18 +1214,22 @@ export class Run<_T extends t.BaseGraphState> {
        * arg to `BaseGraphState`. Cast on the call so the resume path
        * type-checks without widening the wrapper for every caller.
        */
-      const stream = graphRunnable.streamEvents(inputs as t.IState, config, {
-        raiseError: true,
-        /**
-         * Prevent EventStreamCallbackHandler from processing custom events.
-         * Custom events are already handled via our createCustomEventCallback()
-         * which routes them through the handlerRegistry.
-         * Without this flag, EventStreamCallbackHandler throws errors when
-         * custom events are dispatched for run IDs not in its internal map
-         * (due to timing issues in parallel execution or after run cleanup).
-         */
-        ignoreCustomEvent: true,
-      });
+      const stream = graphRunnable.streamEvents(
+        inputs as t.IState,
+        { ...config, runName: graph.runName },
+        {
+          raiseError: true,
+          /**
+           * Prevent EventStreamCallbackHandler from processing custom events.
+           * Custom events are already handled via our createCustomEventCallback()
+           * which routes them through the handlerRegistry.
+           * Without this flag, EventStreamCallbackHandler throws errors when
+           * custom events are dispatched for run IDs not in its internal map
+           * (due to timing issues in parallel execution or after run cleanup).
+           */
+          ignoreCustomEvent: true,
+        }
+      );
 
       for await (const event of stream) {
         const { data, metadata, ...info } = event;
@@ -2123,6 +2140,7 @@ export class Run<_T extends t.BaseGraphState> {
     const labelAgentName =
       labelAgentId == null ? undefined : labelContext?.name;
     const labelMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: ACTIVITY_LABEL_RUN_NAME,
       sourceRunId: this.id,
       responseId: this.id,
       activityIndex: labelIndex,
@@ -2132,7 +2150,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(labelAgentId == null ? {} : { agentId: labelAgentId }),
       ...(labelAgentName == null ? {} : { agentName: labelAgentName }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: 'activity-label-' + this.id,
         parentMessageId: labelParentMessageId,
@@ -2150,16 +2168,9 @@ export class Run<_T extends t.BaseGraphState> {
       labelContext?.langfuse
     );
     initializeLangfuseTracing(labelLangfuseConfig);
-    /** Seed policy, threading two constraints:
-     *  1. `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so
-     *     an absent seed INHERITS the parent run's and collapses every label
-     *     into that trace. When a parent seed is active we must override it
-     *     with a per-label one.
-     *  2. Without deterministic tracing there is no parent seed, and forcing
-     *     one here would make label trace ids deterministic when neither
-     *     `processStream` nor `generateTitle` are — so leave it unset.
-     *  Seeded when determinism is opted into OR a parent seed is live;
-     *  otherwise unseeded, matching the other generation paths. */
+    /** A captured source observation parents the label in the agent trace.
+     *  The distinct seed remains the standalone fallback when labeling runs
+     *  before tracing starts or against another Langfuse destination. */
     const inheritedTraceSeed = getTraceIdSeed();
     const labelTraceSeed =
       labelLangfuseConfig?.deterministicTraceId === true ||
@@ -2174,6 +2185,15 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: labelTraceSeed,
       runId: labelScopeRunId,
     });
+    const labelParentSpanContext = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(labelLangfuseConfig),
+      labelAgentId
+    );
+    if (labelParentSpanContext != null) {
+      labelMetadata.sourceTraceId = labelParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = labelParentSpanContext.traceId;
+    }
     /** Handler only when a session id resolved from
      *  `chainOptions.configurable.thread_id`: without it the label call has
      *  no conversation identity, and tracing it would create an orphan
@@ -2187,15 +2207,18 @@ export class Run<_T extends t.BaseGraphState> {
         langfuse: labelLangfuseConfig,
         userId: labelUserId,
         sessionId: labelSessionId,
-        traceMetadata,
+        traceMetadata:
+          labelParentSpanContext == null ? traceMetadata : undefined,
         tags: labelTags,
         traceIdSeed:
           labelLangfuseConfig?.deterministicTraceId === true
             ? labelTraceSeed
             : undefined,
+        parentSpanContext: labelParentSpanContext,
+        inheritTraceIdentity: labelParentSpanContext != null,
         runId: labelScopeRunId,
         toolOutputTracing: labelRuntimeScope.toolOutputTracing,
-        traceName: labelRunName,
+        traceName: labelParentSpanContext == null ? labelRunName : undefined,
       });
     }
     if (labelLangfuseHandler != null) {
@@ -2297,9 +2320,11 @@ export class Run<_T extends t.BaseGraphState> {
           langfuse: labelLangfuseConfig,
           userId: labelUserId,
           sessionId: labelSessionId,
-          traceName: labelRunName,
-          traceMetadata,
+          traceName: labelParentSpanContext == null ? labelRunName : undefined,
+          traceMetadata:
+            labelParentSpanContext == null ? traceMetadata : undefined,
           tags: labelTags,
+          inheritTraceIdentity: labelParentSpanContext != null,
         },
         () =>
           model.invoke(
@@ -2457,6 +2482,7 @@ export class Run<_T extends t.BaseGraphState> {
     const resolvedSourceRunId = sourceRunId ?? this.id;
     const reasoningResponseId = responseId ?? this.id;
     const reasoningMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: REASONING_LABEL_RUN_NAME,
       sourceRunId: resolvedSourceRunId,
       ...(sourceTraceId == null ? {} : { sourceTraceId }),
       responseId: reasoningResponseId,
@@ -2470,7 +2496,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(reasoningAgentId == null ? {} : { agentId: reasoningAgentId }),
       ...(reasoningAgentName == null ? {} : { agentName: reasoningAgentName }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: `reasoning-label-${reasoningResponseId}`,
         parentMessageId: reasoningParentMessageId,
@@ -2512,21 +2538,40 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: reasoningTraceSeed,
       runId: reasoningScopeRunId,
     });
+    const candidateReasoningParent = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(reasoningLangfuseConfig),
+      reasoningAgentId
+    );
+    const reasoningParentSpanContext =
+      resolvedSourceRunId === this.id &&
+      (sourceTraceId == null ||
+        sourceTraceId === candidateReasoningParent?.traceId)
+        ? candidateReasoningParent
+        : undefined;
+    if (reasoningParentSpanContext != null) {
+      reasoningMetadata.sourceTraceId = reasoningParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = reasoningParentSpanContext.traceId;
+    }
     let reasoningLangfuseHandler: CallbackEntry | undefined;
     if (reasoningSessionId != null) {
       reasoningLangfuseHandler = createLangfuseHandler({
         langfuse: reasoningLangfuseConfig,
         userId: reasoningUserId,
         sessionId: reasoningSessionId,
-        traceMetadata,
+        traceMetadata:
+          reasoningParentSpanContext == null ? traceMetadata : undefined,
         tags: reasoningTags,
         traceIdSeed:
           reasoningLangfuseConfig?.deterministicTraceId === true
             ? reasoningTraceSeed
             : undefined,
+        parentSpanContext: reasoningParentSpanContext,
+        inheritTraceIdentity: reasoningParentSpanContext != null,
         runId: reasoningScopeRunId,
         toolOutputTracing: reasoningRuntimeScope.toolOutputTracing,
-        traceName: reasoningRunName,
+        traceName:
+          reasoningParentSpanContext == null ? reasoningRunName : undefined,
       });
     }
     if (reasoningLangfuseHandler != null) {
@@ -2585,9 +2630,12 @@ export class Run<_T extends t.BaseGraphState> {
           langfuse: reasoningLangfuseConfig,
           userId: reasoningUserId,
           sessionId: reasoningSessionId,
-          traceName: reasoningRunName,
-          traceMetadata,
+          traceName:
+            reasoningParentSpanContext == null ? reasoningRunName : undefined,
+          traceMetadata:
+            reasoningParentSpanContext == null ? traceMetadata : undefined,
           tags: reasoningTags,
+          inheritTraceIdentity: reasoningParentSpanContext != null,
         },
         () =>
           model.invoke(
@@ -2638,9 +2686,10 @@ export class Run<_T extends t.BaseGraphState> {
 
   /**
    * Generates one parent summary for two or more logical activities. The
-   * summary model is traced as a dedicated activity-phase chain root in the
-   * conversation session, with the model callback recorded as its generation
-   * child. No session id means no phase trace, avoiding orphan observations.
+   * summary model is traced as an activity-phase chain beneath the source
+   * agent run, with the model callback recorded as its generation child. It
+   * falls back to a dedicated trace when no source observation is available.
+   * No session id means no phase trace, avoiding orphan observations.
    */
   async generateActivityPhaseLabel({
     provider,
@@ -2771,6 +2820,7 @@ export class Run<_T extends t.BaseGraphState> {
     const phaseParentMessageId =
       phaseChainOptions.configurable?.requestBody?.parentMessageId;
     const phaseMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: ACTIVITY_PHASE_LABEL_RUN_NAME,
       sourceRunId: sourceRunId ?? this.id,
       ...(sourceTraceId == null ? {} : { sourceTraceId }),
       responseId: phaseMessageId,
@@ -2785,7 +2835,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(phaseAgentName == null ? {} : { agentName: phaseAgentName }),
       ...(closingTextPhase == null ? {} : { closingTextPhase }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: phaseMessageId,
         parentMessageId: phaseParentMessageId,
@@ -2826,6 +2876,19 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: phaseTraceSeed,
       runId: phaseScopeRunId,
     });
+    const candidatePhaseParent = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(phaseLangfuseConfig)
+    );
+    const phaseParentSpanContext =
+      (sourceRunId == null || sourceRunId === this.id) &&
+      (sourceTraceId == null || sourceTraceId === candidatePhaseParent?.traceId)
+        ? candidatePhaseParent
+        : undefined;
+    if (phaseParentSpanContext != null) {
+      phaseMetadata.sourceTraceId = phaseParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = phaseParentSpanContext.traceId;
+    }
     let phaseLangfuseHandler: CallbackEntry | undefined;
     const sourceUserText =
       this.activityPhaseTraceInput ??
@@ -2835,15 +2898,18 @@ export class Run<_T extends t.BaseGraphState> {
         langfuse: phaseLangfuseConfig,
         userId: phaseUserId,
         sessionId: phaseSessionId,
-        traceMetadata,
+        traceMetadata:
+          phaseParentSpanContext == null ? traceMetadata : undefined,
         tags: phaseTags,
         traceIdSeed:
           phaseLangfuseConfig?.deterministicTraceId === true
             ? phaseTraceSeed
             : undefined,
+        parentSpanContext: phaseParentSpanContext,
+        inheritTraceIdentity: phaseParentSpanContext != null,
         runId: phaseScopeRunId,
         toolOutputTracing: phaseRuntimeScope.toolOutputTracing,
-        traceName: phaseTraceName,
+        traceName: phaseParentSpanContext == null ? phaseTraceName : undefined,
       });
     }
     if (phaseLangfuseHandler != null) {
@@ -2864,7 +2930,7 @@ export class Run<_T extends t.BaseGraphState> {
     const invokeConfig = Object.assign({}, phaseChainOptions, {
       run_id: phaseRunId,
       runId: phaseRunId,
-      runName: 'summarize-activity-phase',
+      runName: ACTIVITY_PHASE_RUN_NAME,
       tags: [...new Set([...(phaseChainOptions.tags ?? []), ...phaseTags])],
       metadata: {
         ...(phaseChainOptions.metadata ?? {}),
@@ -2943,7 +3009,7 @@ export class Run<_T extends t.BaseGraphState> {
           ? { label, messages: [new AIMessage(label)] }
           : { messages: [] };
       },
-    }).withConfig({ runName: 'summarize-activity-phase' });
+    }).withConfig({ runName: ACTIVITY_PHASE_RUN_NAME });
 
     try {
       const result = await withLangfuseRuntimeScope(phaseRuntimeScope, () =>
@@ -2952,9 +3018,12 @@ export class Run<_T extends t.BaseGraphState> {
             langfuse: phaseLangfuseConfig,
             userId: phaseUserId,
             sessionId: phaseSessionId,
-            traceName: phaseTraceName,
-            traceMetadata,
+            traceName:
+              phaseParentSpanContext == null ? phaseTraceName : undefined,
+            traceMetadata:
+              phaseParentSpanContext == null ? traceMetadata : undefined,
             tags: phaseTags,
+            inheritTraceIdentity: phaseParentSpanContext != null,
           },
           () =>
             phaseRunnable.invoke(

package/src/types/activityLabel.ts

@@ -62,8 +62,9 @@ export type RunActivityLabelOptions = {
   };
   /**
    * Seed for deterministic Langfuse trace ids (e.g. `${runId}-${slotIndex}`)
-   * so each batch's label gets a distinct, reproducible trace. When omitted,
-   * a per-run sequence keeps batches from collapsing into one trace.
+   * for a distinct, reproducible fallback trace when the source agent
+   * observation is unavailable. Normally the label is parented into the
+   * source agent trace instead.
    */
   traceSeed?: string;
 };
@@ -112,7 +113,7 @@ export type RunActivityPhaseLabelOptions = {
   traceSeed?: string;
   /** Stable source run identifier recorded on the phase observation. */
   sourceRunId?: string;
-  /** Source Langfuse trace id for linking this detached summary trace. */
+  /** Source Langfuse trace id retained as correlation metadata. */
   sourceTraceId?: string;
   /** Host response/message identifier recorded on the phase observation. */
   responseId?: string;

package/src/types/reasoningLabel.ts

@@ -52,7 +52,7 @@ export type RunReasoningLabelOptions = {
   traceSeed?: string;
   /** Stable source run identifier recorded on the observation. */
   sourceRunId?: string;
-  /** Source Langfuse trace id for linking this detached label trace. */
+  /** Source Langfuse trace id retained as correlation metadata. */
   sourceTraceId?: string;
   /** Host response/message identifier recorded on the observation. */
   responseId?: string;

package/src/utils/tokens.ts

@@ -120,6 +120,10 @@ const MAX_STRUCTURED_TOKENIZATION_CHARS = 200_000;
 /** One UTF-16 character can encode to several tokenizer pieces. */
 const MAX_TOKENS_PER_OMITTED_STRUCTURED_CHAR = 4;
 const MAX_STRUCTURED_SAFETY_INSPECTION_WORK = 10_000;
+/** Bounds BPE work per plain-text segment without omitting any text. */
+const MAX_TEXT_TOKENIZATION_CHARS = 8_192;
+/** Covers tokenizer segmentation changes on both sides of a chunk boundary. */
+const TEXT_TOKEN_CHUNK_BOUNDARY_SAFETY_TOKENS = 4;
 
 /**
  * Extracts image dimensions from the first bytes of a base64-encoded
@@ -886,22 +890,24 @@ function getBoundedTextTokenCount(
   value: string,
   getTokenCount: (text: string) => number
 ): number {
-  const preview =
-    value.length > MAX_STRUCTURED_TOKENIZATION_CHARS
-      ? value.slice(0, MAX_STRUCTURED_TOKENIZATION_CHARS)
-      : value;
-  const previewTokens = ensureSafeTokenMeasurement(
-    getTokenCount(preview),
-    'tokenizer'
-  );
-  const omittedChars = value.length - preview.length;
-  if (omittedChars <= 0) {
-    return previewTokens;
+  let numTokens = 0;
+  for (
+    let offset = 0;
+    offset < value.length;
+    offset += MAX_TEXT_TOKENIZATION_CHARS
+  ) {
+    const chunkTokens = ensureSafeTokenMeasurement(
+      getTokenCount(value.slice(offset, offset + MAX_TEXT_TOKENIZATION_CHARS)),
+      'tokenizer'
+    );
+    const boundaryTokens =
+      offset > 0 ? TEXT_TOKEN_CHUNK_BOUNDARY_SAFETY_TOKENS : 0;
+    numTokens = Math.min(
+      Number.MAX_SAFE_INTEGER,
+      numTokens + chunkTokens + boundaryTokens
+    );
   }
-  return Math.min(
-    Number.MAX_SAFE_INTEGER,
-    previewTokens + omittedChars * MAX_TOKENS_PER_OMITTED_STRUCTURED_CHAR
-  );
+  return numTokens;
 }
 
 function getBoundedStructuredTokenCount(