@librechat/agents 3.7.7 → 3.7.9

package/src/langfuse.ts

@@ -79,6 +79,8 @@ type LangfuseHandlerParams = {
    *  only adopted when stamped with the same run (see
    *  `LangfuseRuntimeContext.runId`). */
   runId?: string;
+  /** Keep this root open while one processStream call executes graph segments. */
+  deferRootRunId?: string;
   /** The run's resolved tool-output policy — for multi-agent streams the
    *  conservative aggregate across agents, which `this.langfuse` (the
    *  primary agent's config) cannot reproduce. Applied when a foreign
@@ -293,9 +295,19 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   private readonly agentId?: string;
   private readonly parentSpanContext?: SpanContext;
   private readonly runId?: string;
+  private readonly deferredRootRunId?: string;
   private readonly identity: HandlerIdentity;
   private readonly toolOutputTracing?: ResolvedLangfuseToolOutputTracingConfig;
   private readonly trackedRunIds = new Set<string>();
+  private deferredRootStarted = false;
+  private deferredRootOutcome:
+    | {
+      type: 'end';
+      output: Parameters<CallbackHandler['handleChainEnd']>[0];
+      parentRunId?: string;
+    }
+    | { type: 'error'; error: Error; parentRunId?: string }
+    | undefined;
 
   constructor(params?: AgentLangfuseHandlerParams) {
     const {
@@ -306,6 +318,7 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
       parentSpanContext,
       inheritTraceIdentity,
       runId,
+      deferRootRunId,
       toolOutputTracing,
       traceName,
       ...handlerParams
@@ -326,6 +339,10 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     this.agentId = agentId;
     this.parentSpanContext = parentSpanContext;
     this.runId = runId;
+    this.deferredRootRunId = deferRootRunId;
+    if (deferRootRunId != null) {
+      this.awaitHandlers = true;
+    }
     this.toolOutputTracing = toolOutputTracing;
     this.identity = {
       userId: inheritTraceIdentity === true ? undefined : handlerParams.userId,
@@ -528,6 +545,17 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
   override handleChainStart(
     ...args: Parameters<CallbackHandler['handleChainStart']>
   ): ReturnType<CallbackHandler['handleChainStart']> {
+    const [, , runId, parentRunId] = args;
+    if (
+      runId === this.deferredRootRunId &&
+      parentRunId == null &&
+      this.deferredRootStarted
+    ) {
+      return Promise.resolve();
+    }
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootStarted = true;
+    }
     return this.withRuntimeContext(
       () => super.handleChainStart(...args),
       this.startsDetachedRun(args[2], args[3]),
@@ -539,6 +567,13 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     ...args: Parameters<CallbackHandler['handleChainError']>
   ): ReturnType<CallbackHandler['handleChainError']> {
     const [error, runId, parentRunId] = args;
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootOutcome = {
+        type: 'error',
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+      return Promise.resolve();
+    }
     if (error != null && parentRunId != null && isGraphInterrupt(error)) {
       return super.handleChainEnd(
         GRAPH_INTERRUPT_CONTROL_FLOW,
@@ -556,6 +591,36 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     return super.handleChainError(...args);
   }
 
+  override handleChainEnd(
+    ...args: Parameters<CallbackHandler['handleChainEnd']>
+  ): ReturnType<CallbackHandler['handleChainEnd']> {
+    const [output, runId, parentRunId] = args;
+    if (runId === this.deferredRootRunId && parentRunId == null) {
+      this.deferredRootOutcome = { type: 'end', output };
+      return Promise.resolve();
+    }
+    return super.handleChainEnd(...args);
+  }
+
+  async finishDeferredRoot(): Promise<void> {
+    const runId = this.deferredRootRunId;
+    const outcome = this.deferredRootOutcome;
+    if (!this.deferredRootStarted || runId == null || outcome == null) {
+      return;
+    }
+    this.deferredRootStarted = false;
+    this.deferredRootOutcome = undefined;
+    if (outcome.type === 'error') {
+      await super.handleChainError(
+        outcome.error,
+        runId,
+        outcome.parentRunId
+      );
+      return;
+    }
+    await super.handleChainEnd(outcome.output, runId, outcome.parentRunId);
+  }
+
   override handleAgentAction(
     ...args: Parameters<CallbackHandler['handleAgentAction']>
   ): ReturnType<CallbackHandler['handleAgentAction']> {
@@ -792,6 +857,7 @@ export function createLangfuseHandler({
   parentSpanContext,
   inheritTraceIdentity,
   runId,
+  deferRootRunId,
   toolOutputTracing,
   traceName,
 }: AgentLangfuseHandlerParams): CallbackHandler | undefined {
@@ -813,6 +879,7 @@ export function createLangfuseHandler({
     parentSpanContext,
     inheritTraceIdentity,
     runId,
+    deferRootRunId,
     toolOutputTracing,
     traceName,
   });
@@ -865,6 +932,9 @@ export function isLangfuseCallbackHandler(value: unknown): boolean {
 }
 
 export async function disposeLangfuseHandler(value: unknown): Promise<void> {
+  if (value instanceof ScopedLangfuseCallbackHandler) {
+    await value.finishDeferredRoot();
+  }
   if (
     value == null ||
     parseBooleanEnv(process.env[LANGFUSE_FORCE_FLUSH_ON_DISPOSE]) !== true

package/src/langfuseTraceShaping.ts

@@ -35,6 +35,11 @@ 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}`;
+const OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.compaction_semantic_index_entries`;
+const COMPACTION_SEMANTIC_INDEX_OPEN = '<compaction-semantic-index>';
+const COMPACTION_SEMANTIC_INDEX_CLOSE = '</compaction-semantic-index>';
+const REDACTED_COMPACTION_SEMANTIC_INDEX =
+  '<compaction-semantic-index redacted="true" />\n\n';
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -66,6 +71,94 @@ function parseAttributeValue(value: unknown): unknown {
   }
 }
 
+type CompactionSemanticIndexRedaction = {
+  value: unknown;
+  redacted: boolean;
+};
+
+function redactCompactionSemanticIndexText(
+  value: string
+): CompactionSemanticIndexRedaction {
+  if (!value.startsWith(COMPACTION_SEMANTIC_INDEX_OPEN)) {
+    return { value, redacted: false };
+  }
+  const start = 0;
+  const close = value.indexOf(COMPACTION_SEMANTIC_INDEX_CLOSE, start);
+  if (close < 0) {
+    return { value, redacted: false };
+  }
+  let end = close + COMPACTION_SEMANTIC_INDEX_CLOSE.length;
+  while (end < value.length && /\s/.test(value[end])) {
+    end++;
+  }
+  return {
+    value:
+      value.slice(0, start) +
+      REDACTED_COMPACTION_SEMANTIC_INDEX +
+      value.slice(end),
+    redacted: true,
+  };
+}
+
+function redactCompactionSemanticIndexValue(
+  value: unknown
+): CompactionSemanticIndexRedaction {
+  if (typeof value === 'string') {
+    return redactCompactionSemanticIndexText(value);
+  }
+  if (Array.isArray(value)) {
+    for (let index = value.length - 1; index >= 0; index--) {
+      const nested = redactCompactionSemanticIndexValue(value[index]);
+      if (nested.redacted) {
+        const result = [...value];
+        result[index] = nested.value;
+        return { value: result, redacted: true };
+      }
+    }
+    return { value, redacted: false };
+  }
+  if (!isRecord(value)) {
+    return { value, redacted: false };
+  }
+  const entries = Object.entries(value);
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const [key, nestedValue] = entries[index];
+    const nested = redactCompactionSemanticIndexValue(nestedValue);
+    if (nested.redacted) {
+      return {
+        value: { ...value, [key]: nested.value },
+        redacted: true,
+      };
+    }
+  }
+  return { value, redacted: false };
+}
+
+function redactCompactionSemanticIndexInput(span: MutableSpan): void {
+  const entryCount =
+    span.attributes[
+      OBSERVATION_METADATA_COMPACTION_SEMANTIC_INDEX_ENTRIES
+    ];
+  const numericEntryCount = Number(entryCount);
+  if (!Number.isFinite(numericEntryCount) || numericEntryCount <= 0) {
+    return;
+  }
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const input = span.attributes[inputKey];
+  if (input == null) {
+    return;
+  }
+  const parsed = parseAttributeValue(input);
+  const redaction = redactCompactionSemanticIndexValue(parsed);
+  if (!redaction.redacted) {
+    return;
+  }
+  span.attributes[inputKey] =
+    typeof redaction.value === 'string' && parsed === input
+      ? redaction.value
+      : JSON.stringify(redaction.value);
+}
+
 function getMessageArray(
   value: unknown
 ): Record<string, unknown>[] | undefined {
@@ -594,6 +687,7 @@ 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];
+  redactCompactionSemanticIndexInput(mutable);
   const isGraphObservation = isGraphSpan(mutable);
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
     shapeAgentNodeSpan(mutable);

package/src/llm/fake.ts

@@ -14,6 +14,15 @@ export class FakeChatModel extends FakeListChatModel {
   private splitStrategy: SplitStrategy;
   private toolCalls: ToolCall[] = [];
   private addedToolCalls: boolean = false;
+  /**
+   * Attached to the last streamed chunk of every response, mirroring a real
+   * provider's terminal `finish_reason`/`stop_reason` on `generationInfo`.
+   * Lets truncation-path tests (`getTruncationStopReason`) drive a genuine
+   * `Run`/`StandardGraph` without a live provider. `undefined` (the
+   * default) reproduces the previous behavior exactly: no metadata on any
+   * chunk.
+   */
+  private finalChunkGenerationInfo?: Record<string, unknown>;
 
   constructor({
     responses,
@@ -21,16 +30,19 @@ export class FakeChatModel extends FakeListChatModel {
     emitCustomEvent,
     splitStrategy = { type: 'regex', value: /(?<=\s+)|(?=\s+)/ },
     toolCalls = [],
+    finalChunkGenerationInfo,
   }: {
     responses: string[];
     sleep?: number;
     emitCustomEvent?: boolean;
     splitStrategy?: SplitStrategy;
     toolCalls?: ToolCall[];
+    finalChunkGenerationInfo?: Record<string, unknown>;
   }) {
     super({ responses, sleep, emitCustomEvent });
     this.splitStrategy = splitStrategy;
     this.toolCalls = toolCalls;
+    this.finalChunkGenerationInfo = finalChunkGenerationInfo;
   }
 
   private splitText(text: string): string[] {
@@ -47,14 +59,16 @@ export class FakeChatModel extends FakeListChatModel {
   }
   _createResponseChunk(
     text: string,
-    tool_call_chunks?: ToolCallChunk[]
+    tool_call_chunks?: ToolCallChunk[],
+    responseMetadata?: Record<string, unknown>
   ): ChatGenerationChunk {
     return new ChatGenerationChunk({
       text,
-      generationInfo: {},
+      generationInfo: responseMetadata ?? {},
       message: new AIMessageChunk({
         content: text,
         tool_call_chunks,
+        response_metadata: responseMetadata,
         additional_kwargs: tool_call_chunks
           ? {
             tool_calls: tool_call_chunks.map((toolCall) => ({
@@ -87,14 +101,31 @@ export class FakeChatModel extends FakeListChatModel {
     }
 
     const chunks = this.splitText(response);
-    for await (const chunk of chunks) {
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
       await this._sleepIfRequested();
 
       if (options.thrownErrorString != null && options.thrownErrorString) {
         throw new Error(options.thrownErrorString);
       }
 
-      const responseChunk = super._createResponseChunk(chunk);
+      /**
+       * Only the true terminal chunk of the response gets the metadata: when
+       * this response also appends a trailing tool-call chunk below, THAT
+       * chunk is terminal instead (not currently exercised by any test —
+       * a caller wanting truncated-tool-call metadata should attach it
+       * there).
+       */
+      const isTerminalChunk =
+        i === chunks.length - 1 && this.toolCalls.length === 0;
+      const responseChunk =
+        isTerminalChunk && this.finalChunkGenerationInfo != null
+          ? this._createResponseChunk(
+            chunk,
+            undefined,
+            this.finalChunkGenerationInfo
+          )
+          : super._createResponseChunk(chunk);
       yield responseChunk;
       void runManager?.handleLLMNewToken(chunk);
     }

package/src/llm/invoke.ts

@@ -27,6 +27,12 @@ import {
   STREAM_LIMIT_REDISPATCH_KEY,
   STREAM_LIMIT_ATTEMPT_KEY,
 } from '@/llm/streamLimits';
+import {
+  inspectProviderMessageProjection,
+  ProviderMessageProjectionInvariantError,
+  resolveProviderMessageProjectionInvariantMode,
+  modifyDeltaProperties,
+} from '@/messages';
 import {
   assertPreparedProviderRequestFor,
   prepareProviderRequest,
@@ -38,15 +44,10 @@ import {
 import { ChatModelStreamHandler, dispatchesChatModelStream } from '@/stream';
 import { Constants, ContentTypes, GraphEvents, Providers } from '@/common';
 import { assertNotTruncatedToolCall } from '@/llm/truncation';
+import { resolveClientOptionsModel } from '@/llm/request';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { getContextOverflowInfo } from '@/utils/errors';
 import { appendCallbacks } from '@/utils/callbacks';
-import {
-  inspectProviderMessageProjection,
-  ProviderMessageProjectionInvariantError,
-  resolveProviderMessageProjectionInvariantMode,
-  modifyDeltaProperties,
-} from '@/messages';
 import { canSealPreempt } from '@/llm/preempt';
 import { initializeModel } from '@/llm/init';
 
@@ -715,8 +716,7 @@ async function attemptInvokeBody(
     resolveProviderMessageProjectionInvariantMode();
   let sealedRunId: string | undefined;
   let invocationConfig = config;
-  const captureModelRunId =
-    model.stream != null && context?.preemption != null;
+  const captureModelRunId = model.stream != null && context?.preemption != null;
   if (projectionInvariantMode !== 'off' || captureModelRunId) {
     invocationConfig = withModelStartHandler({
       config,
@@ -934,7 +934,10 @@ async function attemptInvokeBody(
     return { messages: [finalChunk as AIMessageChunk] };
   }
 
-  const finalMessage = await model.invoke(messagesForProvider, invocationConfig);
+  const finalMessage = await model.invoke(
+    messagesForProvider,
+    invocationConfig
+  );
   if ((finalMessage.tool_calls?.length ?? 0) > 0) {
     finalMessage.tool_calls = finalMessage.tool_calls?.filter(
       (tool_call: ToolCall) => !!tool_call.name
@@ -997,25 +1000,6 @@ export function getFallbackOverflowCandidates(
   return [...(fallbackOverflowCandidates.get(error) ?? [])];
 }
 
-/**
- * Best-effort read of the configured model name from client options.
- * Providers disagree on the key (`model` vs `modelName`).
- */
-function extractClientOptionsModel(
-  clientOptions: t.ClientOptions | undefined
-): string | undefined {
-  const options = clientOptions as
-    | { model?: unknown; modelName?: unknown }
-    | undefined;
-  if (typeof options?.model === 'string' && options.model !== '') {
-    return options.model;
-  }
-  if (typeof options?.modelName === 'string' && options.modelName !== '') {
-    return options.modelName;
-  }
-  return undefined;
-}
-
 /**
  * Attempts each fallback provider in order until one succeeds.
  *
@@ -1106,7 +1090,7 @@ export async function tryFallbackProviders({
        * `ls_model_name`. The serving provider is stamped uniformly by
        * `attemptInvoke` (`INVOKED_PROVIDER`).
        */
-      const fbModelName = extractClientOptionsModel(fb.clientOptions);
+      const fbModelName = resolveClientOptionsModel(fb.clientOptions);
       const fbConfig: RunnableConfig | undefined =
         fbModelName == null
           ? config

package/src/llm/request.ts

@@ -43,6 +43,30 @@ export function isThinkingEnabled(
   return false;
 }
 
+/**
+ * Model configured on client options, under whichever of the two keys carries
+ * it. LangChain accepts `modelName` as an alias for `model` and this package
+ * writes both (see `buildSummarizationClientConfig`), while hosts configure
+ * agents through either. Reading only one key therefore does not fail loudly:
+ * it reports an unconfigured model, and every caller here treats that as a cue
+ * to fall back to a default, so a Claude agent configured through the alias is
+ * silently handled as something else.
+ */
+export function resolveClientOptionsModel(
+  clientOptions: t.ClientOptions | undefined
+): string | undefined {
+  const options = clientOptions as
+    | { model?: unknown; modelName?: unknown }
+    | undefined;
+  if (typeof options?.model === 'string' && options.model !== '') {
+    return options.model;
+  }
+  if (typeof options?.modelName === 'string' && options.modelName !== '') {
+    return options.modelName;
+  }
+  return undefined;
+}
+
 /**
  * Returns the correct key for setting max output tokens on the model
  * constructor options.  Google/Vertex use `maxOutputTokens`, all others