@librechat/agents 3.3.7 → 3.3.9

package/src/specs/langfuse-trace-shaping.test.ts

@@ -28,6 +28,13 @@ const TRACE_INPUT = LangfuseOtelSpanAttributes.TRACE_INPUT;
 const TRACE_OUTPUT = LangfuseOtelSpanAttributes.TRACE_OUTPUT;
 const OBSERVATION_TYPE = LangfuseOtelSpanAttributes.OBSERVATION_TYPE;
 const TRACE_TAGS = LangfuseOtelSpanAttributes.TRACE_TAGS;
+const METADATA_LANGGRAPH_NODE = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`;
+
+/** The outer workflow node: a non-root LangGraph node span whose
+ *  `langgraph_node` metadata equals its name. */
+function createWorkflowNodeSpan(name: string): TestSpan {
+  return createSpan(name, { [METADATA_LANGGRAPH_NODE]: name }, 'parent-1');
+}
 
 describe('shouldDropLangfuseSpan', () => {
   it('drops langgraph __start__ seed spans', () => {
@@ -127,6 +134,177 @@ describe('shapeLangfuseSpan', () => {
     expect(span.name).toBe('tool-dispatch');
   });
 
+  it('counts id-bearing invalid_tool_calls in the dispatch input (mixed and invalid-only)', () => {
+    /** ToolNode pairs attributable invalid calls with synthesized error
+     *  results (and routes invalid-only turns on them alone), so the span
+     *  input must include them — invalid-only used to find zero calls and
+     *  keep the full serialized graph state as the input. */
+    const mixed = [
+      {
+        type: 'ai',
+        id: 'ai_mixed_span',
+        tool_calls: [{ name: 'echo', args: { command: 'hi' }, id: 'tc_ok' }],
+        invalid_tool_calls: [
+          {
+            name: 'echo',
+            args: '"raw unparsed',
+            id: 'tc_bad',
+            error: 'Malformed args.',
+            type: 'invalid_tool_call',
+          },
+          { name: 'echo', args: 'no-id — excluded', error: 'Malformed args.' },
+          {
+            name: 'echo',
+            args: 'empty-id — excluded',
+            id: '',
+            error: 'Malformed args.',
+          },
+          {
+            name: 'web_search',
+            args: 'server-tool — excluded',
+            id: 'srvtoolu_xyz',
+            error: 'Malformed args.',
+          },
+          {
+            args: 'nameless — included with the unknown fallback',
+            id: 'tc_nameless',
+            error: 'Malformed args.',
+          },
+        ],
+      },
+    ];
+    const mixedSpan = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: JSON.stringify({ messages: mixed }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(mixedSpan);
+    expect(JSON.parse(mixedSpan.attributes[INPUT] as string)).toEqual([
+      { name: 'echo', args: { command: 'hi' } },
+      { name: 'echo', args: '"raw unparsed' },
+      { name: 'unknown', args: 'nameless — included with the unknown fallback' },
+    ]);
+
+    const invalidOnly = [
+      {
+        type: 'ai',
+        id: 'ai_invalid_only_span',
+        tool_calls: [],
+        invalid_tool_calls: [
+          {
+            name: 'echo',
+            args: 'garbage',
+            id: 'tc_solo',
+            error: 'Malformed args.',
+            type: 'invalid_tool_call',
+          },
+        ],
+      },
+    ];
+    const invalidOnlySpan = createSpan(
+      'tools=agent_abc',
+      { [INPUT]: JSON.stringify({ messages: invalidOnly }) },
+      'parent-1'
+    );
+    shapeLangfuseSpan(invalidOnlySpan);
+    expect(JSON.parse(invalidOnlySpan.attributes[INPUT] as string)).toEqual([
+      { name: 'echo', args: 'garbage' },
+    ]);
+  });
+
+  it('excludes invalid calls when ToolNode would skip them (array state / id-less message)', () => {
+    /** Mirrors ToolNode's canPromoteInvalidCalls gate: a bare-array state
+     *  returns a plain output list (invalid handling skipped) and an id-less
+     *  message cannot take the reducer upsert — the span must not report
+     *  those calls as pending work. Valid calls still count. */
+    const invalidCall = {
+      name: 'echo',
+      args: 'garbage',
+      id: 'tc_gated',
+      error: 'Malformed args.',
+      type: 'invalid_tool_call',
+    };
+    const arrayStateSpan = createSpan(
+      'tools=agent_abc',
+      {
+        [INPUT]: JSON.stringify([
+          {
+            type: 'ai',
+            id: 'ai_array_span',
+            tool_calls: [{ name: 'echo', args: { command: 'hi' }, id: 'tc_ok' }],
+            invalid_tool_calls: [invalidCall],
+          },
+        ]),
+      },
+      'parent-1'
+    );
+    shapeLangfuseSpan(arrayStateSpan);
+    expect(JSON.parse(arrayStateSpan.attributes[INPUT] as string)).toEqual([
+      { name: 'echo', args: { command: 'hi' } },
+    ]);
+
+    const idlessSpan = createSpan(
+      'tools=agent_abc',
+      {
+        [INPUT]: JSON.stringify({
+          messages: [
+            {
+              type: 'ai',
+              tool_calls: [{ name: 'echo', args: { command: 'hi' }, id: 'tc_ok' }],
+              invalid_tool_calls: [invalidCall],
+            },
+          ],
+        }),
+      },
+      'parent-1'
+    );
+    shapeLangfuseSpan(idlessSpan);
+    expect(JSON.parse(idlessSpan.attributes[INPUT] as string)).toEqual([
+      { name: 'echo', args: { command: 'hi' } },
+    ]);
+  });
+
+  it('excludes invalid calls already answered by a ToolMessage in the state', () => {
+    /** Mirrors ToolNode's !toolMessageIds.has(id) execution filter: an
+     *  answered invalid call is not pending work, even when the same turn
+     *  still has a pending valid call. */
+    const span = createSpan(
+      'tools=agent_abc',
+      {
+        [INPUT]: JSON.stringify({
+          messages: [
+            {
+              type: 'ai',
+              id: 'ai_answered_invalid',
+              tool_calls: [
+                { name: 'echo', args: { command: 'hi' }, id: 'tc_pending' },
+              ],
+              invalid_tool_calls: [
+                {
+                  name: 'echo',
+                  args: 'garbage',
+                  id: 'tc_answered_invalid',
+                  error: 'Malformed args.',
+                  type: 'invalid_tool_call',
+                },
+              ],
+            },
+            {
+              type: 'tool',
+              tool_call_id: 'tc_answered_invalid',
+              content: 'Error: Malformed args.',
+            },
+          ],
+        }),
+      },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
+      { name: 'echo', args: { command: 'hi' } },
+    ]);
+  });
+
   it('keeps a stable tool-dispatch shape when no tool calls are found', () => {
     const original = JSON.stringify({
       messages: [{ type: 'human', content: 'hi' }],
@@ -142,6 +320,75 @@ describe('shapeLangfuseSpan', () => {
     expect(span.attributes[INPUT]).toBe(original);
   });
 
+  it('reduces ephemeral workflow-agent node ids to agent observations named by sender', () => {
+    const span = createWorkflowNodeSpan(
+      'bedrock__claude-sonnet-5___ClickHouse Agent'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('ClickHouse Agent');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('agent');
+  });
+
+  it('strips parallel-instance index suffixes from ephemeral agent ids', () => {
+    const span = createWorkflowNodeSpan('openAI__gpt-4o___GPT-4o____1');
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('GPT-4o');
+  });
+
+  it('restores encoded colons in ephemeral agent sender names', () => {
+    const span = createWorkflowNodeSpan('openAI__gpt-4o___alias__variant');
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('alias:variant');
+  });
+
+  it('keeps persisted agent ids and senderless ephemeral ids unchanged', () => {
+    const persisted = createWorkflowNodeSpan('agent_okvkCroi6wXM4-7BY4ud1');
+    shapeLangfuseSpan(persisted);
+    expect(persisted.name).toBe('agent_okvkCroi6wXM4-7BY4ud1');
+
+    const senderless = createWorkflowNodeSpan('openAI__gpt-4o');
+    shapeLangfuseSpan(senderless);
+    expect(senderless.name).toBe('openAI__gpt-4o');
+  });
+
+  it('does not rename tool observations whose names embed triple underscores', () => {
+    const span = createSpan(
+      'server__toolkit___lookup',
+      { [OBSERVATION_TYPE]: 'tool' },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('server__toolkit___lookup');
+  });
+
+  it('only renames spans carrying matching langgraph node metadata', () => {
+    const runName = createSpan('LibreChat Agent: Ops___EU', {}, 'parent-1');
+    shapeLangfuseSpan(runName);
+    expect(runName.name).toBe('LibreChat Agent: Ops___EU');
+
+    const ordinaryChain = createSpan('pipeline__stage___EU', {}, 'parent-1');
+    shapeLangfuseSpan(ordinaryChain);
+    expect(ordinaryChain.name).toBe('pipeline__stage___EU');
+    expect(ordinaryChain.attributes[OBSERVATION_TYPE]).toBeUndefined();
+
+    const mismatchedNode = createSpan(
+      'pipeline__stage___EU',
+      { [METADATA_LANGGRAPH_NODE]: 'some-other-node' },
+      'parent-1'
+    );
+    shapeLangfuseSpan(mismatchedNode);
+    expect(mismatchedNode.name).toBe('pipeline__stage___EU');
+  });
+
+  it('never renames root observations, even with an encoded-id shape', () => {
+    const span = createSpan('bedrock__claude-sonnet-5___ClickHouse Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
+      [METADATA_LANGGRAPH_NODE]: 'bedrock__claude-sonnet-5___ClickHouse Agent',
+    });
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('bedrock__claude-sonnet-5___ClickHouse Agent');
+  });
+
   it('sets root span and trace input/output to the question and answer', () => {
     const span = createSpan('LibreChat Agent', {
       [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
@@ -262,4 +509,51 @@ describe('shapeLangfuseSpan', () => {
     expect(span.attributes[TRACE_INPUT]).toBe('Generate a title');
     expect(span.attributes[TRACE_OUTPUT]).toBe('A useful title');
   });
+
+  it('keeps a generation root\'s full observation input while reducing trace input', () => {
+    /** The activity-label path: a bare model.invoke traces the generation
+     *  as its own root, so the observation input is the ONLY record of
+     *  the system prompt. The exact shape @langfuse/langchain exports. */
+    const originalInput = JSON.stringify([
+      { role: 'system', content: 'Write a short label describing…' },
+      { role: 'user', content: 'Tool calls:\n- bash(ls) → ok\n\nLabel:' },
+    ]);
+    const originalOutput = JSON.stringify({
+      role: 'assistant',
+      content: 'Confirmed /mnt/data persists',
+    });
+    const span = createSpan('LibreChat Activity Label', {
+      [OBSERVATION_TYPE]: 'generation',
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'activity-label']),
+      [INPUT]: originalInput,
+      [OUTPUT]: originalOutput,
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.name).toBe('llm');
+    expect(span.attributes[INPUT]).toBe(originalInput);
+    expect(span.attributes[OUTPUT]).toBe(originalOutput);
+    expect(span.attributes[TRACE_INPUT]).toBe(
+      'Tool calls:\n- bash(ls) → ok\n\nLabel:'
+    );
+    expect(span.attributes[TRACE_OUTPUT]).toBe(originalOutput);
+  });
+
+  it('still reduces observation input on non-generation roots', () => {
+    const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
+      [INPUT]: JSON.stringify({
+        messages: [
+          { type: 'system', content: 'You are helpful.' },
+          { type: 'human', content: 'What is ClickHouse?' },
+        ],
+      }),
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.attributes[INPUT]).toBe('What is ClickHouse?');
+    expect(span.attributes[TRACE_INPUT]).toBe('What is ClickHouse?');
+  });
 });

package/src/specs/prune.test.ts

@@ -1444,7 +1444,44 @@ describe('Prune Messages Tests', () => {
       expect(calculateMaxToolCallInputChars(0)).toBe(200_000);
       expect(calculateMaxToolCallInputChars(1_000)).toBe(600);
       expect(calculateMaxToolCallInputChars(1_000_000)).toBe(200_000);
-      expect(serializeToolCallInput(undefined, 4)).toBe('null');
+      // Even below the envelope floor, serialized args stay a JSON object —
+      // 'null' here poisoned replayed tool calls (Anthropic 400s a non-object
+      // tool_use.input).
+      expect(serializeToolCallInput(undefined, 4)).toBe('{}');
+    });
+
+    it('never nulls an input when the cap is below the truncation envelope', () => {
+      // Regression: a tight summarization budget can shrink the per-input cap
+      // below the `{_truncated, _originalChars}` envelope size (~38 chars).
+      // The projection used to return `null` for BOTH the inline block input
+      // and the tool_calls args; the nulls were written back into graph state
+      // by preFlightTruncateToolCallInputs and later replayed to Anthropic as
+      // `tool_use.input: null` → 400 "Input should be an object".
+      const chunk = new AIMessageChunk({
+        content: [
+          {
+            type: 'tool_use',
+            id: 'tiny-cap-call',
+            name: 'calculator',
+            // Streaming leaves the raw JSON string on the block.
+            input: '{"input": "670592745 / 99991"}',
+          },
+        ],
+        tool_calls: [
+          {
+            id: 'tiny-cap-call',
+            name: 'calculator',
+            args: { input: '670592745 / 99991' },
+          },
+        ],
+      });
+
+      const [projected] = projectToolCallInputs([chunk], 20);
+      const block = (
+        (projected as AIMessageChunk).content as Array<Record<string, unknown>>
+      )[0];
+      expect(block.input).toEqual({});
+      expect((projected as AIMessageChunk).tool_calls?.[0].args).toEqual({});
     });
 
     it('returns the original array when every input is already safe and bounded', () => {

package/src/stream.ts

@@ -162,6 +162,13 @@ function isEagerExecutionExcludedTool(
   if (excluded != null && excluded.includes(name)) {
     return true;
   }
+  // Run-scoped circuit breaker: once a prestart for this tool diverged from
+  // the final request ("changed after eager execution started"), stop
+  // prestarting it so the model's retry executes normally instead of
+  // re-diverging in a loop (LibreChat#14371).
+  if (graph.eagerEventToolSuppressions?.has(name) === true) {
+    return true;
+  }
   // A code-session participant writes to the shared sandbox, so it is
   // side-effecting: never prestart it speculatively (a revised/superseded turn
   // would leave the write applied). Implies exclusion without the host having
@@ -1006,8 +1013,9 @@ function recordEagerToolCallChunks(args: {
   graph: StandardGraph;
   stepKey: string;
   toolCallChunks?: ToolCallChunk[];
+  seal?: StreamedToolCallSeal;
 }): void {
-  const { graph, stepKey, toolCallChunks } = args;
+  const { graph, stepKey, toolCallChunks, seal } = args;
   if (toolCallChunks == null || toolCallChunks.length === 0) {
     return;
   }
@@ -1054,13 +1062,33 @@ function recordEagerToolCallChunks(args: {
     const argsText = isRepeatedObservedFragment
       ? existing.argsText
       : mergeToolCallArgsText(existing.argsText, incomingArgs);
+    const index = getEagerToolChunkIndex(toolCallChunk) ?? existing.index;
+    // Only a chunk whose explicit adapter seal covers THIS call may supply a
+    // full-args restatement (OpenAI Responses `arguments.done`). Pure-signal
+    // seals carry empty args and never set this.
+    const sealCoversChunk =
+      seal != null &&
+      (seal.kind === 'all' ||
+        (seal.kind === 'single' &&
+          ((seal.id != null && seal.id === id) ||
+            (seal.index != null && seal.index === index))));
     const next = {
       id,
       name,
       argsText,
-      index: getEagerToolChunkIndex(toolCallChunk) ?? existing.index,
+      // Canonical accumulation length: LangChain concats fragments verbatim
+      // to build the final request, and every reconciliation branch above
+      // yields text no longer than that concat — equal exactly when every
+      // merge was a pure append. Tracking the length (not the text) keeps
+      // cumulative/restating streams from retaining every prefix.
+      rawArgsLength: (existing.rawArgsLength ?? 0) + incomingArgs.length,
+      index,
       lastArgsFragment:
         incomingArgs !== '' ? incomingArgs : existing.lastArgsFragment,
+      sealedArgsFragment:
+        sealCoversChunk && incomingArgs !== ''
+          ? incomingArgs
+          : existing.sealedArgsFragment,
     };
     graph.eagerEventToolCallChunks.set(key, next);
   }
@@ -1095,6 +1123,7 @@ function getStreamedReadyToolCalls(args: {
   const readyEntries: Array<{
     key: string;
     state: t.EagerEventToolCallChunkState;
+    sealedByAdapter: boolean;
   }> = [];
 
   for (const [key, state] of graph.eagerEventToolCallChunks) {
@@ -1124,7 +1153,11 @@ function getStreamedReadyToolCalls(args: {
       isSealedByLaterChunk ||
       isSealedExplicitly
     ) {
-      readyEntries.push({ key, state });
+      readyEntries.push({
+        key,
+        state,
+        sealedByAdapter: isSealedExplicitly || seal?.kind === 'all',
+      });
     }
   }
 
@@ -1143,11 +1176,37 @@ function getStreamedReadyToolCalls(args: {
 
   return readyEntries
     .sort((left, right) => (left.state.index ?? 0) - (right.state.index ?? 0))
-    .flatMap(({ state }) => {
+    .flatMap(({ state, sealedByAdapter }) => {
       const args = coerceRecordArgs(state.argsText);
       if (args == null) {
         return [];
       }
+      // The final request's args come from LangChain's canonical verbatim
+      // concatenation of fragments, while `argsText` reconciles provider
+      // quirks with lossy heuristics that can also swallow legitimately
+      // repetitive payload fragments (LibreChat#14371). `argsText` can never
+      // be LONGER than the plain concat, so length equality proves it IS the
+      // canonical accumulation.
+      const isCanonicalAccumulation =
+        state.rawArgsLength != null &&
+        state.argsText.length === state.rawArgsLength;
+      // Adapter seals may instead restate the finished call's full args on
+      // the seal chunk itself (OpenAI Responses
+      // `function_call_arguments.done`). Only when the seal-carrying chunk
+      // supplied that fragment AND the accumulated text IS that restatement
+      // has the adapter vouched for it — plain concatenation intentionally
+      // differs there. Pure-signal seals (Bedrock contentBlockStop,
+      // `args: ''`) never qualify.
+      const isAuthoritativeRestatement =
+        sealedByAdapter &&
+        state.sealedArgsFragment != null &&
+        state.sealedArgsFragment === state.argsText;
+      // Prestarting an unconfirmed snapshot trips the "changed after eager
+      // execution started" guard and burns a retry loop — leave unconfirmed
+      // calls to normal ToolNode execution with final args.
+      if (!isCanonicalAccumulation && !isAuthoritativeRestatement) {
+        return [];
+      }
       return [
         {
           id: state.id,
@@ -1586,6 +1645,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
           graph,
           stepKey,
           toolCallChunks: chunk.tool_call_chunks,
+          seal: streamedToolCallSeal,
         });
       }
       await handleToolCallChunks({
@@ -2325,7 +2385,9 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         return;
       }
 
-      for (const contentPart of getDeltaContentParts(messageDelta.delta.content)) {
+      for (const contentPart of getDeltaContentParts(
+        messageDelta.delta.content
+      )) {
         updateContent(runStep.index, contentPart);
       }
     } else if (
@@ -2354,7 +2416,9 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         return;
       }
 
-      for (const contentPart of getDeltaContentParts(reasoningDelta.delta.content)) {
+      for (const contentPart of getDeltaContentParts(
+        reasoningDelta.delta.content
+      )) {
         updateContent(runStep.index, contentPart);
       }
     } else if (event === GraphEvents.ON_RUN_STEP_DELTA) {