@librechat/agents 3.6.7 → 3.6.9

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/tools/search/search.ts

@@ -7,6 +7,9 @@ import { createTavilyAPI } from './tavily-search';
 import { createCrwAPI } from './crw-search';
 import { BaseReranker } from './rerankers';
 
+/** Engines queried when `searxngSearchOptions.engines` is not configured. */
+const DEFAULT_SEARXNG_ENGINES = 'google,bing,duckduckgo';
+
 const chunker = {
   cleanText: (text: string): string => {
     if (!text) return '';
@@ -284,15 +287,20 @@ const createSerperAPI = (
 const createSearXNGAPI = (
   instanceUrl?: string,
   apiKey?: string,
-  agents?: t.HttpAgentConfig
+  options?: t.SearxNGSearchOptions
 ): {
   getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
 } => {
+  const engines = options?.engines?.trim();
+  const language = options?.language?.trim();
   const config = {
     instanceUrl: instanceUrl ?? process.env.SEARXNG_INSTANCE_URL,
     apiKey: apiKey ?? process.env.SEARXNG_API_KEY,
-    defaultLocation: 'all',
-    timeout: 10000,
+    engines:
+      engines != null && engines !== '' ? engines : DEFAULT_SEARXNG_ENGINES,
+    language: language != null && language !== '' ? language : 'all',
+    timeRange: options?.timeRange,
+    timeout: options?.timeout ?? 10000,
   };
 
   if (config.instanceUrl == null || config.instanceUrl === '') {
@@ -336,11 +344,15 @@ const createSearXNGAPI = (
         format: 'json',
         pageno: 1,
         categories: category,
-        language: 'all',
+        language: config.language,
         safesearch: safeSearch,
-        engines: 'google,bing,duckduckgo',
+        engines: config.engines,
       };
 
+      if (config.timeRange != null) {
+        params.time_range = config.timeRange;
+      }
+
       const headers: Record<string, string> = {
         'Content-Type': 'application/json',
       };
@@ -353,8 +365,8 @@ const createSearXNGAPI = (
         headers,
         params,
         timeout: config.timeout,
-        httpAgent: agents?.httpAgent,
-        httpsAgent: agents?.httpsAgent,
+        httpAgent: options?.httpAgent,
+        httpsAgent: options?.httpsAgent,
       });
 
       const data = response.data;
@@ -490,6 +502,7 @@ export const createSearchAPI = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    searxngSearchOptions,
     tavilyApiKey,
     tavilySearchUrl,
     tavilySearchOptions,
@@ -508,7 +521,11 @@ export const createSearchAPI = (
   if (searchProvider.toLowerCase() === 'serper') {
     return createSerperAPI(serperApiKey, agents);
   } else if (searchProvider.toLowerCase() === 'searxng') {
-    return createSearXNGAPI(searxngInstanceUrl, searxngApiKey, agents);
+    return createSearXNGAPI(searxngInstanceUrl, searxngApiKey, {
+      ...searxngSearchOptions,
+      httpAgent: httpAgent ?? searxngSearchOptions?.httpAgent,
+      httpsAgent: httpsAgent ?? searxngSearchOptions?.httpsAgent,
+    });
   } else if (searchProvider.toLowerCase() === 'tavily') {
     return createTavilyAPI(tavilyApiKey, tavilySearchUrl, {
       ...tavilySearchOptions,

package/src/tools/search/tool.ts

@@ -417,6 +417,7 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    searxngSearchOptions,
     tavilyApiKey,
     tavilySearchUrl,
     tavilyExtractUrl,
@@ -494,6 +495,7 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    searxngSearchOptions,
     tavilyApiKey,
     tavilySearchUrl,
     tavilySearchOptions: effectiveTavilySearchOptions,

package/src/tools/search/types.ts

@@ -181,11 +181,27 @@ export interface CrwSearchResponse {
   error_code?: string;
 }
 
+export interface SearxNGSearchOptions extends HttpAgentConfig {
+  /**
+   * Comma-separated list of engines to query, e.g. "google,bing,startpage".
+   * Defaults to "google,bing,duckduckgo". Engines not enabled on the target
+   * instance are ignored by SearXNG.
+   */
+  engines?: string;
+  /** Code of the language for search results. Defaults to "all". */
+  language?: string;
+  /** Time range filter, sent to SearXNG as `time_range`. Omitted when unset. */
+  timeRange?: SearxNGSearchPayload['time_range'];
+  /** HTTP request timeout in ms. Defaults to 10000. */
+  timeout?: number;
+}
+
 export interface SearchConfig extends HttpAgentConfig {
   searchProvider?: SearchProvider;
   serperApiKey?: string;
   searxngInstanceUrl?: string;
   searxngApiKey?: string;
+  searxngSearchOptions?: SearxNGSearchOptions;
   tavilyApiKey?: string;
   tavilySearchUrl?: string;
   tavilyExtractUrl?: string;

package/src/tools/subagent/SubagentExecutor.ts

@@ -2745,10 +2745,14 @@ export class SubagentExecutor {
 
         for (;;) {
           let childResult: MultiAgentGraphState;
-          if (this.humanInTheLoop?.enabled === true) {
-            /** Execute as an independently checkpointed root instead of inheriting
-             * the parent's Pregel namespace. Parent decisions are routed explicitly
-             * by interrupt id, so concurrent children keep isolated resume state. */
+          if (
+            this.humanInTheLoop?.enabled === true ||
+            params.taskRuntime != null
+          ) {
+            /** Execute as an independent LangGraph root. HITL children need an
+             * isolated Pregel namespace, while detached children must replace the
+             * parent ToolNode's ambient runnable config so its AbortSignal cannot
+             * cancel task-owned work when the parent stream settles. */
             childResult =
               await AsyncLocalStorageProviderSingleton.runWithConfig(
                 childInvokeConfig,

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;