@librechat/agents 3.2.65 → 3.2.66

package/src/llm/anthropic/utils/cross-provider-server-tools.test.ts

@@ -0,0 +1,110 @@
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { _convertMessagesToAnthropicPayload } from './message_inputs';
+
+/**
+ * Regression for cross-provider agent handoffs (Google → Anthropic): a Gemini
+ * turn that used a server-side tool (URL context, Google Search) leaves
+ * `toolCall`/`toolResponse` content blocks in history. The Anthropic converter
+ * has no branch for them and previously threw
+ * "Unsupported message content format", crashing the handoff. Only Google can
+ * execute these blocks or validate their thought signatures, so they are
+ * dropped on assistant turns; any other unknown block still throws.
+ */
+type AnthropicPayload = ReturnType<typeof _convertMessagesToAnthropicPayload>;
+
+/** Minimal view of a converted Anthropic content block the assertions read. */
+interface TestBlock {
+  type?: string;
+  text?: string;
+}
+
+const assistantBlocks = (payload: AnthropicPayload): TestBlock[] => {
+  const content = payload.messages.find((m) => m.role === 'assistant')?.content;
+  return Array.isArray(content) ? (content as TestBlock[]) : [];
+};
+
+describe('_convertMessagesToAnthropicPayload — Google server-side tool blocks', () => {
+  it('drops toolCall/toolResponse on an assistant turn, keeping text', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('summarize this article'),
+      new AIMessage({
+        content: [
+          {
+            type: 'toolCall',
+            thoughtSignature: 'google-signature-not-valid-for-anthropic',
+            toolCall: {
+              toolType: 'URL_CONTEXT',
+              args: { urls: ['https://example.com/report'] },
+              id: 'j7pfyr6k',
+            },
+          },
+          {
+            type: 'toolResponse',
+            toolResponse: {
+              toolType: 'URL_CONTEXT',
+              id: 'j7pfyr6k',
+              result: { status: 'SUCCESS' },
+            },
+          },
+          {
+            type: 'text',
+            text: 'The article argues for dollar-cost averaging.',
+          },
+        ],
+      }),
+    ];
+
+    expect(() => _convertMessagesToAnthropicPayload(messages)).not.toThrow();
+    const blocks = assistantBlocks(
+      _convertMessagesToAnthropicPayload(messages)
+    );
+
+    const serialized = JSON.stringify(blocks);
+    expect(serialized).not.toContain('URL_CONTEXT');
+    expect(serialized).not.toContain(
+      'google-signature-not-valid-for-anthropic'
+    );
+    expect(
+      blocks.some(
+        (b) =>
+          b.type === 'text' &&
+          b.text === 'The article argues for dollar-cost averaging.'
+      )
+    ).toBe(true);
+  });
+
+  it('emits a placeholder (not empty content) when a server-tool-only turn is fully dropped', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'toolCall',
+            toolCall: { toolType: 'URL_CONTEXT', args: { urls: [] }, id: 'x1' },
+          },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(messages)).not.toThrow();
+    const blocks = assistantBlocks(
+      _convertMessagesToAnthropicPayload(messages)
+    );
+    expect(blocks.length).toBeGreaterThan(0);
+  });
+
+  it('still throws on a genuinely unknown assistant block', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('run code'),
+      new AIMessage({
+        content: [
+          { type: 'some_future_block_type', foo: 'bar' },
+          { type: 'text', text: 'done' },
+        ],
+      }),
+    ];
+    expect(() => _convertMessagesToAnthropicPayload(messages)).toThrow(
+      'Unsupported message content format'
+    );
+  });
+});

package/src/llm/anthropic/utils/message_inputs.ts

@@ -473,6 +473,13 @@ function _formatContent(message: BaseMessage) {
    * forwarding an unusable block. The receiving model produces its own thinking.
    */
   const foreignReasoningTypes = ['reasoning_content', 'reasoning', 'think'];
+  /**
+   * Google server-side tool blocks (`toolCall`/`toolResponse` parts from e.g.
+   * URL context or Google Search). Only Google can execute these and validate
+   * their thought signatures, so they are dropped on a cross-provider handoff
+   * (e.g. Google → Anthropic); the assistant's answer text is kept.
+   */
+  const foreignServerToolTypes = ['toolCall', 'toolResponse'];
   const { content } = message;
 
   if (typeof content === 'string') {
@@ -855,6 +862,14 @@ function _formatContent(message: BaseMessage) {
         // dropped — as does any other unknown block (user media, Google
         // code-execution), which must be surfaced, not discarded.
         return null;
+      } else if (
+        isAIMessage(message) &&
+        foreignServerToolTypes.some((t) => t === contentPart.type)
+      ) {
+        // Google server-side tool call/response (e.g. URL context) — only
+        // Google can execute it or validate its thought signature; drop it
+        // on a cross-provider handoff rather than crash.
+        return null;
       } else {
         console.error(
           'Unsupported content part:',

package/src/llm/bedrock/utils/cross-provider-server-tools.test.ts

@@ -0,0 +1,122 @@
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { convertToConverseMessages } from './message_inputs';
+
+/**
+ * Regression for cross-provider agent handoffs (Google → Bedrock): a Gemini
+ * turn that used a server-side tool (URL context, Google Search) leaves
+ * `toolCall`/`toolResponse` content blocks in history. The Bedrock Converse
+ * converter has no branch for them and previously threw
+ * "Unsupported content block type: toolCall", crashing the handoff. Only
+ * Google can execute these blocks or validate their thought signatures, so
+ * they are dropped on assistant turns; any other unknown block still throws.
+ */
+type ConverseResult = ReturnType<typeof convertToConverseMessages>;
+
+/** Minimal view of a converted Bedrock Converse content block the assertions read. */
+interface ConverseBlock {
+  text?: string;
+  toolUse?: {
+    toolUseId?: string;
+    name?: string;
+    input?: Record<string, string>;
+  };
+}
+
+const assistantContent = (result: ConverseResult): ConverseBlock[] => {
+  const msg = result.converseMessages.find((m) => m.role === 'assistant');
+  return (msg?.content ?? []) as ConverseBlock[];
+};
+
+describe('convertToConverseMessages — Google server-side tool blocks (Google → Bedrock)', () => {
+  it('drops toolCall/toolResponse on an assistant turn, keeping text and tool calls', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('summarize this article'),
+      new AIMessage({
+        content: [
+          {
+            type: 'toolCall',
+            thoughtSignature: 'google-signature-not-valid-for-bedrock',
+            toolCall: {
+              toolType: 'URL_CONTEXT',
+              args: { urls: ['https://example.com/report'] },
+              id: 'j7pfyr6k',
+            },
+          },
+          {
+            type: 'toolResponse',
+            toolResponse: {
+              toolType: 'URL_CONTEXT',
+              id: 'j7pfyr6k',
+              result: { status: 'SUCCESS' },
+            },
+          },
+          {
+            type: 'text',
+            text: 'The article argues for dollar-cost averaging.',
+          },
+        ],
+        tool_calls: [
+          {
+            id: 'call_client_tool',
+            name: 'save_note',
+            args: { note: 'DCA summary' },
+            type: 'tool_call',
+          },
+        ],
+      }),
+    ];
+
+    expect(() => convertToConverseMessages(messages)).not.toThrow();
+    const content = assistantContent(convertToConverseMessages(messages));
+
+    const serialized = JSON.stringify(content);
+    expect(serialized).not.toContain('URL_CONTEXT');
+    expect(serialized).not.toContain('google-signature-not-valid-for-bedrock');
+
+    expect(
+      content.some(
+        (b) => b.text === 'The article argues for dollar-cost averaging.'
+      )
+    ).toBe(true);
+    const toolUse = content.find((b) => b.toolUse != null);
+    expect(toolUse?.toolUse).toMatchObject({
+      toolUseId: 'call_client_tool',
+      name: 'save_note',
+      input: { note: 'DCA summary' },
+    });
+  });
+
+  it('emits a placeholder (not empty content) when a server-tool-only turn is fully dropped', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('hi'),
+      new AIMessage({
+        content: [
+          {
+            type: 'toolCall',
+            toolCall: { toolType: 'URL_CONTEXT', args: { urls: [] }, id: 'x1' },
+          },
+        ],
+      }),
+    ];
+    expect(() => convertToConverseMessages(messages)).not.toThrow();
+    const content = assistantContent(convertToConverseMessages(messages));
+    expect(content.length).toBeGreaterThan(0);
+    expect(content.every((b) => typeof b.text === 'string')).toBe(true);
+  });
+
+  it('still throws on a genuinely unknown assistant block', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('run code'),
+      new AIMessage({
+        content: [
+          { type: 'some_future_block_type', foo: 'bar' },
+          { type: 'text', text: 'done' },
+        ],
+      }),
+    ];
+    expect(() => convertToConverseMessages(messages)).toThrow(
+      'Unsupported content block type'
+    );
+  });
+});

package/src/llm/bedrock/utils/message_inputs.ts

@@ -41,6 +41,14 @@ const FOREIGN_REASONING_TYPES = [
   'think',
 ];
 
+/**
+ * Google server-side tool blocks (`toolCall`/`toolResponse` parts from e.g.
+ * URL context or Google Search). Only Google can execute these and validate
+ * their thought signatures, so they are dropped on a cross-provider handoff
+ * (e.g. Google → Bedrock); the assistant's answer text is kept.
+ */
+const FOREIGN_SERVER_TOOL_TYPES = ['toolCall', 'toolResponse'];
+
 /**
  * Bedrock Converse rejects assistant messages with no content blocks. When
  * filtering (e.g. dropping foreign reasoning) empties an assistant turn that
@@ -727,6 +735,11 @@ function convertAIMessageToConverseMessage(msg: BaseMessage): BedrockMessage {
           // than crash. The Bedrock model produces its own reasoning. Anything
           // else unknown still throws below — real content must be surfaced.
           return;
+        } else if (FOREIGN_SERVER_TOOL_TYPES.some((t) => t === block.type)) {
+          // Google server-side tool call/response (e.g. URL context) — only
+          // Google can execute it or validate its thought signature; drop it
+          // on a cross-provider handoff rather than crash.
+          return;
         } else {
           const blockValues = Object.fromEntries(
             Object.entries(block).filter(([key]) => key !== 'type')

package/src/specs/langfuse-instrumentation.test.ts

@@ -184,6 +184,70 @@ describe('Langfuse instrumentation', () => {
     expect(mockBasicTracerProvider).toHaveBeenCalledTimes(1);
   });
 
+  it('resolves environment from LANGFUSE_TRACING_ENVIRONMENT', async () => {
+    process.env.LANGFUSE_TRACING_ENVIRONMENT = 'staging';
+
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+    });
+
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({ environment: 'staging' })
+    );
+  });
+
+  it('falls back to NODE_ENV when LANGFUSE_TRACING_ENVIRONMENT is unset', async () => {
+    delete process.env.LANGFUSE_TRACING_ENVIRONMENT;
+    process.env.NODE_ENV = 'production';
+
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+    });
+
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({ environment: 'production' })
+    );
+  });
+
+  it('falls through blank environment overrides and trims the selected value', async () => {
+    process.env.LANGFUSE_TRACING_ENVIRONMENT = '   ';
+    process.env.NODE_ENV = ' production ';
+
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+      environment: '',
+    });
+
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({ environment: 'production' })
+    );
+  });
+
+  it('prefers an explicit config environment over environment variables', async () => {
+    process.env.LANGFUSE_TRACING_ENVIRONMENT = 'staging';
+
+    const { initializeLangfuseTracing } = await import('@/instrumentation');
+    initializeLangfuseTracing({
+      publicKey: 'pk-config',
+      secretKey: 'sk-config',
+      baseUrl: 'https://langfuse.config',
+      environment: 'canary',
+    });
+
+    expect(mockLangfuseSpanProcessor).toHaveBeenCalledWith(
+      expect.objectContaining({ environment: 'canary' })
+    );
+  });
+
   it('does not replace the global provider when explicit credentials change', async () => {
     const { initializeLangfuseTracing } = await import('@/instrumentation');
     initializeLangfuseTracing({

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

@@ -25,6 +25,8 @@ type SpanStartRecord = {
   name: string;
   params: ProcessorParams;
   traceId: string;
+  spanId: string;
+  parentSpanId?: string;
 };
 
 const spanStarts: SpanStartRecord[] = [];
@@ -140,11 +142,15 @@ jest.mock('@langfuse/otel', () => ({
   LangfuseSpanProcessor: jest.fn().mockImplementation((params) => ({
     forceFlush: jest.fn(),
     onEnd: jest.fn(),
-    onStart: jest.fn((span) => {
+    onStart: jest.fn((span, parentContext) => {
+      const spanContext = span.spanContext();
+      const parentSpanId = otelTrace.getSpanContext(parentContext)?.spanId;
       spanStarts.push({
         name: span.name,
         params,
-        traceId: span.spanContext().traceId,
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId,
+        ...(parentSpanId != null ? { parentSpanId } : {}),
       });
     }),
     shutdown: jest.fn(),
@@ -190,7 +196,6 @@ function tenantLangfuse(tenantId: string): t.LangfuseConfig {
     deterministicTraceId: true,
     metadata: { tenantId },
     tags: [`tenant:${tenantId}`],
-    toolNodeTracing: { enabled: true },
     toolOutputTracing: { enabled: true },
   };
 }
@@ -239,6 +244,23 @@ function expectNamedSpansUseTraceId({
   }
 }
 
+function expectChildSpanParentName({
+  starts,
+  childName,
+  parentNamePrefix,
+}: {
+  starts: SpanStartRecord[];
+  childName: string;
+  parentNamePrefix: string;
+}): void {
+  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);
+    expect(parent?.name.startsWith(parentNamePrefix)).toBe(true);
+  }
+}
+
 function expectOnlyTraceIds(
   starts: SpanStartRecord[],
   allowedTraceIds: string[]
@@ -446,6 +468,23 @@ describe('Langfuse per-run routing integration', () => {
     getChatModelClassSpy.mockRestore();
   });
 
+  it('keeps tool observations attached to the exported dispatch parent', async () => {
+    await runTenantFlow('tenant-hierarchy');
+
+    const starts = startsForTenant('tenant-hierarchy');
+    expect(starts.some((record) => record.name === 'tool_batch')).toBe(false);
+    expectChildSpanParentName({
+      starts,
+      childName: 'echo',
+      parentNamePrefix: 'tools=',
+    });
+    expectChildSpanParentName({
+      starts,
+      childName: 'subagent',
+      parentNamePrefix: 'tools=',
+    });
+  });
+
   it('routes parallel root, model, tool, subagent, and title spans to each run config', async () => {
     await Promise.all([runTenantFlow('tenant-a'), runTenantFlow('tenant-b')]);
 
@@ -462,10 +501,16 @@ describe('Langfuse per-run routing integration', () => {
         names: [
           `LibreChat Agent: Parent ${tenantId}`,
           'FakeChatModel',
-          'tool_batch',
+          'echo',
           'subagent',
         ],
       });
+      expect(starts.some((record) => record.name === 'tool_batch')).toBe(false);
+      expectChildSpanParentName({
+        starts,
+        childName: 'echo',
+        parentNamePrefix: 'tools=',
+      });
       expectNamedSpansUseTraceId({
         starts,
         traceId: titleTraceId,

package/src/specs/langfuse-tool-output-tracing.test.ts

@@ -118,7 +118,7 @@ describe('Langfuse tool output tracing redaction', () => {
     process.env = originalEnv;
   });
 
-  it('enables ToolNode tracing only when Langfuse is active by default', () => {
+  it('keeps internal ToolNode batch tracing opt-in', () => {
     delete process.env.LANGFUSE_SECRET_KEY;
     delete process.env.LANGFUSE_PUBLIC_KEY;
     delete process.env.LANGFUSE_BASE_URL;
@@ -132,7 +132,7 @@ describe('Langfuse tool output tracing redaction', () => {
           secretKey: 'sk-run',
         },
       })
-    ).toBe(true);
+    ).toBe(false);
     expect(
       shouldTraceToolNodeForLangfuse({
         agentLangfuse: {
@@ -149,7 +149,7 @@ describe('Langfuse tool output tracing redaction', () => {
     process.env.LANGFUSE_PUBLIC_KEY = 'pk-test';
     process.env.LANGFUSE_BASE_URL = 'https://langfuse.test';
 
-    expect(shouldTraceToolNodeForLangfuse({})).toBe(true);
+    expect(shouldTraceToolNodeForLangfuse({})).toBe(false);
     expect(
       shouldTraceToolNodeForLangfuse({
         runLangfuse: { toolNodeTracing: { enabled: true } },
@@ -162,7 +162,7 @@ describe('Langfuse tool output tracing redaction', () => {
     ).toBe(false);
   });
 
-  it('lets agent Langfuse enablement override disabled run defaults for ToolNode tracing', () => {
+  it('lets an agent explicitly opt into ToolNode batch tracing', () => {
     delete process.env.LANGFUSE_SECRET_KEY;
     delete process.env.LANGFUSE_PUBLIC_KEY;
     delete process.env.LANGFUSE_BASE_URL;
@@ -177,6 +177,7 @@ describe('Langfuse tool output tracing redaction', () => {
           publicKey: 'pk-agent',
           secretKey: 'sk-agent',
           baseUrl: 'https://langfuse.test',
+          toolNodeTracing: { enabled: true },
         },
       })
     ).toBe(true);

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

@@ -26,6 +26,8 @@ const INPUT = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
 const OUTPUT = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
 const TRACE_INPUT = LangfuseOtelSpanAttributes.TRACE_INPUT;
 const TRACE_OUTPUT = LangfuseOtelSpanAttributes.TRACE_OUTPUT;
+const OBSERVATION_TYPE = LangfuseOtelSpanAttributes.OBSERVATION_TYPE;
+const TRACE_TAGS = LangfuseOtelSpanAttributes.TRACE_TAGS;
 
 describe('shouldDropLangfuseSpan', () => {
   it('drops langgraph __start__ seed spans', () => {
@@ -40,6 +42,7 @@ describe('shouldDropLangfuseSpan', () => {
     expect(shouldDropLangfuseSpan('GenerateTitle')).toBe(false);
     expect(shouldDropLangfuseSpan('agent=openAI__gpt-5.4')).toBe(false);
     expect(shouldDropLangfuseSpan('ChatOpenAI')).toBe(false);
+    expect(shouldDropLangfuseSpan('tool_batch')).toBe(false);
   });
 });
 
@@ -48,9 +51,10 @@ describe('shapeLangfuseSpan', () => {
     const span = createSpan('agent=openAI__gpt-5.4', {}, 'parent-1');
     shapeLangfuseSpan(span);
     expect(span.name).toBe('agent');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('agent');
   });
 
-  it('renames tool node spans to the pending tool names and scopes input to args', () => {
+  it('shapes tool nodes as stable dispatch chains with scoped call inputs', () => {
     const messages = [
       { type: 'human', content: 'hello' },
       {
@@ -71,13 +75,14 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('get_service_details');
+    expect(span.name).toBe('tool-dispatch');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
     expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
       { name: 'get_service_details', args: { path: 'organizations/1' } },
     ]);
   });
 
-  it('joins multiple pending tool names and dedupes repeats', () => {
+  it('preserves every pending call in a multi-tool dispatch input', () => {
     const messages = [
       {
         type: 'ai',
@@ -89,12 +94,16 @@ describe('shapeLangfuseSpan', () => {
       },
     ];
     const span = createSpan(
-      'tool_batch',
+      'tools=openAI__gpt-5.4',
       { [INPUT]: JSON.stringify({ messages }) },
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('web_search, execute_code');
+    expect(JSON.parse(span.attributes[INPUT] as string)).toEqual([
+      { name: 'web_search', args: { q: 'a' } },
+      { name: 'web_search', args: { q: 'b' } },
+      { name: 'execute_code', args: { code: '1+1' } },
+    ]);
   });
 
   it('reads tool calls from serialized langchain message kwargs', () => {
@@ -115,10 +124,10 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('lookup');
+    expect(span.name).toBe('tool-dispatch');
   });
 
-  it('leaves tool node spans untouched when no tool calls are found', () => {
+  it('keeps a stable tool-dispatch shape when no tool calls are found', () => {
     const original = JSON.stringify({
       messages: [{ type: 'human', content: 'hi' }],
     });
@@ -128,12 +137,14 @@ describe('shapeLangfuseSpan', () => {
       'parent-1'
     );
     shapeLangfuseSpan(span);
-    expect(span.name).toBe('tools=agent_abc');
+    expect(span.name).toBe('tool-dispatch');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
     expect(span.attributes[INPUT]).toBe(original);
   });
 
   it('sets root span and trace input/output to the question and answer', () => {
     const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
       [INPUT]: JSON.stringify({
         messages: [
           { type: 'system', content: 'You are helpful.' },
@@ -156,6 +167,7 @@ describe('shapeLangfuseSpan', () => {
 
   it('extracts answer text from content part arrays', () => {
     const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
       [INPUT]: JSON.stringify([{ type: 'human', content: 'hi' }]),
       [OUTPUT]: JSON.stringify({
         messages: [
@@ -189,6 +201,65 @@ describe('shapeLangfuseSpan', () => {
     const span = createSpan('LibreChat Agent', { [INPUT]: 'plain text' });
     shapeLangfuseSpan(span);
     expect(span.attributes[INPUT]).toBe('plain text');
-    expect(span.attributes[TRACE_INPUT]).toBeUndefined();
+    expect(span.attributes[TRACE_INPUT]).toBe('plain text');
+  });
+
+  it('renames generation spans to a provider-agnostic name', () => {
+    const span = createSpan(
+      'ChatOpenAI',
+      { [OBSERVATION_TYPE]: 'generation' },
+      'parent-1'
+    );
+    shapeLangfuseSpan(span);
+    expect(span.name).toBe('llm');
+  });
+
+  it('marks only agent-tagged root spans as agent observations', () => {
+    const span = createSpan('LibreChat Agent', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'agent']),
+      [INPUT]: JSON.stringify({
+        messages: [{ type: 'human', content: 'hi' }],
+      }),
+    });
+    shapeLangfuseSpan(span);
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('agent');
+  });
+
+  it('marks title-tagged root spans as chain observations', () => {
+    const span = createSpan('LibreChat Title', {
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'title']),
+      [INPUT]: 'Conversation text',
+      [OUTPUT]: 'Conversation title',
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('chain');
+    expect(span.attributes[TRACE_INPUT]).toBe('Conversation text');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('Conversation title');
+  });
+
+  it('does not classify untagged root spans as agents', () => {
+    const span = createSpan('Custom root', { [INPUT]: 'input' });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.attributes[OBSERVATION_TYPE]).toBeUndefined();
+  });
+
+  it('shapes standalone generation roots without replacing their type', () => {
+    const span = createSpan('ChatOpenAI', {
+      [OBSERVATION_TYPE]: 'generation',
+      [TRACE_TAGS]: JSON.stringify(['librechat', 'title']),
+      [INPUT]: 'Generate a title',
+      [OUTPUT]: 'A useful title',
+    });
+
+    shapeLangfuseSpan(span);
+
+    expect(span.name).toBe('llm');
+    expect(span.attributes[OBSERVATION_TYPE]).toBe('generation');
+    expect(span.attributes[TRACE_INPUT]).toBe('Generate a title');
+    expect(span.attributes[TRACE_OUTPUT]).toBe('A useful title');
   });
 });