@librechat/agents 3.3.8 → 3.3.10

package/src/specs/langfuse-routing.integration.test.ts

@@ -256,7 +256,9 @@ function expectChildSpanParentName({
   const children = starts.filter((record) => record.name === childName);
   expect(children).not.toHaveLength(0);
   for (const child of children) {
-    const parent = starts.find((record) => record.spanId === child.parentSpanId);
+    const parent = starts.find(
+      (record) => record.spanId === child.parentSpanId
+    );
     expect(parent?.name.startsWith(parentNamePrefix)).toBe(true);
   }
 }
@@ -560,6 +562,141 @@ describe('Langfuse per-run routing integration', () => {
     }
   });
 
+  it('detaches root observations from foreign ambient spans', async () => {
+    const tenantId = 'tenant-ambient';
+    const foreignTraceId = 'f0e1d2c3b4a5968778695a4b3c2d1e0f';
+    const foreignSpanId = 'a1b2c3d4e5f60718';
+    initializeLangfuseTracing(tenantLangfuse(tenantId));
+
+    // Simulates a host running agent code inside its own OpenTelemetry span
+    // (HTTP server auto-instrumentation on the global provider): the span is
+    // never exported to Langfuse, so inheriting it would orphan the trace
+    // root, merge concurrent runs in one request into a single trace, and
+    // bypass deterministic trace ids.
+    const foreignSpan = otelTrace.wrapSpanContext({
+      traceId: foreignTraceId,
+      spanId: foreignSpanId,
+      traceFlags: 1,
+    });
+    await otelContext.with(
+      otelTrace.setSpan(otelContext.active(), foreignSpan),
+      () => runTenantFlow(tenantId)
+    );
+
+    const starts = startsForTenant(tenantId);
+    expect(starts).not.toHaveLength(0);
+    expect(
+      starts.filter(
+        (record) =>
+          record.traceId === foreignTraceId ||
+          record.parentSpanId === foreignSpanId
+      )
+    ).toHaveLength(0);
+
+    const agentRoot = starts.find(
+      (record) => record.name === `LibreChat Agent: Parent ${tenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(traceIdFromSeed(`routing-${tenantId}`));
+    expect(agentRoot?.parentSpanId).toBeUndefined();
+
+    const titleRoot = starts.find(
+      (record) => record.name === `LibreChat Title: Parent ${tenantId}`
+    );
+    expect(titleRoot?.traceId).toBe(
+      traceIdFromSeed(`title-routing-${tenantId}`)
+    );
+    expect(titleRoot?.parentSpanId).toBeUndefined();
+  });
+
+  it('keeps root observations nested under Langfuse-managed ambient spans', async () => {
+    const tenantId = 'tenant-managed';
+    const langfuse = tenantLangfuse(tenantId);
+    initializeLangfuseTracing(langfuse);
+
+    let hostSpan: MockSpan | undefined;
+    await withLangfuseRuntimeScope({ langfuse }, async () => {
+      hostSpan = createMockSpan('host-group');
+      await otelContext.with(
+        otelTrace.setSpan(otelContext.active(), hostSpan as never),
+        () => runTenantFlow(tenantId)
+      );
+    });
+
+    const hostSpanContext = hostSpan?.spanContext() as {
+      traceId: string;
+      spanId: string;
+    };
+    const agentRoot = startsForTenant(tenantId).find(
+      (record) => record.name === `LibreChat Agent: Parent ${tenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(hostSpanContext.traceId);
+    expect(agentRoot?.parentSpanId).toBe(hostSpanContext.spanId);
+  });
+
+  it('detaches root observations from managed ambient spans of another destination', async () => {
+    const hostTenantId = 'tenant-managed-a';
+    const runTenantId = 'tenant-managed-b';
+    const hostLangfuse = tenantLangfuse(hostTenantId);
+    initializeLangfuseTracing(hostLangfuse);
+    initializeLangfuseTracing(tenantLangfuse(runTenantId));
+
+    let hostSpan: MockSpan | undefined;
+    await withLangfuseRuntimeScope({ langfuse: hostLangfuse }, async () => {
+      hostSpan = createMockSpan('host-group');
+    });
+
+    // A managed span is only a safe parent for runs exporting to the SAME
+    // destination; nesting tenant-B under tenant-A's span would leave B's
+    // trace dangling in B's project with A's trace id.
+    await otelContext.with(
+      otelTrace.setSpan(otelContext.active(), hostSpan as never),
+      () => runTenantFlow(runTenantId)
+    );
+
+    const hostSpanContext = hostSpan?.spanContext() as {
+      traceId: string;
+      spanId: string;
+    };
+    const agentRoot = startsForTenant(runTenantId).find(
+      (record) => record.name === `LibreChat Agent: Parent ${runTenantId}`
+    );
+    expect(agentRoot?.traceId).toBe(traceIdFromSeed(`routing-${runTenantId}`));
+    expect(agentRoot?.traceId).not.toBe(hostSpanContext.traceId);
+    expect(agentRoot?.parentSpanId).toBeUndefined();
+  });
+
+  it('generates a scope stamp for directly-constructed graphs without a run id', async () => {
+    const { StandardGraph } = await import('@/graphs/Graph');
+    const buildGraph = (): { langfuseScopeRunId: string } =>
+      new StandardGraph({
+        agents: [createAgent('stampless')],
+        langfuse: tenantLangfuse('stampless'),
+      }) as unknown as { langfuseScopeRunId: string };
+
+    const graphA = buildGraph();
+    const graphB = buildGraph();
+    expect(graphA.langfuseScopeRunId).toEqual(expect.stringMatching(/^graph:/));
+    expect(graphB.langfuseScopeRunId).toEqual(expect.stringMatching(/^graph:/));
+    expect(graphA.langfuseScopeRunId).not.toBe(graphB.langfuseScopeRunId);
+  });
+
+  it('stamps concurrent executions of the same public run id distinctly', async () => {
+    const { StandardGraph } = await import('@/graphs/Graph');
+    const buildGraph = (): { langfuseScopeRunId: string } =>
+      new StandardGraph({
+        runId: 'duplicate-run',
+        agents: [createAgent('duplicate')],
+        langfuse: tenantLangfuse('duplicate'),
+      }) as unknown as { langfuseScopeRunId: string };
+
+    const first = buildGraph();
+    const second = buildGraph();
+    expect(first.langfuseScopeRunId).toEqual(
+      expect.stringMatching(/^duplicate-run:/)
+    );
+    expect(first.langfuseScopeRunId).not.toBe(second.langfuseScopeRunId);
+  });
+
   it('routes spans from captured OTel context after ALS scope exits', () => {
     const langfuse = tenantLangfuse('tenant-otel');
     initializeLangfuseTracing(langfuse);

package/src/specs/langfuse-span-registry.test.ts

@@ -0,0 +1,70 @@
+import type { Span } from '@opentelemetry/api';
+import type * as t from '@/types';
+import {
+  getLangfuseManagedSpanDestination,
+  registerLangfuseManagedSpan,
+  resolveLangfuseDestinationKey,
+} from '@/langfuseSpanRegistry';
+
+const ORIGINAL_ENV = { ...process.env };
+
+function tenantConfig(
+  overrides: Partial<t.LangfuseConfig> = {}
+): t.LangfuseConfig {
+  return {
+    enabled: true,
+    publicKey: 'pk-registry',
+    secretKey: 'sk-registry',
+    baseUrl: 'https://langfuse.registry',
+    ...overrides,
+  };
+}
+
+describe('Langfuse span registry', () => {
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it('tracks managed spans by destination', () => {
+    const span = { name: 'managed' } as unknown as Span;
+    const key = resolveLangfuseDestinationKey(tenantConfig());
+    expect(key).toBeDefined();
+    registerLangfuseManagedSpan(span, key as string);
+    expect(getLangfuseManagedSpanDestination(span)).toBe(key);
+
+    const untracked = { name: 'foreign' } as unknown as Span;
+    expect(getLangfuseManagedSpanDestination(untracked)).toBeUndefined();
+  });
+
+  it('treats processor policy as irrelevant to destination identity', () => {
+    const base = resolveLangfuseDestinationKey(tenantConfig());
+    const redacting = resolveLangfuseDestinationKey(
+      tenantConfig({ toolOutputTracing: { enabled: false } })
+    );
+    expect(redacting).toBe(base);
+  });
+
+  it('separates destinations by credentials, endpoint, and environment', () => {
+    const base = resolveLangfuseDestinationKey(tenantConfig());
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ publicKey: 'pk-other' }))
+    ).not.toBe(base);
+    expect(
+      resolveLangfuseDestinationKey(
+        tenantConfig({ baseUrl: 'https://langfuse.other' })
+      )
+    ).not.toBe(base);
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ environment: 'staging' }))
+    ).not.toBe(base);
+  });
+
+  it('resolves no destination without credentials', () => {
+    delete process.env.LANGFUSE_PUBLIC_KEY;
+    delete process.env.LANGFUSE_SECRET_KEY;
+    expect(resolveLangfuseDestinationKey(undefined)).toBeUndefined();
+    expect(
+      resolveLangfuseDestinationKey(tenantConfig({ enabled: false }))
+    ).toBeUndefined();
+  });
+});

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', () => {