Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔭 feat: Conversation Trace Viewer (#15869)
Danny Avilaf43301f818dc
diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.jsindex b6f2dcba01..a7594950bb 100644--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js@@ -55,6 +55,7 @@ function wonGenerationClaim(overrides = {}) {}const mockCheckAndIncrementPendingRequest = jest.fn();+const mockGetFailedTurnTraceFields = jest.fn();const mockDecrementPendingRequest = jest.fn();const mockGetViolationInfo = jest.fn(() => ({type: 'concurrent',@@ -282,6 +283,7 @@ jest.mock('@librechat/api', () => ({jest.requireActual('@librechat/api').shouldPersistCodeWorkspaceInitializationError,getSafeErrorMetadata: jest.requireActual('@librechat/api').getSafeErrorMetadata,getSafeErrorText: jest.requireActual('@librechat/api').getSafeErrorText,+ getFailedTurnTraceFields: (...args) => mockGetFailedTurnTraceFields(...args),GenerationJobManager: mockGenerationJobManager,getReferencedQuotes: jest.fn((quotes) => {if (!Array.isArray(quotes)) {@@ -3822,6 +3824,83 @@ describe('ResumableAgentController resume metadata', () => {expect(savedIds).not.toContain('user-message_');});+ it('points a failed turn at the trace of the run that failed', async () => {+ const traceFields = {+ langfuseSampled: true,+ langfuseDestinationIds: ['destination-1'],+ langfuseRunId: 'server-response-uuid',+ };+ mockGetFailedTurnTraceFields.mockResolvedValue(traceFields);+ const serverUserMessage = {+ messageId: 'server-user',+ parentMessageId: 'prior-response',+ conversationId,+ sender: 'User',+ text: 'Hello with a removed model.',+ isCreatedByUser: true,+ };+ const client = {+ options: {},+ sendMessage: jest.fn(async (_text, options) => {+ options.onStart(serverUserMessage, 'server-response-uuid');+ client.run = {};+ throw new Error('failed inside the run');+ }),+ };++ await AgentController(+ createFailedRequest(),+ createResumableResponse(),+ jest.fn(),+ jest.fn().mockResolvedValue({ client }),+ null,+ );+ await flushBackgroundGeneration();++ const errorRow = mockSaveMessage.mock.calls+ .map(([, message]) => message)+ .find((message) => message.messageId === 'server-user_');+ expect(mockGetFailedTurnTraceFields).toHaveBeenCalledWith(expect.anything(), {+ messageId: 'server-user_',+ runId: 'server-response-uuid',+ runCreated: true,+ });+ expect(errorRow).toMatchObject({ error: true, isCreatedByUser: false, ...traceFields });+ });++ it('tells the trace lookup when a failure came before the run was created', async () => {+ mockGetFailedTurnTraceFields.mockResolvedValue({});+ const client = {+ options: {},+ sendMessage: jest.fn(async (_text, options) => {+ options.onStart(+ { messageId: 'server-user', conversationId, isCreatedByUser: true, text: 'Hi' },+ 'server-response-uuid',+ );+ throw new Error('failed before the run');+ }),+ };++ await AgentController(+ createFailedRequest(),+ createResumableResponse(),+ jest.fn(),+ jest.fn().mockResolvedValue({ client }),+ null,+ );+ await flushBackgroundGeneration();++ const errorRow = mockSaveMessage.mock.calls+ .map(([, message]) => message)+ .find((message) => message.messageId === 'server-user_');+ expect(mockGetFailedTurnTraceFields).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ runCreated: false }),+ );+ expect(errorRow).toMatchObject({ error: true });+ expect(errorRow).not.toHaveProperty('langfuseSampled');+ });+it('does not overwrite an existing response row', async () => {mockGetMessages.mockResolvedValue([{ _id: 'already-saved' }]);diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex d4ea75e173..65b92bfec5 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -45,6 +45,7 @@ const {logAgentMemorySnapshot,getCodeWorkspaceSelectionErrorDetails,shouldPersistCodeWorkspaceInitializationError,+ getFailedTurnTraceFields,} = require('@librechat/api');const { disposeClient } = require('~/server/cleanup');const {@@ -352,6 +353,7 @@ async function saveErrorTurn(errorText,liveUserMessage,liveResponseMessageId,+ runCreated = false,sender,initialAgentId,},@@ -467,9 +469,15 @@ async function saveErrorTurn(throw new Error('Failed user message could not be persisted');}}+ const langfuseTraceFields = await getFailedTurnTraceFields(req.config, {+ messageId: errorMessageId,+ runId: liveResponseMessageId,+ runCreated,+ });const savedErrorMessage = await saveMessage(reqCtx,{+ ...langfuseTraceFields,messageId: errorMessageId,conversationId,parentMessageId: errorParentMessageId,@@ -3211,6 +3219,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTiterrorText: generationError,liveUserMessage: userMessage,liveResponseMessageId,+ runCreated: client?.run != null,sender: client?.sender,initialAgentId: verifiedInitialAgentId,}),diff --git a/api/server/index.js b/api/server/index.jsindex 6fc63714fe..73ce8e45d7 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -403,6 +403,7 @@ const startServer = async () => {app.use('/api/search', routes.search);app.use('/api/messages', routes.messages);app.use('/api/convos', routes.convos);+ app.use('/api/traces', routes.traces);app.use('/api/presets', routes.presets);app.use('/api/projects', routes.projects);app.use('/api/prompts', routes.prompts);diff --git a/api/server/routes/__tests__/messages-feedback.spec.js b/api/server/routes/__tests__/messages-feedback.spec.jsindex 2076c2a4c3..46d53a3ce0 100644--- a/api/server/routes/__tests__/messages-feedback.spec.js+++ b/api/server/routes/__tests__/messages-feedback.spec.js@@ -135,6 +135,32 @@ describe('PUT /:conversationId/:messageId/feedback', () => {);});+ it('scores the trace of the run a failed turn stands for', async () => {+ updateMessage.mockImplementationOnce((userId, { messageId, feedback }) =>+ Promise.resolve({+ messageId,+ conversationId: 'conversation-1',+ endpoint: 'agents',+ langfuseSampled: true,+ langfuseDestinationIds: ['destination-1'],+ langfuseRunId: 'run-1',+ feedback,+ }),+ );++ const response = await request(app)+ .put('/api/messages/conversation-1/user-1_/feedback')+ .send({ feedback: { rating: 'thumbsDown', tag: 'other' } });++ expect(response.status).toBe(200);+ expect(sendFeedbackScore).toHaveBeenCalledWith(+ expect.objectContaining({+ traceId: 'trace-run-1',+ metadata: expect.objectContaining({ messageId: 'user-1_' }),+ }),+ );+ });+it.each([['an object tag', { rating: 'thumbsDown', tag: { key: 'inaccurate' } }],['a tag for the opposite rating', { rating: 'thumbsUp', tag: 'inaccurate' }],diff --git a/api/server/routes/__tests__/messages-get.spec.js b/api/server/routes/__tests__/messages-get.spec.jsindex d25357bd12..b72c0973f4 100644--- a/api/server/routes/__tests__/messages-get.spec.js+++ b/api/server/routes/__tests__/messages-get.spec.js@@ -51,6 +51,9 @@ jest.mock('@librechat/api', () => {};return {+ /** The real helper, without loading the rest of the package this suite mocks around. */+ withoutTraceRefs: jest.requireActual('../../../../packages/api/src/langfuse/trace.ts')+ .withoutTraceRefs,createContentFilter: jest.fn(() => (req, res, next) => next()),inspectContent,extractChatContent,@@ -528,6 +531,9 @@ describe('message route conversation ownership filters', () => {encoding: 'claude',fading: { v: 1, budgetTokens: 1, masked: true },},+ langfuseSampled: true,+ langfuseDestinationIds: ['forged-destination'],+ langfuseRunId: 'someone-elses-run',});expect(response.status).toBe(201);@@ -546,6 +552,9 @@ describe('message route conversation ownership filters', () => {expect(saveMessage.mock.calls[0][1]).not.toHaveProperty('userSubmittedPaths');expect(saveMessage.mock.calls[0][1]).not.toHaveProperty('userSubmittedMessageFieldPaths');expect(saveMessage.mock.calls[0][1]).not.toHaveProperty('contextMeta');+ expect(saveMessage.mock.calls[0][1].langfuseSampled).toBe(false);+ expect(saveMessage.mock.calls[0][1]).not.toHaveProperty('langfuseDestinationIds');+ expect(saveMessage.mock.calls[0][1]).not.toHaveProperty('langfuseRunId');expect(response.body.messageId).toBe(savedMessage.messageId);expect(response.body).not.toHaveProperty('contextMeta');expect(saveConvo).toHaveBeenCalledWith(diff --git a/api/server/routes/__tests__/messages-subagent-thread.spec.js b/api/server/routes/__tests__/messages-subagent-thread.spec.jsindex bb71adf098..3c7ee69e75 100644--- a/api/server/routes/__tests__/messages-subagent-thread.spec.js+++ b/api/server/routes/__tests__/messages-subagent-thread.spec.js@@ -6,6 +6,7 @@ const mockIsSubagentThreadWriteBlocked = jest.fn();jest.mock('@librechat/agents', () => ({ sleep: jest.fn() }));jest.mock('@librechat/api', () => ({+ withoutTraceRefs: jest.fn((message) => message),createContentFilter: jest.fn(() => (_req, _res, next) => next()),unescapeLaTeX: jest.fn((value) => value),countTokens: jest.fn().mockResolvedValue(1),diff --git a/api/server/routes/__tests__/traces.spec.js b/api/server/routes/__tests__/traces.spec.jsnew file mode 100644index 0000000000..1e20200844--- /dev/null+++ b/api/server/routes/__tests__/traces.spec.js@@ -0,0 +1,173 @@+const express = require('express');+const request = require('supertest');+const { createHash } = require('crypto');++const mockGetConvoOwnership = jest.fn();+const mockGetConversationTraceRefs = jest.fn();+const mockHasSampledTraceMessage = jest.fn();+let mockUser;+let mockTraceViewer;++jest.mock('~/models', () => ({+ getConvoOwnership: (...args) => mockGetConvoOwnership(...args),+ getConversationTraceRefs: (...args) => mockGetConversationTraceRefs(...args),+ hasSampledTraceMessage: (...args) => mockHasSampledTraceMessage(...args),+}));++jest.mock('~/server/middleware', () => ({+ requireJwtAuth: (req, res, next) => {+ if (!mockUser) {+ return res.status(401).json({ message: 'Unauthorized' });+ }+ req.user = mockUser;+ next();+ },+}));++jest.mock('~/server/middleware/config/app', () => (req, _res, next) => {+ req.config = { interfaceConfig: { traceViewer: mockTraceViewer } };+ next();+});++const traceIdFor = (seed) => createHash('sha256').update(seed, 'utf8').digest('hex').slice(0, 32);++const langfuseEnv = {+ LANGFUSE_PUBLIC_KEY: 'pk-route',+ LANGFUSE_SECRET_KEY: 'sk-route',+ LANGFUSE_PROJECT_ID: 'route-project',+ LANGFUSE_BASE_URL: 'https://langfuse.route.test',+};++describe('trace routes', () => {+ let app;+ let fetchSpy;++ beforeAll(() => {+ Object.assign(process.env, langfuseEnv);+ const tracesRouter = require('../traces');+ app = express();+ app.use('/api/traces', tracesRouter);+ });++ afterAll(() => {+ for (const key of Object.keys(langfuseEnv)) {+ delete process.env[key];+ }+ });++ beforeEach(() => {+ mockUser = { id: 'owner', role: 'USER' };+ mockTraceViewer = { enabled: true };+ mockGetConvoOwnership.mockResolvedValue({ user: 'owner' });+ mockGetConversationTraceRefs.mockResolvedValue({+ firstMessageAt: new Date('2026-09-12T11:00:00.000Z'),+ sampledMessages: [{ messageId: 'response-1' }],+ });+ mockHasSampledTraceMessage.mockResolvedValue(true);+ fetchSpy = jest.spyOn(global, 'fetch').mockImplementation(+ async () =>+ new Response(+ JSON.stringify({+ data: [+ {+ id: 'obs-root',+ traceId: traceIdFor('response-1'),+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:02.000Z',+ parentObservationId: null,+ type: 'AGENT',+ name: 'AgentGraph',+ level: 'DEFAULT',+ },+ {+ id: 'obs-foreign',+ traceId: traceIdFor('other-response'),+ startTime: '2026-09-12T11:31:00.000Z',+ endTime: '2026-09-12T11:31:02.000Z',+ parentObservationId: null,+ type: 'AGENT',+ name: 'AgentGraph',+ },+ ],+ meta: {},+ }),+ { status: 200, headers: { 'Content-Type': 'application/json' } },+ ),+ );+ });++ afterEach(() => {+ fetchSpy.mockRestore();+ });++ it('requires authentication', async () => {+ mockUser = undefined;++ const response = await request(app).get('/api/traces/convo-1/records');++ expect(response.status).toBe(401);+ expect(fetchSpy).not.toHaveBeenCalled();+ });++ it("reads the owner's sampled traces from Langfuse without exposing other traces", async () => {+ const availability = await request(app).get('/api/traces/convo-1/availability');+ const response = await request(app).get('/api/traces/convo-1/records');++ expect(availability.body).toEqual({ available: true });+ expect(response.status).toBe(200);+ expect(response.body.records.map(({ id }) => id)).toEqual(['obs-root']);+ expect(response.body.records[0]).toMatchObject({ messageId: 'response-1', kind: 'agent' });+ expect(mockGetConvoOwnership).toHaveBeenCalledWith('owner', 'convo-1', null);+ expect(mockHasSampledTraceMessage).toHaveBeenCalledWith({+ user: 'owner',+ conversationId: 'convo-1',+ tenantId: undefined,+ destinationIds: [+ createHash('sha256').update('https://langfuse.route.test\nroute-project').digest('hex'),+ ],+ });+ expect(mockGetConversationTraceRefs).toHaveBeenCalledWith({+ user: 'owner',+ conversationId: 'convo-1',+ tenantId: undefined,+ limit: 51,+ });+ const [url, init] = fetchSpy.mock.calls[0];+ expect(new URL(url).origin).toBe('https://langfuse.route.test');+ expect(JSON.parse(new URL(url).searchParams.get('filter'))).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ column: 'sessionId', operator: '=', value: 'convo-1' }),+ expect.objectContaining({ column: 'traceId', operator: 'any of' }),+ expect.objectContaining({ column: 'userId', operator: 'any of', value: ['owner'] }),+ ]),+ );+ expect(new Headers(init.headers).get('Authorization')).toBe(+ `Basic ${Buffer.from('pk-route:sk-route').toString('base64')}`,+ );+ expect(JSON.stringify(response.body)).not.toContain('sk-route');+ });++ it("refuses another user's conversation before reading Langfuse", async () => {+ mockGetConvoOwnership.mockResolvedValue(null);++ const availability = await request(app).get('/api/traces/convo-1/availability');+ const response = await request(app).get(+ '/api/traces/convo-1/records/obs-root?message=response-1',+ );++ expect(availability.body).toEqual({ available: false });+ expect(response.status).toBe(404);+ expect(mockGetConversationTraceRefs).not.toHaveBeenCalled();+ expect(fetchSpy).not.toHaveBeenCalled();+ });++ it('stays off until the deployment enables the viewer', async () => {+ mockTraceViewer = undefined;++ const response = await request(app).get('/api/traces/convo-1/records');++ expect(response.status).toBe(404);+ expect(response.body.errorCode).toBe('disabled');+ expect(fetchSpy).not.toHaveBeenCalled();+ });+});diff --git a/api/server/routes/index.js b/api/server/routes/index.jsindex c3b6c4bb8e..7827559f11 100644--- a/api/server/routes/index.js+++ b/api/server/routes/index.js@@ -28,6 +28,7 @@ const banner = require('./banner');const search = require('./search');const models = require('./models');const convos = require('./convos');+const traces = require('./traces');const config = require('./config');const agents = require('./agents');const roles = require('./roles');@@ -69,6 +70,7 @@ module.exports = {banner,agents,convos,+ traces,search,config,models,diff --git a/api/server/routes/messages.js b/api/server/routes/messages.jsindex 756f8ff8cb..6ac391c18d 100644--- a/api/server/routes/messages.js+++ b/api/server/routes/messages.js@@ -26,6 +26,7 @@ const {mergeUserSubmittedPaths,mergeUserSubmittedMessageFieldPaths,isContentFilterError,+ withoutTraceRefs,} = require('@librechat/api');const subagentThreadTaskStore = require('~/server/services/Endpoints/agents/subagentThreadStore');const { findAllArtifacts, replaceArtifactContent } = require('~/server/services/Artifacts/update');@@ -522,7 +523,8 @@ router.post('/:conversationId', storedMessageMutationMiddleware, async (req, resif (await rejectSubagentThreadWrite(req, res, req.params.conversationId)) {return;}- const message = { ...req.body, conversationId: req.params.conversationId };+ /** Trace sampling fields are ownership claims only the server writes. */+ const message = withoutTraceRefs({ ...req.body, conversationId: req.params.conversationId });delete message.isUserSubmitted;delete message.userSubmittedPaths;delete message.userSubmittedMessageFieldPaths;@@ -716,7 +718,7 @@ router.put(// Best-effort: Assistants messages do not have deterministic AgentRun traces.if (!isAssistantsEndpoint(updatedMessage.endpoint)) {sendFeedbackScore({- traceId: traceIdForMessage(messageId),+ traceId: traceIdForMessage(updatedMessage.langfuseRunId ?? messageId),sampled: updatedMessage.langfuseSampled,destinationIds: updatedMessage.langfuseDestinationIds,feedback: updatedMessage.feedback,diff --git a/api/server/routes/traces.js b/api/server/routes/traces.jsnew file mode 100644index 0000000000..b52869ed14--- /dev/null+++ b/api/server/routes/traces.js@@ -0,0 +1,33 @@+const express = require('express');+const {+ createTraceHandlers,+ limiterCache,+ createTraceReadLimiter,+ createLangfuseTraceReader,+ resolveLangfuseReadDestinations,+} = require('@librechat/api');+const configMiddleware = require('~/server/middleware/config/app');+const { requireJwtAuth } = require('~/server/middleware');+const db = require('~/models');++const router = express.Router();++const handlers = createTraceHandlers({+ reader: createLangfuseTraceReader({+ getConversationTraceRefs: db.getConversationTraceRefs,+ hasSampledTraceMessage: db.hasSampledTraceMessage,+ resolveDestinations: resolveLangfuseReadDestinations,+ fetch: (url, init) => fetch(url, init),+ }),+ getConvoOwnership: db.getConvoOwnership,+});+const traceReadLimiter = createTraceReadLimiter({+ store: limiterCache('trace_viewer_user_limiter'),+});++router.use(requireJwtAuth, configMiddleware);+router.get('/:conversationId/availability', handlers.availability);+router.get('/:conversationId/records', traceReadLimiter, handlers.records);+router.get('/:conversationId/records/:recordId', traceReadLimiter, handlers.record);++module.exports = router;diff --git a/api/server/utils/import/fork.js b/api/server/utils/import/fork.jsindex cd08d51862..467aabc0de 100644--- a/api/server/utils/import/fork.js+++ b/api/server/utils/import/fork.js@@ -1,4 +1,5 @@const { v4: uuidv4 } = require('uuid');+const { withoutTraceRefs } = require('@librechat/api');const { logger, tenantStorage } = require('@librechat/data-schemas');const { EModelEndpoint, Constants, ForkOptions } = require('librechat-data-provider');const { getConvo, getMessages, getSharedMessages } = require('~/models');@@ -64,7 +65,7 @@ function cloneMessagesWithTimestamps(}const clonedMessage = {- ...message,+ ...withoutTraceRefs(message),messageId: newMessageId,parentMessageId: parentId,createdAt,diff --git a/api/server/utils/import/fork.spec.js b/api/server/utils/import/fork.spec.jsindex 10c2bfdfbf..d53bb8775c 100644--- a/api/server/utils/import/fork.spec.js+++ b/api/server/utils/import/fork.spec.js@@ -185,6 +185,44 @@ describe('forkConversation', () => {).toBe(true);});+ test('does not carry the source messages trace sampling onto their copies', async () => {+ getMessages.mockResolvedValue([+ {+ messageId: 'user-1',+ parentMessageId: Constants.NO_PARENT,+ isCreatedByUser: true,+ text: 'Hello',+ },+ {+ messageId: 'response-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text: 'Hi',+ langfuseSampled: true,+ langfuseDestinationIds: ['destination-a'],+ langfuseRunId: 'run-a',+ },+ ]);++ await forkConversation({+ originalConvoId: 'abc123',+ targetMessageId: 'response-1',+ requestUserId: 'user1',+ option: ForkOptions.DIRECT_PATH,+ });++ const savedMessages = bulkSaveMessages.mock.calls[0][0];+ expect(savedMessages.map((message) => message.text)).toEqual(['Hello', 'Hi']);+ expect(+ savedMessages.every(+ (message) =>+ message.langfuseSampled === false &&+ !('langfuseDestinationIds' in message) &&+ !('langfuseRunId' in message),+ ),+ ).toBe(true);+ });+test('drops child execution metadata while retaining its visible transcript', async () => {getConvo.mockResolvedValue({...mockConversation,diff --git a/api/server/utils/import/importers.js b/api/server/utils/import/importers.jsindex 181796c339..d1d2edd29d 100644--- a/api/server/utils/import/importers.js+++ b/api/server/utils/import/importers.js@@ -7,6 +7,7 @@ const {stripMessageUIResourceMarkers,} = require('@librechat/data-schemas');const { EModelEndpoint, Constants, Tools, openAISettings } = require('librechat-data-provider');+const { withoutTraceRefs } = require('@librechat/api');const { getEndpointsConfig } = require('~/server/services/Config');const { createImportBatchBuilder } = require('./importBatchBuilder');const { resolveImportDefaultModel } = require('./defaults');@@ -59,8 +60,8 @@ function sanitizeImportedMessage(message) {const text = castPersistedImportedText(message.text);const content = normalizeImportedArray(message.content);const attachments = normalizeImportedArray(message.attachments);- const importable = { ...message };- /** Server-private run state never comes from an import. */+ /** Server-private run state and trace sampling records never come from an import. */+ const importable = withoutTraceRefs({ ...message });delete importable.contextMeta;return {...importable,diff --git a/api/server/utils/import/importers.spec.js b/api/server/utils/import/importers.spec.jsindex fcc96162fe..aa71772de5 100644--- a/api/server/utils/import/importers.spec.js+++ b/api/server/utils/import/importers.spec.js@@ -966,12 +966,15 @@ describe('importLibreChatConvo', () => {]);});- it('drops server-private context meta from imported messages', async () => {+ it('drops server-private context meta and trace sampling from imported messages', async () => {const message = {messageId: 'message-1',parentMessageId: Constants.NO_PARENT,text: 'Imported response',isCreatedByUser: false,+ langfuseSampled: true,+ langfuseDestinationIds: ['forged-destination'],+ langfuseRunId: 'someone-elses-run',contextMeta: {calibrationRatio: 1,encoding: 'claude',@@ -990,6 +993,9 @@ describe('importLibreChatConvo', () => {await importer(jsonData, 'user-123', () => importBatchBuilder);expect(importBatchBuilder.messages[0]).not.toHaveProperty('contextMeta');+ expect(importBatchBuilder.messages[0].langfuseSampled).toBe(false);+ expect(importBatchBuilder.messages[0]).not.toHaveProperty('langfuseDestinationIds');+ expect(importBatchBuilder.messages[0]).not.toHaveProperty('langfuseRunId');expect(importBatchBuilder.messages[0].isUserSubmitted).toBe(true);});diff --git a/client/src/components/Chat/ChatView.tsx b/client/src/components/Chat/ChatView.tsxindex de800d6eb4..24186fa708 100644--- a/client/src/components/Chat/ChatView.tsx+++ b/client/src/components/Chat/ChatView.tsx@@ -26,6 +26,7 @@ import { AskAnswerHostProvider } from './ask/state';import MessagesView from './Messages/MessagesView';import Presentation from './Presentation';import ChatForm from './Input/ChatForm';+import { TraceSurface } from './Trace';import Landing from './Landing';import Header from './Header';import { cn } from '~/utils';@@ -156,7 +157,7 @@ function ChatView({ index = 0, project }: { index?: number; project?: TChatProje<AddedChatContext.Provider value={addedChatHelpers}><ApprovalProvider pendingAction={pendingAction}><Presentation>- <div className="relative flex h-full w-full flex-col">+ <TraceSurface conversationId={conversationId}><h1 className="sr-only">{pageHeading}</h1><HeaderparentConversationId={parentConversationId}@@ -218,7 +219,7 @@ function ChatView({ index = 0, project }: { index?: number; project?: TChatProje</div>{isLandingPage && <Footer />}</>- </div>+ </TraceSurface></Presentation></ApprovalProvider></AddedChatContext.Provider>diff --git a/client/src/components/Chat/Header.tsx b/client/src/components/Chat/Header.tsxindex 02ce42ca2b..240e83fa3f 100644--- a/client/src/components/Chat/Header.tsx+++ b/client/src/components/Chat/Header.tsx@@ -10,6 +10,7 @@ import {import { OpenSidebar, PresetsMenu, NewChat, HeaderMenu } from './Menus';import { TemporaryChat, TemporaryChatIndicator } from './TemporaryChat';import ModelSelector from './Menus/Endpoints/ModelSelector';+import { TraceButton, useTraceControl } from './Trace';import { useGetStartupConfig } from '~/data-provider';import ExportAndShareMenu from './ExportAndShareMenu';import SubagentThreadLink from './SubagentThreadLink';@@ -36,6 +37,7 @@ function Header({}) {const { data: startupConfig } = useGetStartupConfig();const navVisible = useRecoilValue(store.sidebarExpanded);+ const isSubmitting = useRecoilValue(store.isSubmittingFamily(0));/** The mobile row only offers a new chat when there is one to leave. Read* from the route rather than the context conversation, which still holds the@@ -64,6 +66,14 @@ function Header({permission: Permissions.USE,});+ /** Child threads are view-only records of their parent's run and have no trace of their own. */+ const trace = useTraceControl({+ conversationId: isNewChat ? null : routeConversationId,+ traceViewer: interfaceConfig.traceViewer,+ isSubmitting,+ enabled: parentConversationId == null,+ });+/** The drawer covers the header on mobile; keep its controls out of the tab order. */const hiddenBehindNav = navVisible === true && 'max-md:hidden';@@ -101,8 +111,9 @@ function Header({<div className={cn('flex flex-shrink-0 items-center gap-2', hiddenBehindNav)}>{hasAccessToTemporaryChat === true && <TemporaryChatIndicator />}{!isNewChat && <NewChat className="md:hidden" />}- <HeaderMenu startupConfig={startupConfig} className="md:hidden" />+ <HeaderMenu startupConfig={startupConfig} trace={trace} className="md:hidden" /><div className="hidden items-center gap-2 md:flex">+ {trace.show && <TraceButton onClick={trace.open} />}<ExportAndShareMenu isSharedButtonEnabled={startupConfig?.sharedLinksEnabled ?? false} />{hasAccessToTemporaryChat === true && <TemporaryChat />}</div>diff --git a/client/src/components/Chat/Menus/HeaderMenu.tsx b/client/src/components/Chat/Menus/HeaderMenu.tsxindex f158685f70..b0a91ae9e7 100644--- a/client/src/components/Chat/Menus/HeaderMenu.tsx+++ b/client/src/components/Chat/Menus/HeaderMenu.tsx@@ -1,10 +1,11 @@import { useState, useId } from 'react';import * as Ariakit from '@ariakit/react';import { PermissionTypes, Permissions } from 'librechat-data-provider';-import { Ellipsis, PlusCircle, HatGlasses, Check } from 'lucide-react';import { DropdownPopup, TooltipAnchor, Button } from '@librechat/client';import { BookmarkFilledIcon, BookmarkIcon } from '@radix-ui/react-icons';+import { Ellipsis, PlusCircle, HatGlasses, Check, ChartNoAxesGantt } from 'lucide-react';import type { TStartupConfig } from 'librechat-data-provider';+import type { TraceControl } from '~/components/Chat/Trace';import type * as t from '~/common';import { BookmarkContext } from '~/Providers/BookmarkContext';import useBookmarkItems from '~/hooks/Chat/useBookmarkItems';@@ -22,9 +23,12 @@ import { cn } from '~/utils';*/export default function HeaderMenu({startupConfig,+ trace,className,}: {startupConfig?: TStartupConfig;+ /** Owned by the header, which also renders the desktop trace button from it. */+ trace?: TraceControl;className?: string;}) {const localize = useLocalize();@@ -87,6 +91,15 @@ export default function HeaderMenu({});}+ if (trace?.show === true) {+ pushGroup({+ id: 'header-trace',+ label: localize('com_ui_trace_view'),+ icon: <ChartNoAxesGantt className="size-4 text-text-secondary" />,+ onClick: trace.open,+ });+ }+if (exportShare.show) {pushGroup(...exportShare.items);}diff --git a/client/src/components/Chat/Menus/__tests__/HeaderMenu.spec.tsx b/client/src/components/Chat/Menus/__tests__/HeaderMenu.spec.tsxindex d4893b316a..30541a517c 100644--- a/client/src/components/Chat/Menus/__tests__/HeaderMenu.spec.tsx+++ b/client/src/components/Chat/Menus/__tests__/HeaderMenu.spec.tsx@@ -190,6 +190,35 @@ describe('HeaderMenu', () => {);});+ it('offers the trace in its own group only when the header says one is available', () => {+ const { rerender } = render(<HeaderMenu trace={{ show: false, open: jest.fn() }} />);+ expect(labels()).not.toContain('com_ui_trace_view');++ rerender(<HeaderMenu trace={{ show: true, open: jest.fn() }} />);++ expect(labels()).toEqual([+ 'com_ui_bookmarks',+ 'com_ui_add_multi_conversation',+ 'com_ui_trace_view',+ 'share',+ 'export',+ 'com_ui_temporary',+ ]);+ expect(rows().filter((node) => node.getAttribute('data-kind') === 'separator')).toHaveLength(3);+ });++ it('keeps the trace reachable when it is the only action left', () => {+ mockHookState.multiConvo.show = false;+ mockHookState.temporary.show = false;+ mockHookState.bookmarks.show = false;+ mockHookState.exportShare.show = false;++ render(<HeaderMenu trace={{ show: true, open: jest.fn() }} />);++ expect(labels()).toEqual(['com_ui_trace_view']);+ expect(rows()[0]).toHaveAttribute('data-kind', 'item');+ });+it('shows temporary chat as active to sighted users, not just assistive tech', () => {mockHookState.temporary.isTemporary = true;diff --git a/client/src/components/Chat/Trace/Button.tsx b/client/src/components/Chat/Trace/Button.tsxnew file mode 100644index 0000000000..a0cd14c0d0--- /dev/null+++ b/client/src/components/Chat/Trace/Button.tsx@@ -0,0 +1,27 @@+import { ChartNoAxesGantt } from 'lucide-react';+import { Button, TooltipAnchor } from '@librechat/client';+import { useLocalize } from '~/hooks';++/** Header control that opens the conversation trace over the chat. */+export default function TraceButton({ onClick }: { onClick: () => void }) {+ const localize = useLocalize();+ const label = localize('com_ui_trace_view');++ return (+ <TooltipAnchor+ description={label}+ render={+ <Button+ size="icon"+ variant="outline"+ aria-label={label}+ onClick={onClick}+ data-testid="header-trace-button"+ className="size-9 flex-shrink-0 rounded-xl bg-presentation hover:bg-surface-tertiary"+ >+ <ChartNoAxesGantt className="icon-md" aria-hidden="true" />+ </Button>+ }+ />+ );+}diff --git a/client/src/components/Chat/Trace/Inspector.tsx b/client/src/components/Chat/Trace/Inspector.tsxnew file mode 100644index 0000000000..cf931d64be--- /dev/null+++ b/client/src/components/Chat/Trace/Inspector.tsx@@ -0,0 +1,272 @@+import { memo, useId } from 'react';+import { X } from 'lucide-react';+import { Button, Spinner } from '@librechat/client';+import type { TTraceContent } from 'librechat-data-provider';+import type { ReactNode } from 'react';+import type { TranslationKeys } from '~/hooks';+import type { TraceNode } from './model';+import { useConversationTraceRecordQuery } from '~/data-provider';+import { useTraceFormat, recordDurationText } from './format';+import { formatCost, formatTokens } from '~/utils/tokens';+import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';+import { formatJSON } from '~/utils/json';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';++type Field = { label: TranslationKeys; value: ReactNode };++function Section({ title, fields }: { title: TranslationKeys; fields: Field[] }) {+ const localize = useLocalize();+ if (fields.length === 0) {+ return null;+ }+ return (+ <section className="flex flex-col gap-1.5">+ <h4 className="text-xs font-semibold uppercase tracking-wide text-text-secondary">+ {localize(title)}+ </h4>+ <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1 text-sm">+ {fields.map((field) => (+ <div key={field.label} className="contents">+ <dt className="text-text-secondary">{localize(field.label)}</dt>+ <dd className="min-w-0 break-words text-right tabular-nums text-text-primary">+ {field.value}+ </dd>+ </div>+ ))}+ </dl>+ </section>+ );+}++function ContentBlock({ label, content }: { label: TranslationKeys; content?: TTraceContent }) {+ const localize = useLocalize();+ if (!content) {+ return null;+ }+ const text = content.truncated ? content.value : formatJSON(content.value);+ return (+ <section className="flex flex-col gap-1">+ <h4 className="text-xs font-semibold uppercase tracking-wide text-text-secondary">+ {localize(label)}+ </h4>+ <pre className="max-h-80 overflow-auto whitespace-pre-wrap break-words rounded-lg border border-border-light bg-surface-primary-alt p-2 font-mono text-xs text-text-primary">+ {text}+ </pre>+ {content.truncated && (+ <p className="text-xs text-text-secondary">{localize('com_ui_trace_truncated')}</p>+ )}+ </section>+ );+}++function RecordContent({+ conversationId,+ recordId,+ messageId,+ sourceId,+}: {+ conversationId: string;+ recordId: string;+ messageId: string;+ sourceId?: string;+}) {+ const localize = useLocalize();+ const { data, isLoading, isError, refetch } = useConversationTraceRecordQuery(+ { conversationId, recordId, messageId, sourceId },+ true,+ );++ if (isLoading) {+ return (+ <div className="flex justify-center py-4" role="status">+ <Spinner className="size-4 text-text-secondary" />+ <span className="sr-only">{localize('com_ui_trace_loading')}</span>+ </div>+ );+ }+ if (isError || !data) {+ return (+ <div className="flex flex-col items-start gap-2 text-sm text-text-secondary">+ <p>{localize('com_ui_trace_content_error')}</p>+ <Button size="sm" variant="outline" onClick={() => refetch()}>+ {localize('com_ui_retry')}+ </Button>+ </div>+ );+ }+ if (!data.contentAvailable) {+ return <p className="text-sm text-text-secondary">{localize('com_ui_trace_content_hidden')}</p>;+ }+ if (!data.input && !data.output && !data.metadata) {+ return <p className="text-sm text-text-secondary">{localize('com_ui_trace_content_empty')}</p>;+ }+ return (+ <div className="flex flex-col gap-3">+ <ContentBlock label="com_ui_trace_input" content={data.input} />+ <ContentBlock label="com_ui_trace_output" content={data.output} />+ <ContentBlock label="com_ui_trace_metadata" content={data.metadata} />+ </div>+ );+}++/** Details for the selected record; input and output load only when the deployment allows them. */+function Inspector({+ node,+ turnStart,+ sourceId,+ conversationId,+ showContent,+ showCost,+ currency,+ onClose,+}: {+ node: TraceNode;+ turnStart: number;+ /** The page source that listed this record. */+ sourceId?: string;+ conversationId: string;+ showContent: boolean;+ showCost: boolean;+ currency?: { code: string; rate: number };+ onClose: () => void;+}) {+ const localize = useLocalize();+ const format = useTraceFormat();+ const headingId = useId();+ const { record } = node;+ const appearance = KIND_APPEARANCE[record.kind];+ const Icon = appearance.icon;+ const { usage } = record;++ const timing: Field[] = [+ { label: 'com_ui_trace_started', value: format.clock(node.start) },+ { label: 'com_ui_trace_offset', value: format.duration(node.start - turnStart) },+ {+ label: 'com_ui_trace_column_duration',+ value: recordDurationText(node, format, localize(STATUS_LABEL.running)),+ },+ ];+ if (node.firstToken != null) {+ timing.push({+ label: 'com_ui_trace_ttft',+ value: format.duration(node.firstToken - node.start),+ });+ if (node.end != null) {+ timing.push({+ label: 'com_ui_trace_decoding',+ value: format.duration(node.end - node.firstToken),+ });+ }+ }++ const usageFields: Field[] = (+ [+ ['com_ui_trace_usage_input', usage?.input],+ ['com_ui_trace_usage_output', usage?.output],+ ['com_ui_trace_usage_reasoning', usage?.reasoning],+ ['com_ui_trace_usage_cache_read', usage?.cacheRead],+ ['com_ui_trace_usage_cache_write', usage?.cacheWrite],+ ['com_ui_trace_usage_total', usage?.total],+ ] as Array<[TranslationKeys, number | undefined]>+ )+ .filter((entry): entry is [TranslationKeys, number] => entry[1] != null)+ .map(([label, value]) => ({ label, value: formatTokens(value) }));+ if (showCost && record.cost != null) {+ usageFields.push({+ label: 'com_ui_trace_summary_cost',+ value: formatCost(record.cost, currency),+ });+ }++ return (+ <aside+ aria-labelledby={headingId}+ data-testid="trace-inspector"+ className="flex min-h-0 flex-col border-border-light bg-presentation max-md:absolute max-md:inset-x-0 max-md:bottom-0 max-md:z-20 max-md:max-h-[65%] max-md:rounded-t-2xl max-md:border-t max-md:shadow-lg md:w-[22rem] md:shrink-0 md:border-l"+ >+ <div className="flex items-center gap-2 border-b border-border-light px-3 py-2">+ <Icon aria-hidden="true" className="size-4 shrink-0 text-text-secondary" />+ <h3 id={headingId} className="min-w-0 flex-1 truncate text-sm font-semibold">+ {record.name}+ </h3>+ <Button+ size="icon-sm"+ variant="ghost"+ onClick={onClose}+ aria-label={localize('com_ui_trace_close_details')}+ >+ <X className="size-4" aria-hidden="true" />+ </Button>+ </div>+ <div className="flex min-h-0 flex-col gap-4 overflow-y-auto p-3">+ <div className="flex flex-wrap items-center gap-2 text-xs">+ <span className="rounded-full border border-border-light px-2 py-0.5 text-text-secondary">+ {localize(appearance.label)}+ </span>+ <span+ className={cn(+ 'rounded-full border px-2 py-0.5',+ record.status === 'error' &&+ 'border-status-error-border bg-status-error-subtle text-status-error',+ record.status === 'warning' &&+ 'border-status-warning-border bg-status-warning-subtle text-status-warning',+ (record.status === 'ok' || record.status === 'running') &&+ 'border-border-light text-text-secondary',+ )}+ >+ {localize(STATUS_LABEL[record.status])}+ </span>+ </div>+ {record.statusMessage != null && (+ <p+ className={cn(+ 'whitespace-pre-wrap break-words rounded-lg border p-2 text-xs',+ record.status === 'error'+ ? 'border-status-error-border bg-status-error-subtle text-status-error'+ : 'border-status-warning-border bg-status-warning-subtle text-status-warning',+ )}+ >+ {record.statusMessage}+ </p>+ )}+ <Section title="com_ui_trace_timing" fields={timing} />+ <Section+ title="com_ui_trace_model"+ fields={+ record.model != null ? [{ label: 'com_ui_trace_model', value: record.model }] : []+ }+ />+ <Section title="com_ui_trace_usage" fields={usageFields} />+ <Section+ title="com_ui_trace_identifiers"+ fields={[+ {+ label: 'com_ui_trace_record_id',+ value: <span className="select-all font-mono text-xs">{record.id}</span>,+ },+ {+ label: 'com_ui_trace_trace_id',+ value: <span className="select-all font-mono text-xs">{record.traceId}</span>,+ },+ ]}+ />+ {showContent && (+ <section className="flex flex-col gap-2">+ <h4 className="text-xs font-semibold uppercase tracking-wide text-text-secondary">+ {localize('com_ui_trace_content')}+ </h4>+ <RecordContent+ conversationId={conversationId}+ recordId={record.id}+ messageId={record.messageId}+ sourceId={sourceId}+ />+ </section>+ )}+ </div>+ </aside>+ );+}++export default memo(Inspector);diff --git a/client/src/components/Chat/Trace/Ledger.tsx b/client/src/components/Chat/Trace/Ledger.tsxnew file mode 100644index 0000000000..2631c73b86--- /dev/null+++ b/client/src/components/Chat/Trace/Ledger.tsx@@ -0,0 +1,394 @@+import { memo, useId, useMemo, useState } from 'react';+import { ChevronRight, CircleAlert, CircleDashed } from 'lucide-react';+import type { RefObject, CSSProperties, KeyboardEvent } from 'react';+import type { TraceModel, TraceNode, TraceRow, TraceTurn, TraceWindow } from './model';+import { useTraceFormat, recordDurationText } from './format';+import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';+import { formatTokens } from '~/utils/tokens';+import { useRowWindow } from './virtual';+import { useLocalize } from '~/hooks';+import { turnKey } from './model';+import { cn } from '~/utils';++const ROW_HEIGHT = 32;+const HEADER_HEIGHT = 28;+const INDENT_PX = 14;+/** Shown only while the tree itself has keyboard focus, so a pointer user sees just the selection. */+const ACTIVE_RING =+ 'group-focus-visible/tree:ring-2 group-focus-visible/tree:ring-inset group-focus-visible/tree:ring-ring-primary';+const GRID =+ 'grid grid-cols-[minmax(0,1fr)_4.5rem_minmax(5rem,1fr)] md:grid-cols-[minmax(14rem,2fr)_5rem_4.5rem_minmax(10rem,3fr)]';++type Domain = { start: number; span: number };++const barStyle = (start: number, end: number, domain: Domain): CSSProperties => ({+ left: `${((start - domain.start) / domain.span) * 100}%`,+ width: `${((end - start) / domain.span) * 100}%`,+});++function RecordBar({ node, domain }: { node: TraceNode; domain: Domain }) {+ const { record } = node;+ const appearance = KIND_APPEARANCE[record.kind];+ const solid = record.status === 'error' ? 'bg-status-error' : appearance.bar;++ if (node.end == null) {+ return (+ <span+ className={cn('absolute top-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rotate-45', solid)}+ style={{ left: `${((node.start - domain.start) / domain.span) * 100}%` }}+ />+ );+ }++ const duration = node.end - node.start;+ const ttftShare =+ node.firstToken != null && duration > 0 ? (node.firstToken - node.start) / duration : 0;+ return (+ <span+ className="absolute top-1/2 flex h-2.5 min-w-[2px] -translate-y-1/2 overflow-hidden rounded-sm"+ style={barStyle(node.start, node.end, domain)}+ >+ {ttftShare > 0 && (+ <span+ className={cn(+ 'h-full',+ record.status === 'error' ? 'bg-status-error/40' : appearance.tint,+ )}+ style={{ width: `${ttftShare * 100}%` }}+ />+ )}+ <span className={cn('h-full flex-1', solid)} />+ </span>+ );+}++function TurnBar({ turn, domain }: { turn: TraceTurn; domain: Domain }) {+ return (+ <span+ className="absolute top-1/2 h-1 min-w-[2px] -translate-y-1/2 rounded-full bg-border-heavy"+ style={barStyle(turn.start, turn.end, domain)}+ />+ );+}++function recordTokens(node: TraceNode): string {+ const usage = node.record.usage;+ if (node.record.kind !== 'generation' || usage == null) {+ return '';+ }+ const total = usage.total ?? (usage.input ?? 0) + (usage.output ?? 0);+ return total > 0 ? formatTokens(total) : '';+}++const toDomain = (start: number, end: number): Domain => ({+ start,+ span: Math.max(end - start, 1),+});++/**+ * The hierarchical record list: one row per turn and per record. Each bar is+ * scaled to its own response, so a short turn in a long conversation stays+ * legible, until an interval is focused and every row shares that scale. Rows+ * are windowed, and the tree follows the ARIA tree pattern through+ * `aria-activedescendant`, which must name a mounted row, so the active row+ * stays rendered while the window scrolls away from it.+ */+function Ledger({+ rows,+ model,+ view,+ selectedId,+ treeRef,+ onSelect,+ onToggle,+}: {+ rows: TraceRow[];+ model: TraceModel;+ view: TraceWindow | null;+ selectedId: string | null;+ treeRef: RefObject<HTMLDivElement>;+ onSelect: (id: string) => void;+ onToggle: (key: string) => void;+}) {+ const localize = useLocalize();+ const format = useTraceFormat();+ const idPrefix = useId();+ const scrollRef = treeRef;+ const [activeKey, setActiveKey] = useState<string | null>(null);+ const { first, last } = useRowWindow(scrollRef, rows.length, ROW_HEIGHT, {+ offset: HEADER_HEIGHT,+ });++ const indexByKey = useMemo(() => new Map(rows.map((row, index) => [row.key, index])), [rows]);+ const turnDomains = useMemo(+ () => new Map(model.turns.map((turn) => [turn.messageId, toDomain(turn.start, turn.end)])),+ [model],+ );+ const viewDomain = useMemo(() => (view ? toDomain(view.start, view.end) : null), [view]);+ const domainFor = (messageId: string): Domain =>+ viewDomain ?? turnDomains.get(messageId) ?? toDomain(model.start, model.end);+ const activeIndex = activeKey != null ? (indexByKey.get(activeKey) ?? 0) : 0;+ const activeRow = rows[activeIndex];+ const rowId = (key: string) => `${idPrefix}-${key}`;++ /** Keeps a keyboard-moved row inside the viewport so its windowed element mounts. */+ const scrollIntoView = (index: number) => {+ const element = scrollRef.current;+ if (!element) {+ return;+ }+ const top = index * ROW_HEIGHT;+ if (top < element.scrollTop) {+ element.scrollTop = top;+ } else if (HEADER_HEIGHT + top + ROW_HEIGHT > element.scrollTop + element.clientHeight) {+ element.scrollTop = HEADER_HEIGHT + top + ROW_HEIGHT - element.clientHeight;+ }+ };++ const moveTo = (index: number) => {+ const clamped = Math.min(Math.max(index, 0), rows.length - 1);+ const row = rows[clamped];+ scrollIntoView(clamped);+ if (row) {+ setActiveKey(row.key);+ }+ };++ const activate = (row: TraceRow) => {+ setActiveKey(row.key);+ if (row.type === 'record') {+ onSelect(row.key);+ } else {+ onToggle(row.key);+ }+ };++ const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {+ if (!activeRow) {+ return;+ }+ const expandable = activeRow.type === 'turn' || activeRow.hasChildren;+ const pageSize = Math.max(1, Math.floor((scrollRef.current?.clientHeight ?? 0) / ROW_HEIGHT));+ const handlers: Record<string, () => void> = {+ ArrowDown: () => moveTo(activeIndex + 1),+ ArrowUp: () => moveTo(activeIndex - 1),+ PageDown: () => moveTo(activeIndex + pageSize),+ PageUp: () => moveTo(activeIndex - pageSize),+ Home: () => moveTo(0),+ End: () => moveTo(rows.length - 1),+ ArrowRight: () => {+ if (expandable && !activeRow.expanded) {+ onToggle(activeRow.key);+ } else if (expandable) {+ moveTo(activeIndex + 1);+ }+ },+ ArrowLeft: () => {+ if (expandable && activeRow.expanded) {+ onToggle(activeRow.key);+ return;+ }+ if (activeRow.type === 'record') {+ const { node } = activeRow;+ const parentKey = node.parentId ?? turnKey(node.record.messageId);+ const parentIndex = indexByKey.get(parentKey);+ if (parentIndex != null) {+ moveTo(parentIndex);+ }+ }+ },+ Enter: () => activate(activeRow),+ ' ': () => activate(activeRow),+ };+ const handler = handlers[event.key];+ if (handler) {+ event.preventDefault();+ handler();+ }+ };++ const renderRow = (row: TraceRow, index: number) => {+ const style: CSSProperties = { top: HEADER_HEIGHT + index * ROW_HEIGHT, height: ROW_HEIGHT };+ const active = activeRow?.key === row.key;+ const common = {+ id: rowId(row.key),+ role: 'treeitem',+ 'aria-posinset': row.position,+ 'aria-setsize': row.setSize,+ style,+ onClick: () => activate(row),+ };++ if (row.type === 'turn') {+ const { turn } = row;+ const label = localize('com_ui_trace_turn', { 0: format.clock(turn.start) });+ return (+ <div+ key={row.key}+ {...common}+ aria-level={1}+ aria-expanded={row.expanded}+ aria-label={`${label}, ${localize('com_ui_trace_turn_records', { 0: String(turn.recordCount) })}, ${format.duration(turn.end - turn.start)}`}+ className={cn(+ GRID,+ 'absolute inset-x-0 cursor-pointer items-center gap-2 border-t border-border-light bg-surface-primary-alt px-2 text-xs font-semibold text-text-primary hover:bg-surface-hover',+ active && ACTIVE_RING,+ )}+ >+ <span className="flex min-w-0 items-center gap-1.5">+ <ChevronRight+ aria-hidden="true"+ className={cn(+ 'size-3.5 shrink-0 text-text-secondary transition-transform motion-reduce:transition-none',+ row.expanded && 'rotate-90',+ )}+ />+ <span className="truncate">{label}</span>+ {turn.errorCount > 0 && (+ <CircleAlert aria-hidden="true" className="size-3.5 shrink-0 text-status-error" />+ )}+ </span>+ <span className="text-right font-normal tabular-nums text-text-secondary">+ {format.duration(turn.end - turn.start)}+ </span>+ <span className="hidden md:block" />+ <span className="relative h-full overflow-hidden">+ <TurnBar turn={turn} domain={domainFor(turn.messageId)} />+ </span>+ </div>+ );+ }++ const { node } = row;+ const { record } = node;+ const turnStart = turnDomains.get(record.messageId)?.start ?? model.start;+ const appearance = KIND_APPEARANCE[record.kind];+ const Icon = appearance.icon;+ const running = record.status === 'running';+ const duration = recordDurationText(node, format, localize(STATUS_LABEL.running));+ const statusText =+ record.status === 'error' || record.status === 'warning'+ ? `${duration}, ${localize(STATUS_LABEL[record.status])}`+ : duration;++ return (+ <div+ key={row.key}+ {...common}+ aria-level={node.depth + 2}+ aria-expanded={row.hasChildren ? row.expanded : undefined}+ aria-selected={selectedId === row.key}+ aria-label={localize('com_ui_trace_bar_description', {+ 0: `${record.name}, ${localize(appearance.label)}`,+ 1: format.duration(node.start - turnStart),+ 2: statusText,+ })}+ className={cn(+ GRID,+ 'absolute inset-x-0 cursor-pointer items-center gap-2 px-2 text-sm text-text-primary hover:bg-surface-hover',+ selectedId === row.key && 'bg-surface-active-alt',+ active && ACTIVE_RING,+ )}+ >+ <span+ className="flex min-w-0 items-center gap-1.5"+ style={{ paddingLeft: node.depth * INDENT_PX }}+ >+ <span+ aria-hidden="true"+ onClick={(event) => {+ if (row.hasChildren) {+ event.stopPropagation();+ setActiveKey(row.key);+ onToggle(row.key);+ }+ }}+ className="flex size-4 shrink-0 items-center justify-center"+ >+ {row.hasChildren && (+ <ChevronRight+ className={cn(+ 'size-3.5 text-text-secondary transition-transform motion-reduce:transition-none',+ row.expanded && 'rotate-90',+ )}+ />+ )}+ </span>+ <Icon aria-hidden="true" className="size-3.5 shrink-0 text-text-secondary" />+ <span className="min-w-[3ch] truncate">{record.name}</span>+ {record.model != null && (+ <span className="hidden min-w-0 shrink-[4] truncate text-xs text-text-secondary sm:inline">+ {record.model}+ </span>+ )}+ {record.status === 'error' && (+ <CircleAlert aria-hidden="true" className="size-3.5 shrink-0 text-status-error" />+ )}+ {running && (+ <CircleDashed aria-hidden="true" className="size-3.5 shrink-0 text-text-secondary" />+ )}+ </span>+ <span className="truncate text-right text-xs tabular-nums text-text-secondary">+ {duration}+ </span>+ <span className="hidden text-right text-xs tabular-nums text-text-secondary md:block">+ {recordTokens(node)}+ </span>+ <span className="relative h-full overflow-hidden">+ <RecordBar node={node} domain={domainFor(record.messageId)} />+ </span>+ </div>+ );+ };++ const visibleRows: JSX.Element[] = [];+ for (let index = first; index <= last && index < rows.length; index++) {+ visibleRows.push(renderRow(rows[index], index));+ }+ if (activeRow && (activeIndex < first || activeIndex > last)) {+ visibleRows.push(renderRow(activeRow, activeIndex));+ }++ return (+ <div+ ref={scrollRef}+ role="tree"+ tabIndex={0}+ aria-label={localize('com_ui_trace_records')}+ aria-activedescendant={activeRow ? rowId(activeRow.key) : undefined}+ onKeyDown={handleKeyDown}+ onFocus={() => {+ if (activeKey == null && rows[0]) {+ setActiveKey(rows[0].key);+ }+ }}+ data-testid="trace-ledger"+ className="group/tree relative min-h-0 flex-1 overflow-auto focus-visible:outline-none"+ >+ <div+ aria-hidden="true"+ className={cn(+ GRID,+ 'sticky top-0 z-10 h-7 items-center gap-2 border-b border-border-light bg-presentation px-2 text-[11px] font-medium uppercase tracking-wide text-text-secondary',+ )}+ >+ <span>{localize('com_ui_trace_column_name')}</span>+ <span className="text-right">{localize('com_ui_trace_column_duration')}</span>+ <span className="hidden text-right md:block">{localize('com_ui_trace_column_tokens')}</span>+ {viewDomain ? (+ <span className="flex justify-between normal-case tabular-nums tracking-normal">+ <span>{format.duration(viewDomain.start - model.start)}</span>+ <span>{format.duration(viewDomain.start + viewDomain.span - model.start)}</span>+ </span>+ ) : (+ <span>{localize('com_ui_trace_column_timeline')}</span>+ )}+ </div>+ <div role="presentation" style={{ height: rows.length * ROW_HEIGHT }}>+ {visibleRows}+ </div>+ </div>+ );+}++export default memo(Ledger);diff --git a/client/src/components/Chat/Trace/Summary.tsx b/client/src/components/Chat/Trace/Summary.tsxnew file mode 100644index 0000000000..6287623643--- /dev/null+++ b/client/src/components/Chat/Trace/Summary.tsx@@ -0,0 +1,79 @@+import { memo } from 'react';+import type { TranslationKeys } from '~/hooks';+import type { TraceSummary } from './model';+import { formatCost, formatTokens } from '~/utils/tokens';+import { useTraceFormat } from './format';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';++type SummaryItem = { key: string; label: TranslationKeys; value: string; alert?: boolean };++function TraceSummaryBar({+ summary,+ showCost,+ currency,+}: {+ summary: TraceSummary;+ showCost: boolean;+ currency?: { code: string; rate: number };+}) {+ const localize = useLocalize();+ const format = useTraceFormat();+ const items: SummaryItem[] = [+ {+ key: 'duration',+ label: 'com_ui_trace_summary_duration',+ value: format.duration(summary.duration),+ },+ { key: 'turns', label: 'com_ui_trace_summary_turns', value: String(summary.turns) },+ {+ key: 'generations',+ label: 'com_ui_trace_summary_generations',+ value: String(summary.generations),+ },+ { key: 'tools', label: 'com_ui_trace_summary_tools', value: String(summary.toolCalls) },+ {+ key: 'tokens',+ label: 'com_ui_trace_summary_tokens',+ value: formatTokens(summary.totalTokens),+ },+ ];+ if (showCost && summary.cost != null) {+ items.push({+ key: 'cost',+ label: 'com_ui_trace_summary_cost',+ value: formatCost(summary.cost, currency),+ });+ }+ if (summary.errors > 0) {+ items.push({+ key: 'errors',+ label: 'com_ui_trace_summary_errors',+ value: String(summary.errors),+ alert: true,+ });+ }++ return (+ <dl+ aria-label={localize('com_ui_trace_summary')}+ className="flex flex-wrap items-center gap-x-5 gap-y-1 text-sm"+ >+ {items.map((item) => (+ <div key={item.key} className="flex items-baseline gap-1.5">+ <dt className="text-xs text-text-secondary">{localize(item.label)}</dt>+ <dd+ className={cn(+ 'font-medium tabular-nums',+ item.alert === true ? 'text-status-error' : 'text-text-primary',+ )}+ >+ {item.value}+ </dd>+ </div>+ ))}+ </dl>+ );+}++export default memo(TraceSummaryBar);diff --git a/client/src/components/Chat/Trace/Surface.tsx b/client/src/components/Chat/Trace/Surface.tsxnew file mode 100644index 0000000000..4debfb970f--- /dev/null+++ b/client/src/components/Chat/Trace/Surface.tsx@@ -0,0 +1,44 @@+import { useEffect } from 'react';+import { useAtom } from 'jotai';+import type { ReactNode } from 'react';+import { traceViewerConversationAtom } from './store';+import Viewer from './Viewer';+import { cn } from '~/utils';++/**+ * Hosts the trace over the chat without unmounting it: the chat stays mounted+ * and inert underneath, so closing the trace restores its scroll position,+ * composer draft and focus target exactly as they were.+ */+export default function TraceSurface({+ conversationId,+ children,+}: {+ conversationId?: string | null;+ children: ReactNode;+}) {+ const [traceConversationId, setTraceConversationId] = useAtom(traceViewerConversationAtom);+ const open = conversationId != null && traceConversationId === conversationId;++ useEffect(() => {+ if (traceConversationId != null && traceConversationId !== conversationId) {+ setTraceConversationId(null);+ }+ }, [conversationId, traceConversationId, setTraceConversationId]);++ return (+ <div className="relative flex h-full w-full flex-col">+ {/* `isolate` while covered: the chat's own layers (the message rail sits at+ z-40) would otherwise stack above the trace. */}+ <div+ className={cn('flex h-full w-full flex-col', open && 'isolate')}+ inert={open ? '' : undefined}+ >+ {children}+ </div>+ {open && (+ <Viewer conversationId={conversationId} onClose={() => setTraceConversationId(null)} />+ )}+ </div>+ );+}diff --git a/client/src/components/Chat/Trace/Timeline.tsx b/client/src/components/Chat/Trace/Timeline.tsxnew file mode 100644index 0000000000..23724377cb--- /dev/null+++ b/client/src/components/Chat/Trace/Timeline.tsx@@ -0,0 +1,245 @@+import { memo, useId, useRef, useMemo, useState, useEffect, useCallback } from 'react';+import type { KeyboardEvent, PointerEvent } from 'react';+import type { TraceModel, TraceWindow } from './model';+import { ZOOM_STEP, zoomWindow, panWindow, assignLanes, clampWindow, minimumSpan } from './model';+import { KIND_APPEARANCE } from './kinds';+import { useTraceFormat } from './format';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';++const LANE_COUNT = 8;+const LANE_HEIGHT = 5;+const LANE_GAP = 1;+const TOP_PADDING = 6;+const DRAG_THRESHOLD_PX = 3;+const TICKS = [0, 0.25, 0.5, 0.75, 1];++type Drag = { origin: number; current: number; moved: boolean; pointerId: number };++const percent = (fraction: number) => `${Math.min(Math.max(fraction, 0), 1) * 100}%`;++/**+ * The pinned overview of the whole trace. It always draws every loaded record+ * at full scale; the focused interval is an overlay the ledger follows.+ */+function Timeline({+ model,+ view,+ onViewChange,+}: {+ model: TraceModel;+ view: TraceWindow | null;+ onViewChange: (view: TraceWindow | null) => void;+}) {+ const localize = useLocalize();+ const format = useTraceFormat();+ const hintId = useId();+ const surfaceRef = useRef<HTMLDivElement>(null);+ const dragRef = useRef<Drag | null>(null);+ const [draft, setDraft] = useState<{ from: number; to: number } | null>(null);++ const span = Math.max(model.end - model.start, 1);+ const lanes = useMemo(() => assignLanes(model, LANE_COUNT), [model]);+ const records = useMemo(() => [...model.nodes.values()], [model]);+ const toFraction = useCallback(+ (time: number) => (time - model.start) / span,+ [model.start, span],+ );++ const fractionAt = (clientX: number): number => {+ const rect = surfaceRef.current?.getBoundingClientRect();+ if (!rect || rect.width === 0) {+ return 0;+ }+ return Math.min(Math.max((clientX - rect.left) / rect.width, 0), 1);+ };++ useEffect(() => {+ const surface = surfaceRef.current;+ if (!surface) {+ return;+ }+ /** Registered natively: React's wheel listener is passive and cannot stop page scroll. */+ const handleWheel = (event: WheelEvent) => {+ if (event.deltaY === 0) {+ return;+ }+ event.preventDefault();+ const rect = surface.getBoundingClientRect();+ const fraction = rect.width > 0 ? (event.clientX - rect.left) / rect.width : 0.5;+ const anchor = model.start + Math.min(Math.max(fraction, 0), 1) * span;+ const factor = event.deltaY > 0 ? 1 / ZOOM_STEP : ZOOM_STEP;+ onViewChange(zoomWindow(model, view, factor, anchor));+ };+ surface.addEventListener('wheel', handleWheel, { passive: false });+ return () => surface.removeEventListener('wheel', handleWheel);+ }, [model, span, view, onViewChange]);++ const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {+ if (event.button !== 0) {+ return;+ }+ const origin = fractionAt(event.clientX);+ dragRef.current = { origin, current: origin, moved: false, pointerId: event.pointerId };+ event.currentTarget.setPointerCapture?.(event.pointerId);+ };++ const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {+ const drag = dragRef.current;+ if (!drag || drag.pointerId !== event.pointerId) {+ return;+ }+ const width = surfaceRef.current?.getBoundingClientRect().width ?? 0;+ drag.current = fractionAt(event.clientX);+ drag.moved = drag.moved || Math.abs(drag.current - drag.origin) * width > DRAG_THRESHOLD_PX;+ if (drag.moved) {+ setDraft({+ from: Math.min(drag.origin, drag.current),+ to: Math.max(drag.origin, drag.current),+ });+ }+ };++ const finishDrag = (event: PointerEvent<HTMLDivElement>) => {+ const drag = dragRef.current;+ dragRef.current = null;+ setDraft(null);+ if (!drag || drag.pointerId !== event.pointerId || !drag.moved) {+ return;+ }+ const from = Math.min(drag.origin, drag.current);+ const to = Math.max(drag.origin, drag.current);+ onViewChange(+ clampWindow(+ { start: model.start + from * span, end: model.start + to * span },+ { start: model.start, end: model.end },+ minimumSpan(model),+ ),+ );+ };++ const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {+ if (event.key === '+' || event.key === '=') {+ event.preventDefault();+ onViewChange(zoomWindow(model, view, ZOOM_STEP));+ } else if (event.key === '-' || event.key === '_') {+ event.preventDefault();+ onViewChange(zoomWindow(model, view, 1 / ZOOM_STEP));+ } else if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {+ event.preventDefault();+ onViewChange(panWindow(model, view, event.key === 'ArrowLeft' ? -1 : 1));+ } else if (event.key === 'Escape' && view != null) {+ event.preventDefault();+ event.stopPropagation();+ onViewChange(null);+ }+ };++ const selection =+ draft ?? (view ? { from: toFraction(view.start), to: toFraction(view.end) } : null);++ return (+ <div className="flex flex-col gap-1">+ <div+ ref={surfaceRef}+ role="group"+ tabIndex={0}+ aria-label={localize('com_ui_trace_overview')}+ aria-describedby={hintId}+ data-testid="trace-overview"+ onKeyDown={handleKeyDown}+ onPointerDown={handlePointerDown}+ onPointerMove={handlePointerMove}+ onPointerUp={finishDrag}+ onPointerCancel={finishDrag}+ onDoubleClick={() => onViewChange(null)}+ onContextMenu={(event) => {+ if (view != null) {+ event.preventDefault();+ onViewChange(null);+ }+ }}+ className="relative h-[60px] cursor-crosshair touch-none select-none overflow-hidden rounded-lg border border-border-light bg-surface-primary-alt focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary"+ >+ <svg className="absolute inset-0 h-full w-full" aria-hidden="true">+ {model.turns.map((turn) => (+ <rect+ key={turn.key}+ x={percent(toFraction(turn.start))}+ y={0}+ width={1}+ height="100%"+ className="fill-border-medium"+ />+ ))}+ {records.map((node) => {+ const { record } = node;+ const lane = lanes.get(record.id) ?? 0;+ const y = TOP_PADDING + lane * (LANE_HEIGHT + LANE_GAP);+ const fill =+ record.status === 'error' ? 'fill-status-error' : KIND_APPEARANCE[record.kind].fill;+ if (node.end == null) {+ return (+ <rect+ key={record.id}+ x={percent(toFraction(node.start))}+ y={y - 1}+ width={3}+ height={LANE_HEIGHT + 2}+ className={fill}+ />+ );+ }+ return (+ <rect+ key={record.id}+ x={percent(toFraction(node.start))}+ y={y}+ width={`${Math.max(((node.end - node.start) / span) * 100, 0.15)}%`}+ height={LANE_HEIGHT}+ rx={1}+ className={fill}+ />+ );+ })}+ </svg>+ {selection && (+ <>+ <div+ className="pointer-events-none absolute inset-y-0 left-0 bg-presentation/60"+ style={{ width: percent(selection.from) }}+ />+ <div+ className="pointer-events-none absolute inset-y-0 right-0 bg-presentation/60"+ style={{ width: percent(1 - selection.to) }}+ />+ <div+ data-testid="trace-overview-selection"+ className={cn(+ 'pointer-events-none absolute inset-y-0 border-x-2 border-border-xheavy',+ draft != null && 'border-dashed',+ )}+ style={{+ left: percent(selection.from),+ width: percent(selection.to - selection.from),+ }}+ />+ </>+ )}+ </div>+ <div+ className="flex justify-between text-[11px] tabular-nums text-text-secondary"+ aria-hidden="true"+ >+ {TICKS.map((tick) => (+ <span key={tick}>{format.duration(span * tick)}</span>+ ))}+ </div>+ <p id={hintId} className="sr-only">+ {localize('com_ui_trace_overview_hint')}+ </p>+ </div>+ );+}++export default memo(Timeline);diff --git a/client/src/components/Chat/Trace/Viewer.tsx b/client/src/components/Chat/Trace/Viewer.tsxnew file mode 100644index 0000000000..cd7cfc64b0--- /dev/null+++ b/client/src/components/Chat/Trace/Viewer.tsx@@ -0,0 +1,456 @@+import { useId, useRef, useMemo, useState, useEffect, useCallback, useDeferredValue } from 'react';+import axios from 'axios';+import { useQueryClient } from '@tanstack/react-query';+import { QueryKeys, resolveTraceViewerConfig } from 'librechat-data-provider';+import { Button, Spinner, EmptyState, FilterInput, buttonVariants } from '@librechat/client';+import {+ X,+ ZoomIn,+ ZoomOut,+ RefreshCw,+ ExternalLink,+ ChevronsUpDown,+ ChevronsDownUp,+ TriangleAlert,+ ChartNoAxesGantt,+} from 'lucide-react';+import type { TTraceRecord, TTraceErrorCode, TTraceErrorResponse } from 'librechat-data-provider';+import type { KeyboardEvent } from 'react';+import type { TranslationKeys } from '~/hooks';+import type { TraceWindow } from './model';+import {+ keepNewestTracePage,+ useGetStartupConfig,+ useGetLangfuseSessionLinkQuery,+ useConversationTraceRecordsQuery,+} from '~/data-provider';+import {+ ZOOM_STEP,+ fitWindow,+ zoomWindow,+ flattenRows,+ buildTraceModel,+ collapsibleKeys,+} from './model';+import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';+import { useTraceFormat } from './format';+import { useLocalize } from '~/hooks';+import Inspector from './Inspector';+import Timeline from './Timeline';+import Summary from './Summary';+import Ledger from './Ledger';+import { cn } from '~/utils';++const ERROR_MESSAGES: Partial<Record<TTraceErrorCode, TranslationKeys>> = {+ invalid_request: 'com_ui_trace_error_changed',+ not_found: 'com_ui_trace_error_not_found',+ rate_limited: 'com_ui_trace_error_rate_limited',+ timeout: 'com_ui_trace_error_timeout',+ unauthorized: 'com_ui_trace_error_unauthorized',+ unsupported: 'com_ui_trace_error_unsupported',+};++function errorCodeOf(error: unknown): TTraceErrorCode | undefined {+ return axios.isAxiosError<TTraceErrorResponse>(error)+ ? error.response?.data?.errorCode+ : undefined;+}++function errorMessageKey(error: unknown): TranslationKeys {+ const code = errorCodeOf(error);+ return (code != null ? ERROR_MESSAGES[code] : undefined) ?? 'com_ui_trace_error_generic';+}++/**+ * The conversation trace: a summary, a pinned overview of every loaded record,+ * the record ledger and an inspector. It covers the chat surface and returns+ * focus to whatever opened it when it closes.+ */+export default function Viewer({+ conversationId,+ onClose,+}: {+ conversationId: string;+ onClose: () => void;+}) {+ const localize = useLocalize();+ const queryClient = useQueryClient();+ const format = useTraceFormat();+ const headingId = useId();+ const searchId = useId();+ const closeRef = useRef<HTMLButtonElement>(null);+ const treeRef = useRef<HTMLDivElement>(null);+ const { data: startupConfig } = useGetStartupConfig();+ const settings = resolveTraceViewerConfig(startupConfig?.interface?.traceViewer);+ const showCost = startupConfig?.interface?.contextCost === true;+ const currency = startupConfig?.interface?.currency;++ const recordsQuery = useConversationTraceRecordsQuery(conversationId, true);+ const { data: langfuseSession } = useGetLangfuseSessionLinkQuery(+ conversationId,+ startupConfig?.langfuseConnectionAccess === true,+ );++ const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set());+ const [query, setQuery] = useState('');+ const [view, setView] = useState<TraceWindow | null>(null);+ const [selectedId, setSelectedId] = useState<string | null>(null);+ const [lastRead, setLastRead] = useState<'refresh' | 'older'>('refresh');+ const labelsFor = useCallback(+ (record: TTraceRecord) => [+ localize(KIND_APPEARANCE[record.kind].label),+ localize(STATUS_LABEL[record.status]),+ ],+ [localize],+ );+ /** Rereads only the newest page; older pages cannot change and reload on demand. */+ const refresh = useCallback(() => {+ setLastRead('refresh');+ keepNewestTracePage(queryClient, conversationId);+ recordsQuery.refetch();+ /** An open record may have finished or finished ingesting since its detail loaded. */+ queryClient.invalidateQueries([QueryKeys.conversationTraceRecord, conversationId]);+ }, [queryClient, conversationId, recordsQuery]);+ const loadOlder = useCallback(() => {+ setLastRead('older');+ recordsQuery.fetchNextPage();+ }, [recordsQuery]);+ const deferredQuery = useDeferredValue(query);++ const pages = recordsQuery.data?.pages;+ const records = useMemo(() => pages?.flatMap((page) => page.records) ?? [], [pages]);+ const recordSources = useMemo(() => {+ const sources = new Map<string, string>();+ for (const page of pages ?? []) {+ for (const record of page.records) {+ if (page.sourceId != null) {+ sources.set(record.id, page.sourceId);+ }+ }+ }+ return sources;+ }, [pages]);+ /** The session link opens one project; offer it only when that project served every loaded page. */+ const langfuseUrl =+ langfuseSession?.url != null &&+ langfuseSession.destinationId != null &&+ pages != null &&+ pages.length > 0 &&+ pages.every((page) => page.sourceId === langfuseSession.destinationId)+ ? langfuseSession.url+ : undefined;+ const model = useMemo(() => buildTraceModel(records), [records]);+ const rows = useMemo(+ () => flattenRows(model, { collapsed, query: deferredQuery, window: view, labelsFor }),+ [model, collapsed, deferredQuery, view, labelsFor],+ );+ /** A refresh or a settled run trims the cache to its newest page. An interval or a selection+ * on records that left with the older pages would hide every row, or reopen when they reload. */+ useEffect(() => {+ setSelectedId((id) => (id != null && !model.nodes.has(id) ? null : id));+ setView((current) => (current != null ? fitWindow(current, model) : current));+ }, [model]);+ const selectedNode = selectedId != null ? model.nodes.get(selectedId) : undefined;+ const selectedTurnStart =+ model.turns.find((turn) => turn.messageId === selectedNode?.record.messageId)?.start ??+ model.start;++ useEffect(() => {+ const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;+ closeRef.current?.focus();+ return () => {+ /** Only reclaim focus the trace took with it; a close caused by navigating+ * elsewhere leaves focus wherever that navigation put it. */+ const active = document.activeElement;+ if (active != null && active !== document.body) {+ return;+ }+ const target = opener?.isConnected ? opener : document.getElementById('header-menu-button');+ target?.focus();+ };+ }, []);++ const toggle = useCallback((key: string) => {+ setCollapsed((current) => {+ const next = new Set(current);+ if (next.has(key)) {+ next.delete(key);+ } else {+ next.add(key);+ }+ return next;+ });+ }, []);++ const closeInspector = useCallback(() => {+ setSelectedId(null);+ /** A filter that matches nothing unmounts the tree; the search field is what is left to return to. */+ (treeRef.current ?? document.getElementById(searchId))?.focus();+ }, [searchId]);++ const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {+ if (event.key !== 'Escape' || event.defaultPrevented) {+ return;+ }+ event.preventDefault();+ if (selectedId != null) {+ closeInspector();+ return;+ }+ onClose();+ };++ const refreshButton = (+ <Button+ size="icon-sm"+ variant="outline"+ aria-label={localize('com_ui_trace_refresh')}+ disabled={recordsQuery.isFetching}+ onClick={refresh}+ >+ <RefreshCw+ aria-hidden="true"+ className={cn(+ 'size-4',+ recordsQuery.isFetching && 'animate-spin motion-reduce:animate-none',+ )}+ />+ </Button>+ );++ const renderBody = () => {+ if (recordsQuery.isLoading) {+ return (+ <div role="status" className="flex flex-1 items-center justify-center gap-2">+ <Spinner className="size-5 text-text-secondary" />+ <span className="sr-only">{localize('com_ui_trace_loading')}</span>+ </div>+ );+ }++ if (recordsQuery.isError && recordsQuery.data == null) {+ return (+ <div className="flex flex-1 items-center justify-center p-4">+ <EmptyState+ icon={TriangleAlert}+ title={localize('com_ui_trace_error_title')}+ description={localize(errorMessageKey(recordsQuery.error))}+ action={+ <Button size="sm" variant="outline" onClick={refresh}>+ {localize('com_ui_retry')}+ </Button>+ }+ />+ </div>+ );+ }++ if (model.nodes.size === 0 && recordsQuery.hasNextPage !== true) {+ return (+ <div className="flex flex-1 items-center justify-center p-4">+ <EmptyState+ icon={ChartNoAxesGantt}+ title={localize('com_ui_trace_empty_title')}+ description={localize('com_ui_trace_empty_description')}+ action={+ <Button size="sm" variant="outline" onClick={refresh}>+ {localize('com_ui_trace_refresh')}+ </Button>+ }+ />+ </div>+ );+ }++ /** A refresh or an older page failed while earlier results stay on screen. */+ const cachedReadFailed = recordsQuery.isError && recordsQuery.data != null;+ return (+ <>+ <div className="flex flex-col gap-3 border-b border-border-light px-3 py-3 md:px-4">+ <div className="flex flex-wrap items-center justify-between gap-2">+ <Summary summary={model.summary} showCost={showCost} currency={currency} />+ {recordsQuery.hasNextPage === true && (+ <p className="text-xs text-text-secondary">+ {localize('com_ui_trace_partial', { 0: String(records.length) })}+ </p>+ )}+ </div>+ <Timeline model={model} view={view} onViewChange={setView} />+ <div className="flex flex-wrap items-center gap-2">+ <FilterInput+ inputId={searchId}+ label={localize('com_ui_trace_search')}+ value={query}+ onChange={(event) => setQuery(event.target.value)}+ onKeyDown={(event) => {+ if (event.key === 'Escape' && query !== '') {+ event.preventDefault();+ setQuery('');+ }+ }}+ containerClassName="min-w-[10rem] flex-1 md:max-w-xs"+ />+ <Button+ size="sm"+ variant="outline"+ aria-label={localize('com_ui_trace_expand_all')}+ onClick={() => setCollapsed(new Set())}+ disabled={collapsed.size === 0}+ >+ <ChevronsUpDown className="size-4" aria-hidden="true" />+ <span className="hidden sm:inline">{localize('com_ui_trace_expand_all')}</span>+ </Button>+ <Button+ size="sm"+ variant="outline"+ aria-label={localize('com_ui_trace_collapse_all')}+ onClick={() => setCollapsed(new Set(collapsibleKeys(model)))}+ >+ <ChevronsDownUp className="size-4" aria-hidden="true" />+ <span className="hidden sm:inline">{localize('com_ui_trace_collapse_all')}</span>+ </Button>+ <div className="ml-auto flex items-center gap-1">+ {view != null && (+ <span className="text-xs tabular-nums text-text-secondary" aria-live="polite">+ {localize('com_ui_trace_selection', {+ 0: format.duration(view.start - model.start),+ 1: format.duration(view.end - model.start),+ })}+ </span>+ )}+ <Button+ size="icon-sm"+ variant="ghost"+ aria-label={localize('com_ui_zoom_out')}+ disabled={view == null}+ onClick={() => setView(zoomWindow(model, view, 1 / ZOOM_STEP))}+ >+ <ZoomOut className="size-4" aria-hidden="true" />+ </Button>+ <Button+ size="icon-sm"+ variant="ghost"+ aria-label={localize('com_ui_zoom_in')}+ onClick={() => setView(zoomWindow(model, view, ZOOM_STEP))}+ >+ <ZoomIn className="size-4" aria-hidden="true" />+ </Button>+ {view != null && (+ <Button size="sm" variant="ghost" onClick={() => setView(null)}>+ {localize('com_ui_trace_clear_selection')}+ </Button>+ )}+ </div>+ </div>+ </div>+ <div className="relative flex min-h-0 flex-1">+ <div className="flex min-h-0 min-w-0 flex-1 flex-col">+ {rows.length === 0 ? (+ <p role="status" className="p-4 text-sm text-text-secondary">+ {localize('com_ui_trace_no_matches')}+ </p>+ ) : (+ <Ledger+ rows={rows}+ model={model}+ view={view}+ selectedId={selectedId}+ treeRef={treeRef}+ onSelect={setSelectedId}+ onToggle={toggle}+ />+ )}+ {(recordsQuery.hasNextPage === true || cachedReadFailed) && (+ <div className="flex flex-wrap items-center justify-center gap-2 border-t border-border-light p-2">+ {cachedReadFailed && (+ <>+ <span role="alert" className="text-xs text-status-error">+ {localize(errorMessageKey(recordsQuery.error))}+ </span>+ <Button+ size="sm"+ variant="outline"+ disabled={recordsQuery.isFetching}+ onClick={+ /** A continuation the trace no longer matches can only be reloaded from the newest page. */+ lastRead === 'older' &&+ errorCodeOf(recordsQuery.error) !== 'invalid_request'+ ? loadOlder+ : refresh+ }+ >+ {localize('com_ui_retry')}+ </Button>+ </>+ )}+ {recordsQuery.hasNextPage === true && (+ <Button+ size="sm"+ variant="outline"+ disabled={recordsQuery.isFetchingNextPage}+ onClick={loadOlder}+ >+ {recordsQuery.isFetchingNextPage && <Spinner className="size-3.5" />}+ {localize('com_ui_trace_load_older')}+ </Button>+ )}+ </div>+ )}+ </div>+ {selectedNode && (+ <Inspector+ node={selectedNode}+ turnStart={selectedTurnStart}+ sourceId={recordSources.get(selectedNode.record.id)}+ conversationId={conversationId}+ showContent={settings.showInputOutput}+ showCost={showCost}+ currency={currency}+ onClose={closeInspector}+ />+ )}+ </div>+ </>+ );+ };++ return (+ <section+ aria-labelledby={headingId}+ data-testid="trace-viewer"+ onKeyDown={handleKeyDown}+ className="absolute inset-0 z-20 flex flex-col bg-presentation text-text-primary"+ >+ <div className="flex h-[52px] shrink-0 items-center gap-2 border-b border-border-light px-2 md:px-4">+ <h2 id={headingId} className="text-base font-semibold">+ {localize('com_ui_trace_title')}+ </h2>+ <div className="ml-auto flex items-center gap-2">+ {langfuseUrl != null && (+ <a+ href={langfuseUrl}+ target="_blank"+ rel="noopener noreferrer"+ className={buttonVariants({ variant: 'outline', size: 'sm' })}+ >+ <ExternalLink className="size-4" aria-hidden="true" />+ <span className="hidden sm:inline">{localize('com_ui_trace_open_langfuse')}</span>+ <span className="sr-only sm:hidden">{localize('com_ui_trace_open_langfuse')}</span>+ </a>+ )}+ {refreshButton}+ <Button+ ref={closeRef}+ size="icon-sm"+ variant="outline"+ aria-label={localize('com_ui_trace_close')}+ onClick={onClose}+ >+ <X className="size-4" aria-hidden="true" />+ </Button>+ </div>+ </div>+ {renderBody()}+ </section>+ );+}diff --git a/client/src/components/Chat/Trace/__tests__/Surface.test.tsx b/client/src/components/Chat/Trace/__tests__/Surface.test.tsxnew file mode 100644index 0000000000..3bd9c3f195--- /dev/null+++ b/client/src/components/Chat/Trace/__tests__/Surface.test.tsx@@ -0,0 +1,265 @@+import React, { useEffect, useState } from 'react';+import userEvent from '@testing-library/user-event';+import { QueryKeys, dataService } from 'librechat-data-provider';+import { render, screen, waitFor } from '@testing-library/react';+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import type { TStartupConfig, TTraceViewerConfig } from 'librechat-data-provider';+import { IsolatedAtomStore } from 'test/harness';+import useTraceControl from '../useTraceControl';+import TraceSurface from '../Surface';+import TraceButton from '../Button';++jest.mock('librechat-data-provider', () => {+ const actual =+ jest.requireActual<typeof import('librechat-data-provider')>('librechat-data-provider');+ return { ...actual, dataService: { ...actual.dataService } };+});++type MockStartupConfig = Omit<Partial<TStartupConfig>, 'interface'> & {+ interface?: Partial<NonNullable<TStartupConfig['interface']>>;+};++let mockStartupConfig: MockStartupConfig = {};++jest.mock('~/data-provider/Endpoints/queries', () => ({+ useGetStartupConfig: () => ({ data: mockStartupConfig }),+}));++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+}));++jest.mock('@librechat/client', () => {+ const actual = jest.requireActual('@librechat/client');+ return {+ ...actual,+ TooltipAnchor: ({ render: node }: { render: React.ReactNode }) => node,+ };+});++const mounts = { count: 0 };++function Chat() {+ const [draft, setDraft] = useState('');+ useEffect(() => {+ mounts.count++;+ }, []);+ return <input aria-label="composer" value={draft} onChange={(e) => setDraft(e.target.value)} />;+}++function Host({+ conversationId,+ traceViewer = { enabled: true },+ isSubmitting = false,+ enabled = true,+}: {+ conversationId: string;+ traceViewer?: TTraceViewerConfig;+ isSubmitting?: boolean;+ enabled?: boolean;+}) {+ const trace = useTraceControl({ conversationId, traceViewer, isSubmitting, enabled });+ return (+ <TraceSurface conversationId={conversationId}>+ <div data-testid="chat-pane">+ {trace.show && <TraceButton onClick={trace.open} />}+ <Chat />+ </div>+ </TraceSurface>+ );+}++function renderHost(props: React.ComponentProps<typeof Host>) {+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ logger: { log: () => undefined, warn: () => undefined, error: () => undefined },+ });+ const wrap = (next: React.ComponentProps<typeof Host>) => (+ <QueryClientProvider client={client}>+ <IsolatedAtomStore>+ <Host {...next} />+ </IsolatedAtomStore>+ </QueryClientProvider>+ );+ const utils = render(wrap(props));+ return {+ ...utils,+ client,+ rerenderHost: (next: React.ComponentProps<typeof Host>) => utils.rerender(wrap(next)),+ };+}++const traceButton = () => screen.queryByTestId('header-trace-button');+const chatPane = () => screen.getByTestId('chat-pane').parentElement as HTMLElement;++describe('trace entry point and surface', () => {+ let availability: jest.SpiedFunction<typeof dataService.getConversationTraceAvailability>;++ beforeEach(() => {+ mounts.count = 0;+ mockStartupConfig = { interface: { traceViewer: { enabled: true } } };+ availability = jest+ .spyOn(dataService, 'getConversationTraceAvailability')+ .mockResolvedValue({ available: true });+ jest.spyOn(dataService, 'getConversationTraceRecords').mockResolvedValue({ records: [] });+ });++ it('shows the control only for an available trace on an enabled deployment', async () => {+ renderHost({ conversationId: 'convo-1' });++ expect(await screen.findByTestId('header-trace-button')).toBeInTheDocument();+ expect(availability).toHaveBeenCalledWith('convo-1');+ });++ it.each([+ ['the viewer is disabled', { conversationId: 'convo-1', traceViewer: { enabled: false } }],+ ['the chat is new', { conversationId: 'new' }],+ ['the host opts out', { conversationId: 'convo-1', enabled: false }],+ ])('never asks for availability when %s', async (_label, props) => {+ renderHost(props);++ await waitFor(() => expect(traceButton()).not.toBeInTheDocument());+ expect(availability).not.toHaveBeenCalled();+ });++ it('hides the control for a conversation with no sampled trace', async () => {+ availability.mockResolvedValue({ available: false });+ renderHost({ conversationId: 'convo-1' });++ await waitFor(() => expect(availability).toHaveBeenCalled());+ expect(traceButton()).not.toBeInTheDocument();+ });++ it('re-reads availability once a running response settles', async () => {+ availability.mockResolvedValue({ available: false });+ const { rerenderHost } = renderHost({ conversationId: 'convo-1' });+ await waitFor(() => expect(availability).toHaveBeenCalledTimes(1));++ rerenderHost({ conversationId: 'convo-1', isSubmitting: true });+ availability.mockResolvedValue({ available: true });+ expect(availability).toHaveBeenCalledTimes(1);++ rerenderHost({ conversationId: 'convo-1', isSubmitting: false });++ expect(await screen.findByTestId('header-trace-button')).toBeInTheDocument();+ expect(availability).toHaveBeenCalledTimes(2);+ });++ it('reads the trace again after a response settles instead of reusing cached pages', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValue({ records: [] });+ const { rerenderHost } = renderHost({ conversationId: 'convo-1' });+ const close = () => userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_close' }));++ await userEvent.click(await screen.findByTestId('header-trace-button'));+ await waitFor(() => expect(list).toHaveBeenCalledTimes(1));+ await close();+ await userEvent.click(screen.getByTestId('header-trace-button'));+ await close();+ expect(list).toHaveBeenCalledTimes(1);++ rerenderHost({ conversationId: 'convo-1', isSubmitting: true });+ rerenderHost({ conversationId: 'convo-1', isSubmitting: false });+ await userEvent.click(await screen.findByTestId('header-trace-button'));++ await waitFor(() => expect(list).toHaveBeenCalledTimes(2));+ });++ it('marks cached record details stale too when a response settles', async () => {+ const { rerenderHost, client } = renderHost({ conversationId: 'convo-1' });+ const detailKey = [QueryKeys.conversationTraceRecord, 'convo-1', 'obs-1', null];+ client.setQueryData(detailKey, { record: {}, contentAvailable: true });++ rerenderHost({ conversationId: 'convo-1', isSubmitting: true });+ rerenderHost({ conversationId: 'convo-1', isSubmitting: false });++ await waitFor(() => expect(client.getQueryState(detailKey)?.isInvalidated).toBe(true));+ });++ it('retries a transient availability failure instead of hiding the control for good', async () => {+ availability+ .mockRejectedValueOnce(+ Object.assign(new Error('unavailable'), {+ isAxiosError: true,+ response: { status: 503 },+ }),+ )+ .mockResolvedValue({ available: true });+ const client = new QueryClient({+ defaultOptions: { queries: { retryDelay: 1 } },+ logger: { log: () => undefined, warn: () => undefined, error: () => undefined },+ });+ render(+ <QueryClientProvider client={client}>+ <IsolatedAtomStore>+ <Host conversationId="convo-1" />+ </IsolatedAtomStore>+ </QueryClientProvider>,+ );++ expect(await screen.findByTestId('header-trace-button')).toBeInTheDocument();+ expect(availability).toHaveBeenCalledTimes(2);+ });++ it('checks availability again when the server cannot decide yet', async () => {+ availability+ .mockResolvedValueOnce({ available: false, retryAfterMs: 20 })+ .mockResolvedValue({ available: true });+ renderHost({ conversationId: 'convo-1' });++ expect(await screen.findByTestId('header-trace-button')).toBeInTheDocument();+ expect(availability).toHaveBeenCalledTimes(2);+ });++ it('covers the chat without unmounting it and restores it with focus on close', async () => {+ renderHost({ conversationId: 'convo-1' });+ await userEvent.type(screen.getByLabelText('composer'), 'unsent draft');+ const button = await screen.findByTestId('header-trace-button');++ await userEvent.click(button);++ expect(await screen.findByTestId('trace-viewer')).toBeInTheDocument();+ expect(chatPane()).toHaveAttribute('inert');+ expect(chatPane()).toHaveClass('isolate');+ expect(screen.getByRole('button', { name: 'com_ui_trace_close' })).toHaveFocus();++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_close' }));++ expect(screen.queryByTestId('trace-viewer')).not.toBeInTheDocument();+ expect(chatPane()).not.toHaveAttribute('inert');+ expect(screen.getByLabelText('composer')).toHaveValue('unsent draft');+ expect(mounts.count).toBe(1);+ expect(screen.getByTestId('header-trace-button')).toHaveFocus();+ });++ it('leaves focus where a navigation put it when that navigation closes the trace', async () => {+ const outside = document.createElement('button');+ outside.textContent = 'sidebar link';+ document.body.appendChild(outside);+ const { rerenderHost, client } = renderHost({ conversationId: 'convo-1' });+ /** The next chat also has a trace, so the opener stays mounted and could steal focus back. */+ client.setQueryData([QueryKeys.conversationTraceAvailability, 'convo-2'], { available: true });+ await userEvent.click(await screen.findByTestId('header-trace-button'));+ expect(await screen.findByTestId('trace-viewer')).toBeInTheDocument();++ outside.focus();+ rerenderHost({ conversationId: 'convo-2' });++ expect(screen.queryByTestId('trace-viewer')).not.toBeInTheDocument();+ expect(outside).toHaveFocus();+ outside.remove();+ });++ it('does not carry an open trace into another conversation', async () => {+ const { rerenderHost } = renderHost({ conversationId: 'convo-1' });+ await userEvent.click(await screen.findByTestId('header-trace-button'));+ expect(await screen.findByTestId('trace-viewer')).toBeInTheDocument();++ rerenderHost({ conversationId: 'convo-2' });+ expect(screen.queryByTestId('trace-viewer')).not.toBeInTheDocument();++ rerenderHost({ conversationId: 'convo-1' });+ expect(screen.queryByTestId('trace-viewer')).not.toBeInTheDocument();+ });+});diff --git a/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsxnew file mode 100644index 0000000000..2c1f6ea72e--- /dev/null+++ b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx@@ -0,0 +1,632 @@+import React from 'react';+import userEvent from '@testing-library/user-event';+import { dataService } from 'librechat-data-provider';+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import { act, render, screen, waitFor, within, fireEvent } from '@testing-library/react';+import type { TTracePage, TTraceRecord, TStartupConfig } from 'librechat-data-provider';+import { keepNewestTracePage } from '~/data-provider/Traces/queries';+import Viewer from '../Viewer';++jest.mock('librechat-data-provider', () => {+ const actual =+ jest.requireActual<typeof import('librechat-data-provider')>('librechat-data-provider');+ return { ...actual, dataService: { ...actual.dataService } };+});++type MockStartupConfig = Omit<Partial<TStartupConfig>, 'interface'> & {+ interface?: Partial<NonNullable<TStartupConfig['interface']>>;+};++let mockStartupConfig: MockStartupConfig = {};++jest.mock('~/data-provider/Endpoints/queries', () => ({+ useGetStartupConfig: () => ({ data: mockStartupConfig }),+}));++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string, options?: Record<string, string>) =>+ options ? `${key} ${Object.values(options).join(' ')}` : key,+}));++const BASE = Date.UTC(2026, 8, 12, 11, 30, 0);+const at = (offsetMs: number) => new Date(BASE + offsetMs).toISOString();++function record(overrides: Partial<TTraceRecord> & Pick<TTraceRecord, 'id'>): TTraceRecord {+ return {+ traceId: 'trace-1',+ messageId: 'response-1',+ parentId: null,+ kind: 'span',+ name: overrides.id,+ startTime: at(0),+ endTime: at(1000),+ status: 'ok',+ ...overrides,+ };+}++const records: TTraceRecord[] = [+ record({ id: 'root', kind: 'agent', name: 'AgentGraph', startTime: at(0), endTime: at(4000) }),+ record({+ id: 'llm',+ parentId: 'root',+ kind: 'generation',+ name: 'llm',+ model: 'gpt-5',+ startTime: at(100),+ endTime: at(2100),+ completionStartTime: at(600),+ usage: { input: 1200, output: 300, total: 1500 },+ cost: 0.02,+ }),+ record({+ id: 'tool',+ parentId: 'root',+ kind: 'tool',+ name: 'web_search',+ status: 'error',+ statusMessage: 'Error: search backend unavailable',+ startTime: at(2200),+ endTime: at(3000),+ }),+];++function axiosError(status: number, errorCode: string) {+ return Object.assign(new Error(errorCode), {+ isAxiosError: true,+ response: { status, data: { error: errorCode, errorCode } },+ });+}++function renderViewer(onClose = jest.fn()) {+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ logger: { log: () => undefined, warn: () => undefined, error: () => undefined },+ });+ const utils = render(+ <QueryClientProvider client={client}>+ <Viewer conversationId="convo-1" onClose={onClose} />+ </QueryClientProvider>,+ );+ return { ...utils, onClose, client };+}++const treeItem = (name: RegExp) => screen.findByRole('treeitem', { name });++describe('Trace Viewer', () => {+ beforeEach(() => {+ mockStartupConfig = { interface: { traceViewer: { enabled: true } } };+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValue({ records, sourceId: 'tenant-project' } satisfies TTracePage);+ jest.spyOn(dataService, 'getConversationTraceRecord').mockResolvedValue({+ record: records[1],+ contentAvailable: true,+ input: { value: '{"messages":[{"role":"user","content":"hi"}]}', truncated: false },+ output: { value: 'partial outp', truncated: true },+ });+ jest.spyOn(dataService, 'getLangfuseSessionLink').mockResolvedValue({+ url: 'https://langfuse.test/project/p/sessions/convo-1',+ destinationId: 'tenant-project',+ });+ });++ it('shows a loading state, then the summary, overview and record tree', async () => {+ renderViewer();++ expect(screen.getByRole('status')).toHaveTextContent('com_ui_trace_loading');+ expect(await treeItem(/AgentGraph/)).toBeInTheDocument();+ expect(screen.getByRole('treeitem', { name: /llm/ })).toHaveAttribute('aria-level', '3');+ expect(+ screen.getByRole('treeitem', { name: /web_search.*com_ui_trace_status_error/ }),+ ).toBeInTheDocument();+ expect(screen.getByRole('treeitem', { name: /^com_ui_trace_turn/ })).toHaveAttribute(+ 'aria-level',+ '1',+ );++ const summary = screen.getByLabelText('com_ui_trace_summary');+ expect(+ within(summary).getByText('com_ui_trace_summary_generations').nextSibling,+ ).toHaveTextContent('1');+ expect(within(summary).getByText('com_ui_trace_summary_errors').nextSibling).toHaveTextContent(+ '1',+ );+ expect(within(summary).queryByText('com_ui_trace_summary_cost')).not.toBeInTheDocument();+ expect(screen.getByTestId('trace-overview')).toBeInTheDocument();+ expect(dataService.getConversationTraceRecords).toHaveBeenCalledWith(+ { conversationId: 'convo-1', cursor: undefined },+ expect.any(AbortSignal),+ );+ });++ it('shows cost only when the deployment shows context cost', async () => {+ mockStartupConfig = { interface: { traceViewer: { enabled: true }, contextCost: true } };+ renderViewer();++ await treeItem(/AgentGraph/);+ expect(screen.getByText('com_ui_trace_summary_cost')).toBeInTheDocument();+ });++ it('explains a failure by its error code and recovers on retry', async () => {+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockRejectedValueOnce(axiosError(501, 'unsupported'));+ renderViewer();++ expect(await screen.findByText('com_ui_trace_error_unsupported')).toBeInTheDocument();+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));++ expect(await treeItem(/AgentGraph/)).toBeInTheDocument();+ });++ it('falls back to a generic message for an unknown failure', async () => {+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockRejectedValueOnce(new Error('network down'));+ renderViewer();++ expect(await screen.findByText('com_ui_trace_error_generic')).toBeInTheDocument();+ });++ it('shows an empty state that can refresh when no records have arrived yet', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValueOnce({ records: [] });+ renderViewer();++ const title = await screen.findByText('com_ui_trace_empty_title');+ const emptyState = title.parentElement as HTMLElement;+ await userEvent.click(within(emptyState).getByRole('button', { name: 'com_ui_trace_refresh' }));++ expect(await treeItem(/AgentGraph/)).toBeInTheDocument();+ expect(list).toHaveBeenCalledTimes(2);+ });++ it('inspects a record without requesting content the deployment withholds', async () => {+ renderViewer();++ await userEvent.click(await treeItem(/llm/));++ const inspector = screen.getByTestId('trace-inspector');+ expect(within(inspector).getByRole('heading', { name: 'llm' })).toBeInTheDocument();+ expect(within(inspector).getByText('com_ui_trace_ttft')).toBeInTheDocument();+ expect(within(inspector).getByText('com_ui_trace_decoding')).toBeInTheDocument();+ expect(within(inspector).getByText('gpt-5')).toBeInTheDocument();+ expect(within(inspector).queryByText('com_ui_trace_content')).not.toBeInTheDocument();+ expect(screen.getByRole('treeitem', { name: /llm/ })).toHaveAttribute('aria-selected', 'true');+ expect(dataService.getConversationTraceRecord).not.toHaveBeenCalled();+ });++ it('loads input and output for the selected record when the deployment allows it', async () => {+ mockStartupConfig = { interface: { traceViewer: { enabled: true, showInputOutput: true } } };+ renderViewer();++ await userEvent.click(await treeItem(/llm/));++ const inspector = screen.getByTestId('trace-inspector');+ expect(await within(inspector).findByText(/"content": "hi"/)).toBeInTheDocument();+ expect(within(inspector).getByText('partial outp')).toBeInTheDocument();+ expect(within(inspector).getByText('com_ui_trace_truncated')).toBeInTheDocument();+ expect(dataService.getConversationTraceRecord).toHaveBeenCalledWith(+ {+ conversationId: 'convo-1',+ recordId: 'llm',+ messageId: 'response-1',+ sourceId: 'tenant-project',+ },+ expect.any(AbortSignal),+ );+ });++ it('shows the error message for a failed record', async () => {+ renderViewer();++ await userEvent.click(await treeItem(/web_search/));++ expect(+ within(screen.getByTestId('trace-inspector')).getByText('Error: search backend unavailable'),+ ).toBeInTheDocument();+ });++ it('does not call a failed record with no end time running', async () => {+ jest.spyOn(dataService, 'getConversationTraceRecords').mockResolvedValue({+ records: [+ record({+ id: 'broken',+ name: 'broken_tool',+ kind: 'tool',+ status: 'error',+ endTime: undefined,+ }),+ ],+ });+ renderViewer();++ const row = await treeItem(/broken_tool/);++ expect(row).not.toHaveAccessibleName(/com_ui_trace_status_running/);+ expect(row).toHaveAccessibleName(/com_ui_trace_status_error/);+ await userEvent.click(row);+ const inspector = screen.getByTestId('trace-inspector');+ expect(within(inspector).queryByText('com_ui_trace_status_running')).not.toBeInTheDocument();+ expect(within(inspector).getByText('—')).toBeInTheDocument();+ });++ it('filters the tree by search and keeps the match context', async () => {+ renderViewer();+ await treeItem(/AgentGraph/);++ await userEvent.type(screen.getByLabelText('com_ui_trace_search'), 'web');++ await waitFor(() =>+ expect(screen.queryByRole('treeitem', { name: /llm/ })).not.toBeInTheDocument(),+ );+ expect(screen.getByRole('treeitem', { name: /AgentGraph/ })).toBeInTheDocument();+ expect(screen.getByRole('treeitem', { name: /web_search/ })).toBeInTheDocument();++ await userEvent.clear(screen.getByLabelText('com_ui_trace_search'));+ await userEvent.type(screen.getByLabelText('com_ui_trace_search'), 'nothing matches');+ expect(await screen.findByText('com_ui_trace_no_matches')).toBeInTheDocument();+ });++ it('folds and unfolds rows from the keyboard', async () => {+ renderViewer();+ const root = await treeItem(/AgentGraph/);+ const tree = screen.getByRole('tree');++ await userEvent.click(root);+ expect(root).toHaveAttribute('aria-expanded', 'true');+ fireEvent.keyDown(tree, { key: 'ArrowLeft' });++ await waitFor(() =>+ expect(screen.queryByRole('treeitem', { name: /llm/ })).not.toBeInTheDocument(),+ );+ expect(screen.getByRole('treeitem', { name: /AgentGraph/ })).toHaveAttribute(+ 'aria-expanded',+ 'false',+ );++ fireEvent.keyDown(tree, { key: 'ArrowRight' });+ expect(await treeItem(/llm/)).toBeInTheDocument();+ fireEvent.keyDown(tree, { key: 'ArrowDown' });+ expect(tree).toHaveAttribute(+ 'aria-activedescendant',+ screen.getByRole('treeitem', { name: /llm/ }).id,+ );+ fireEvent.keyDown(tree, { key: 'Enter' });+ expect(screen.getByTestId('trace-inspector')).toBeInTheDocument();+ });++ it('keeps the active row mounted while the ledger scrolls away from it', async () => {+ const many = [+ record({+ id: 'root',+ kind: 'agent',+ name: 'AgentGraph',+ startTime: at(0),+ endTime: at(9000),+ }),+ ...Array.from({ length: 150 }, (_, index) =>+ record({+ id: `step-${index}`,+ parentId: 'root',+ name: `step-${index}`,+ startTime: at(index),+ }),+ ),+ ];+ jest.spyOn(dataService, 'getConversationTraceRecords').mockResolvedValue({ records: many });+ renderViewer();+ await treeItem(/AgentGraph/);+ const tree = screen.getByRole('tree');++ fireEvent.focus(tree);+ const activeId = await waitFor(() => {+ const id = tree.getAttribute('aria-activedescendant');+ expect(id).toBeTruthy();+ return id as string;+ });+ tree.scrollTop = 140 * 32;+ fireEvent.scroll(tree);++ expect(await treeItem(/step-140/)).toBeInTheDocument();+ expect(tree.getAttribute('aria-activedescendant')).toBe(activeId);+ expect(document.getElementById(activeId)).toHaveAttribute('role', 'treeitem');+ });++ it('collapses and expands everything', async () => {+ renderViewer();+ await treeItem(/AgentGraph/);++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_collapse_all' }));+ expect(screen.queryByRole('treeitem', { name: /AgentGraph/ })).not.toBeInTheDocument();++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_expand_all' }));+ expect(screen.getByRole('treeitem', { name: /llm/ })).toBeInTheDocument();+ });++ it('focuses an interval from the overview keyboard and clears it', async () => {+ renderViewer();+ await treeItem(/AgentGraph/);+ const overview = screen.getByTestId('trace-overview');++ fireEvent.keyDown(overview, { key: '+' });++ expect(screen.getByTestId('trace-overview-selection')).toBeInTheDocument();+ expect(screen.getByText(/^com_ui_trace_selection/)).toBeInTheDocument();+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_clear_selection' }));+ expect(screen.queryByTestId('trace-overview-selection')).not.toBeInTheDocument();+ });++ it('loads older records on demand and merges them into the tree', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockImplementation(async ({ cursor }) =>+ cursor == null+ ? { records: records.slice(1), nextCursor: 'older' }+ : { records: records.slice(0, 1) },+ );+ renderViewer();++ expect(await screen.findByText('com_ui_trace_partial 2')).toBeInTheDocument();+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));++ await waitFor(() =>+ expect(screen.getByRole('treeitem', { name: /llm/ })).toHaveAttribute('aria-level', '3'),+ );+ expect(list).toHaveBeenLastCalledWith(+ { conversationId: 'convo-1', cursor: 'older' },+ expect.any(AbortSignal),+ );+ expect(+ screen.queryByRole('button', { name: 'com_ui_trace_load_older' }),+ ).not.toBeInTheDocument();+ });++ it('reports a failed refresh while every page is already loaded, with a retry', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValueOnce({ records })+ .mockRejectedValueOnce(axiosError(504, 'timeout'))+ .mockResolvedValue({ records });+ renderViewer();+ await treeItem(/AgentGraph/);++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_refresh' }));++ expect(await screen.findByRole('alert')).toHaveTextContent('com_ui_trace_error_timeout');+ expect(screen.getByRole('treeitem', { name: /AgentGraph/ })).toBeInTheDocument();+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));++ await waitFor(() => expect(screen.queryByRole('alert')).not.toBeInTheDocument());+ expect(list).toHaveBeenCalledTimes(3);+ });++ it('refreshes by rereading only the newest page, not every loaded page', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockImplementation(async ({ cursor }) =>+ cursor == null+ ? { records: records.slice(1), nextCursor: 'older' }+ : { records: records.slice(0, 1) },+ );+ renderViewer();+ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));+ await waitFor(() => expect(list).toHaveBeenCalledTimes(2));++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_refresh' }));++ expect(+ await screen.findByRole('button', { name: 'com_ui_trace_load_older' }),+ ).toBeInTheDocument();+ expect(list).toHaveBeenCalledTimes(3);+ expect(list).toHaveBeenLastCalledWith(+ { conversationId: 'convo-1', cursor: undefined },+ expect.any(AbortSignal),+ );+ });++ it('drops an interval and a selection on older pages when a refresh trims them', async () => {+ const newest = [+ record({+ id: 'later',+ messageId: 'response-2',+ traceId: 'trace-2',+ name: 'LaterGraph',+ kind: 'agent',+ startTime: at(10_000),+ endTime: at(12_000),+ }),+ ];+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockImplementation(async ({ cursor }) =>+ cursor == null ? { records: newest, nextCursor: 'older' } : { records },+ );+ renderViewer();+ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));+ await userEvent.click(await treeItem(/llm/));+ fireEvent.keyDown(screen.getByTestId('trace-overview'), { key: '+' });+ expect(screen.queryByRole('treeitem', { name: /LaterGraph/ })).not.toBeInTheDocument();+ expect(screen.getByTestId('trace-inspector')).toBeInTheDocument();++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_refresh' }));++ expect(await treeItem(/LaterGraph/)).toBeInTheDocument();+ expect(screen.queryByTestId('trace-overview-selection')).not.toBeInTheDocument();+ expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();++ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));++ expect(await treeItem(/llm/)).toBeInTheDocument();+ expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();+ });++ it('keeps a newest-page selection but drops an older one when a settled run trims the cache', async () => {+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockImplementation(async ({ cursor }) =>+ cursor == null+ ? { records: records.slice(1), nextCursor: 'older' }+ : { records: records.slice(0, 1) },+ );+ const { client } = renderViewer();+ const inspectorHeading = () =>+ within(screen.getByTestId('trace-inspector')).getByRole('heading', { level: 3 });++ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));+ await userEvent.click(await treeItem(/web_search/));+ act(() => keepNewestTracePage(client, 'convo-1'));++ expect(await screen.findByRole('button', { name: 'com_ui_trace_load_older' })).toBeVisible();+ expect(inspectorHeading()).toHaveTextContent('web_search');++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));+ await userEvent.click(await treeItem(/AgentGraph/));+ expect(inspectorHeading()).toHaveTextContent('AgentGraph');+ act(() => keepNewestTracePage(client, 'convo-1'));++ await waitFor(() => expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument());+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));++ expect(await treeItem(/AgentGraph/)).toBeInTheDocument();+ expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();+ });++ it('retries the read that failed: an older page retries that page', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValueOnce({ records: records.slice(1), nextCursor: 'older' })+ .mockRejectedValueOnce(axiosError(504, 'timeout'))+ .mockResolvedValue({ records: records.slice(0, 1) });+ renderViewer();+ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));+ expect(await screen.findByRole('alert')).toHaveTextContent('com_ui_trace_error_timeout');++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));++ await waitFor(() => expect(list).toHaveBeenCalledTimes(3));+ expect(list).toHaveBeenLastCalledWith(+ { conversationId: 'convo-1', cursor: 'older' },+ expect.any(AbortSignal),+ );+ });++ it('reloads from the newest page when an older page no longer matches the trace', async () => {+ const list = jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValueOnce({ records: records.slice(1), nextCursor: 'older' })+ .mockRejectedValueOnce(axiosError(400, 'invalid_request'))+ .mockResolvedValue({ records: records.slice(1), nextCursor: 'older' });+ renderViewer();+ await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));+ expect(await screen.findByRole('alert')).toHaveTextContent('com_ui_trace_error_changed');++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));++ await waitFor(() => expect(list).toHaveBeenCalledTimes(3));+ expect(list).toHaveBeenLastCalledWith(+ { conversationId: 'convo-1', cursor: undefined },+ expect.any(AbortSignal),+ );+ });++ it('rereads an open record detail when the trace is refreshed', async () => {+ mockStartupConfig = { interface: { traceViewer: { enabled: true, showInputOutput: true } } };+ renderViewer();+ await userEvent.click(await treeItem(/llm/));+ await waitFor(() => expect(dataService.getConversationTraceRecord).toHaveBeenCalledTimes(1));++ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_refresh' }));++ await waitFor(() => expect(dataService.getConversationTraceRecord).toHaveBeenCalledTimes(2));+ });++ it('returns focus to the search field when closing the inspector after a filter hid every row', async () => {+ renderViewer();+ await userEvent.click(await treeItem(/llm/));+ const search = screen.getByLabelText('com_ui_trace_search');+ await userEvent.type(search, 'no-such-record');+ expect(screen.queryByRole('tree')).not.toBeInTheDocument();++ const inspector = screen.getByTestId('trace-inspector');+ await userEvent.click(+ within(inspector).getByRole('button', { name: 'com_ui_trace_close_details' }),+ );++ expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();+ expect(search).toHaveFocus();+ });++ it('closes the inspector on Escape before closing the trace', async () => {+ const { onClose } = renderViewer();+ await userEvent.click(await treeItem(/llm/));++ await userEvent.keyboard('{Escape}');+ expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();+ expect(onClose).not.toHaveBeenCalled();++ await userEvent.keyboard('{Escape}');+ expect(onClose).toHaveBeenCalledTimes(1);+ });++ it('links to Langfuse only for users who manage the connection', async () => {+ const first = renderViewer();+ await treeItem(/AgentGraph/);+ expect(+ screen.queryByRole('link', { name: /com_ui_trace_open_langfuse/ }),+ ).not.toBeInTheDocument();+ expect(dataService.getLangfuseSessionLink).not.toHaveBeenCalled();+ first.unmount();++ mockStartupConfig = {+ interface: { traceViewer: { enabled: true } },+ langfuseConnectionAccess: true,+ };+ renderViewer();++ const link = await screen.findByRole('link', { name: /com_ui_trace_open_langfuse/ });+ expect(link).toHaveAttribute('href', 'https://langfuse.test/project/p/sessions/convo-1');+ expect(link).toHaveAttribute('rel', 'noopener noreferrer');+ });++ it('does not link to a Langfuse project other than the one that served the trace', async () => {+ mockStartupConfig = {+ interface: { traceViewer: { enabled: true } },+ langfuseConnectionAccess: true,+ };+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockResolvedValue({ records, sourceId: 'central-project' });+ renderViewer();++ await treeItem(/AgentGraph/);+ await waitFor(() => expect(dataService.getLangfuseSessionLink).toHaveBeenCalled());+ expect(+ screen.queryByRole('link', { name: /com_ui_trace_open_langfuse/ }),+ ).not.toBeInTheDocument();+ });++ it('cancels an in-flight trace read when the viewer closes', async () => {+ let signal: AbortSignal | undefined;+ jest+ .spyOn(dataService, 'getConversationTraceRecords')+ .mockImplementation((_params, requestSignal) => {+ signal = requestSignal;+ return new Promise(() => undefined);+ });+ const { unmount } = renderViewer();+ await waitFor(() => expect(signal).toBeDefined());++ unmount();++ await waitFor(() => expect(signal?.aborted).toBe(true));+ });++ it('moves focus into the trace when it opens', async () => {+ renderViewer();++ expect(screen.getByRole('button', { name: 'com_ui_trace_close' })).toHaveFocus();+ });+});diff --git a/client/src/components/Chat/Trace/__tests__/format.test.ts b/client/src/components/Chat/Trace/__tests__/format.test.tsnew file mode 100644index 0000000000..b91a320c2b--- /dev/null+++ b/client/src/components/Chat/Trace/__tests__/format.test.ts@@ -0,0 +1,32 @@+import { createTraceFormat } from '../format';++const AFTERNOON = Date.UTC(2026, 8, 12, 13, 5, 9);++describe('createTraceFormat', () => {+ it('scales the duration unit with the magnitude', () => {+ const { duration } = createTraceFormat('en-US');++ expect(duration(12)).toMatch(/^12\s?ms$/);+ expect(duration(1234)).toMatch(/^1\.23\s?s$/);+ expect(duration(65_000)).toMatch(/^1\s?m(in)?\s+5\s?s$/);+ expect(duration(3_720_000)).toMatch(/^1\s?h\s+2\s?m(in)?$/);+ expect(duration(-5)).toMatch(/^0\s?ms$/);+ });++ it("formats numbers in the app's language rather than the runtime's", () => {+ expect(createTraceFormat('de').duration(1234)).toContain('1,23');+ expect(createTraceFormat('en-US').duration(1234)).toContain('1.23');+ });++ it("follows the user's clock setting over the language's own convention", () => {+ const twentyFour = createTraceFormat('en-US', false).clock(AFTERNOON);+ const twelve = createTraceFormat('en-GB', true).clock(AFTERNOON);++ expect(twentyFour).not.toMatch(/am|pm/i);+ expect(twelve).toMatch(/am|pm/i);+ });++ it('falls back to the runtime locale for a malformed language tag', () => {+ expect(() => createTraceFormat('not a locale!').duration(1234)).not.toThrow();+ });+});diff --git a/client/src/components/Chat/Trace/__tests__/model.test.ts b/client/src/components/Chat/Trace/__tests__/model.test.tsnew file mode 100644index 0000000000..6dd2df9315--- /dev/null+++ b/client/src/components/Chat/Trace/__tests__/model.test.ts@@ -0,0 +1,354 @@+import type { TTraceRecord } from 'librechat-data-provider';+import {+ turnKey,+ panWindow,+ fitWindow,+ zoomWindow,+ assignLanes,+ clampWindow,+ flattenRows,+ buildTraceModel,+ collapsibleKeys,+} from '../model';++const BASE = Date.UTC(2026, 8, 12, 11, 30, 0);+const at = (offsetMs: number) => new Date(BASE + offsetMs).toISOString();++function record(overrides: Partial<TTraceRecord> & Pick<TTraceRecord, 'id'>): TTraceRecord {+ return {+ traceId: 'trace-1',+ messageId: 'response-1',+ parentId: null,+ kind: 'span',+ name: overrides.id,+ startTime: at(0),+ endTime: at(1000),+ status: 'ok',+ ...overrides,+ };+}++const noFilter = { collapsed: new Set<string>(), query: '', window: null };+const rowKeys = (rows: ReturnType<typeof flattenRows>) => rows.map((row) => row.key);++describe('buildTraceModel', () => {+ it('nests records under their parents and orders turns and siblings by start', () => {+ const model = buildTraceModel([+ record({+ id: 'late-turn-root',+ messageId: 'response-2',+ startTime: at(5000),+ endTime: at(6000),+ }),+ record({ id: 'tool', parentId: 'root', kind: 'tool', startTime: at(600), endTime: at(900) }),+ record({+ id: 'llm',+ parentId: 'root',+ kind: 'generation',+ startTime: at(100),+ endTime: at(500),+ }),+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(1000) }),+ ]);++ expect(model.turns.map((turn) => turn.messageId)).toEqual(['response-1', 'response-2']);+ expect(model.nodes.get('root')?.childIds).toEqual(['llm', 'tool']);+ expect(model.nodes.get('tool')?.depth).toBe(1);+ expect(rowKeys(flattenRows(model, noFilter))).toEqual([+ turnKey('response-1'),+ 'root',+ 'llm',+ 'tool',+ turnKey('response-2'),+ 'late-turn-root',+ ]);+ });++ it('keeps records with a missing, cross-turn or cyclic parent as roots instead of dropping them', () => {+ const model = buildTraceModel([+ record({ id: 'orphan', parentId: 'not-loaded' }),+ record({ id: 'other-turn', messageId: 'response-2', parentId: 'orphan' }),+ record({ id: 'a', parentId: 'b', startTime: at(10) }),+ record({ id: 'b', parentId: 'a', startTime: at(20) }),+ record({ id: 'self', parentId: 'self', startTime: at(30) }),+ ]);++ const keys = rowKeys(flattenRows(model, noFilter));+ expect(new Set(keys)).toEqual(+ new Set([+ turnKey('response-1'),+ turnKey('response-2'),+ 'orphan',+ 'other-turn',+ 'a',+ 'b',+ 'self',+ ]),+ );+ expect(keys).toHaveLength(7);+ expect(model.nodes.get('other-turn')?.parentId).toBeNull();+ expect(model.nodes.get('self')?.parentId).toBeNull();+ const cycle = [model.nodes.get('a'), model.nodes.get('b')];+ expect(cycle.filter((node) => node?.parentId == null)).toHaveLength(1);+ });++ it('keeps a running record as a start with no invented duration', () => {+ const model = buildTraceModel([+ record({ id: 'root', startTime: at(0), endTime: at(2000) }),+ record({+ id: 'running',+ parentId: 'root',+ status: 'running',+ startTime: at(3000),+ endTime: undefined,+ }),+ ]);++ expect(model.nodes.get('running')?.end).toBeUndefined();+ expect(model.end).toBe(BASE + 3000);+ expect(model.summary.running).toBe(1);+ });++ it('clamps first-token time inside the record and repairs an end before its start', () => {+ const model = buildTraceModel([+ record({+ id: 'llm',+ kind: 'generation',+ startTime: at(1000),+ endTime: at(3000),+ completionStartTime: at(5000),+ }),+ record({ id: 'backwards', startTime: at(1000), endTime: at(500) }),+ record({ id: 'invalid', startTime: 'not a date' }),+ ]);++ expect(model.nodes.get('llm')?.firstToken).toBe(BASE + 3000);+ expect(model.nodes.get('backwards')?.end).toBe(BASE + 1000);+ expect(model.nodes.has('invalid')).toBe(false);+ });++ it('summarizes generations, tools, tokens, cost and errors', () => {+ const model = buildTraceModel([+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(4000) }),+ record({+ id: 'llm-1',+ parentId: 'root',+ kind: 'generation',+ usage: { input: 100, output: 20, total: 120 },+ cost: 0.01,+ }),+ record({+ id: 'llm-2',+ parentId: 'root',+ kind: 'generation',+ usage: { input: 10, output: 5 },+ cost: 0.005,+ }),+ record({ id: 'tool', parentId: 'root', kind: 'tool', status: 'error' }),+ ]);++ expect(model.summary).toEqual({+ duration: 4000,+ turns: 1,+ generations: 2,+ toolCalls: 1,+ errors: 1,+ running: 0,+ inputTokens: 110,+ outputTokens: 25,+ totalTokens: 135,+ cost: expect.closeTo(0.015),+ });+ expect(model.turns[0].errorCount).toBe(1);+ });++ it('withholds the cost total when any model call has no price, with or without usage', () => {+ const priced = record({ id: 'priced', kind: 'generation', usage: { total: 100 }, cost: 0.02 });+ const withUsage = buildTraceModel([+ priced,+ record({ id: 'unpriced', kind: 'generation', usage: { total: 50 } }),+ ]);+ const withoutUsage = buildTraceModel([priced, record({ id: 'bare', kind: 'generation' })]);+ const toolOnly = buildTraceModel([priced, record({ id: 'tool', kind: 'tool' })]);++ expect(withUsage.summary.cost).toBeUndefined();+ expect(withUsage.summary.totalTokens).toBe(150);+ expect(withoutUsage.summary.cost).toBeUndefined();+ expect(toolOnly.summary.cost).toBeCloseTo(0.02);+ });++ it('keeps the last copy of a record loaded twice', () => {+ const model = buildTraceModel([+ record({ id: 'root', status: 'running', endTime: undefined }),+ record({ id: 'root', status: 'ok' }),+ ]);++ expect(model.nodes.size).toBe(1);+ expect(model.nodes.get('root')?.record.status).toBe('ok');+ });+});++describe('flattenRows', () => {+ const model = buildTraceModel([+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(10_000) }),+ record({+ id: 'llm',+ parentId: 'root',+ kind: 'generation',+ model: 'gpt-5',+ startTime: at(0),+ endTime: at(2000),+ }),+ record({+ id: 'tool',+ parentId: 'root',+ kind: 'tool',+ name: 'web_search',+ startTime: at(5000),+ endTime: at(6000),+ }),+ record({+ id: 'nested',+ parentId: 'tool',+ name: 'fetch',+ startTime: at(5100),+ endTime: at(5900),+ }),+ ]);++ it('places each row among its visible siblings rather than the whole list', () => {+ const placements = flattenRows(model, noFilter).map(({ key, position, setSize }) => [+ key,+ position,+ setSize,+ ]);++ expect(placements).toEqual([+ [turnKey('response-1'), 1, 1],+ ['root', 1, 1],+ ['llm', 1, 2],+ ['tool', 2, 2],+ ['nested', 1, 1],+ ]);+ expect(+ flattenRows(model, { ...noFilter, query: 'fetch' }).find((row) => row.key === 'tool'),+ ).toMatchObject({ position: 1, setSize: 1 });+ });++ it('hides the descendants of a collapsed record and turn', () => {+ expect(rowKeys(flattenRows(model, { ...noFilter, collapsed: new Set(['tool']) }))).toEqual([+ turnKey('response-1'),+ 'root',+ 'llm',+ 'tool',+ ]);+ expect(+ rowKeys(flattenRows(model, { ...noFilter, collapsed: new Set([turnKey('response-1')]) })),+ ).toEqual([turnKey('response-1')]);+ });++ it('keeps search matches and their ancestors, even inside collapsed parents', () => {+ const rows = flattenRows(model, {+ collapsed: new Set(['root', 'tool']),+ query: 'FETCH',+ window: null,+ });++ expect(rowKeys(rows)).toEqual([turnKey('response-1'), 'root', 'tool', 'nested']);+ });++ it('matches on model names', () => {+ expect(rowKeys(flattenRows(model, { ...noFilter, query: 'gpt-5' }))).toEqual([+ turnKey('response-1'),+ 'root',+ 'llm',+ ]);+ });++ it('focuses the ledger on records active at any point in the interval', () => {+ const rows = flattenRows(model, {+ ...noFilter,+ window: { start: BASE + 5500, end: BASE + 7000 },+ });++ expect(rowKeys(rows)).toEqual([turnKey('response-1'), 'root', 'tool', 'nested']);+ });++ it('matches the localized labels a row shows rather than internal kind names', () => {+ const labelsFor = (entry: TTraceRecord) => [+ entry.kind === 'generation' ? 'Modellaufruf' : 'Schritt',+ entry.status === 'ok' ? 'Abgeschlossen' : 'Fehler',+ ];++ expect(rowKeys(flattenRows(model, { ...noFilter, query: 'modellauf', labelsFor }))).toEqual([+ turnKey('response-1'),+ 'root',+ 'llm',+ ]);+ expect(flattenRows(model, { ...noFilter, query: 'generation', labelsFor })).toEqual([]);+ });++ it('drops turns with nothing left to show', () => {+ expect(flattenRows(model, { ...noFilter, query: 'no such record' })).toEqual([]);+ });++ it('offers every turn and parent as a collapsible key', () => {+ expect(new Set(collapsibleKeys(model))).toEqual(+ new Set([turnKey('response-1'), 'root', 'tool']),+ );+ });+});++describe('time windows', () => {+ const bounds = { start: BASE, end: BASE + 10_000 };++ it('clamps a window inside the trace and clears it when it covers everything', () => {+ expect(clampWindow({ start: BASE - 5000, end: BASE + 1000 }, bounds)).toEqual({+ start: BASE,+ end: BASE + 6000,+ });+ expect(clampWindow({ start: BASE - 1, end: BASE + 20_000 }, bounds)).toBeNull();+ });++ it('fits a window to a trace that shrank, and drops one that no longer covers it', () => {+ const inside = { start: BASE + 1000, end: BASE + 2000 };+ expect(fitWindow(inside, bounds)).toBe(inside);+ expect(fitWindow({ start: BASE - 3000, end: BASE + 2000 }, bounds)).toEqual({+ start: BASE,+ end: BASE + 2000,+ });+ expect(fitWindow({ start: BASE - 3000, end: BASE - 1000 }, bounds)).toBeNull();+ expect(fitWindow({ start: BASE - 3000, end: BASE }, bounds)).toBeNull();+ });++ it('zooms around an anchor and pans within bounds', () => {+ const zoomed = zoomWindow(bounds, null, 0.5, BASE + 2000);+ expect(zoomed).toEqual({ start: BASE + 1000, end: BASE + 6000 });+ expect(zoomWindow(bounds, zoomed, 2, BASE + 2000)).toBeNull();+ expect(panWindow(bounds, { start: BASE + 9000, end: BASE + 10_000 }, 1)).toEqual({+ start: BASE + 9000,+ end: BASE + 10_000,+ });+ expect(panWindow(bounds, { start: BASE + 1000, end: BASE + 2000 }, -1)).toEqual({+ start: BASE + 900,+ end: BASE + 1900,+ });+ });+});++describe('assignLanes', () => {+ it('reuses a lane once its record ends and caps the lane count', () => {+ const model = buildTraceModel([+ record({ id: 'a', startTime: at(0), endTime: at(1000) }),+ record({ id: 'b', startTime: at(500), endTime: at(1500) }),+ record({ id: 'c', startTime: at(1000), endTime: at(2000) }),+ record({ id: 'd', startTime: at(1200), endTime: at(1300) }),+ ]);++ const lanes = assignLanes(model, 2);+ expect(lanes.get('a')).toBe(0);+ expect(lanes.get('b')).toBe(1);+ expect(lanes.get('c')).toBe(0);+ expect(lanes.get('d')).toBe(1);+ });+});diff --git a/client/src/components/Chat/Trace/format.ts b/client/src/components/Chat/Trace/format.tsnew file mode 100644index 0000000000..243160b2c1--- /dev/null+++ b/client/src/components/Chat/Trace/format.ts@@ -0,0 +1,103 @@+import { useMemo } from 'react';+import { useTranslation } from 'react-i18next';+import type { TraceNode } from './model';+import useClockFormat from '~/hooks/useClockFormat';++/** Shown for a finished record the backend gave no end, which has no measurable duration. */+const UNKNOWN_DURATION = '—';++export type TraceFormat = {+ duration: (ms: number) => string;+ clock: (epochMs: number) => string;+};++const formats = new Map<string, TraceFormat>();++/** A malformed language tag makes `Intl` throw; it falls back to the runtime's own locale. */+function supportedLocale(locale?: string): string | undefined {+ if (!locale) {+ return undefined;+ }+ try {+ return Intl.DateTimeFormat.supportedLocalesOf(locale).length > 0 ? locale : undefined;+ } catch {+ return undefined;+ }+}++/**+ * Duration and clock formatters for one locale and clock preference. Built once+ * per pair, since every visible ledger row formats several values per render.+ */+export function createTraceFormat(language?: string, hour12?: boolean): TraceFormat {+ const locale = supportedLocale(language);+ const key = `${locale ?? ''}|${hour12 ?? ''}`;+ const cached = formats.get(key);+ if (cached) {+ return cached;+ }++ const unit = (name: string, maximumFractionDigits: number) =>+ new Intl.NumberFormat(locale, {+ style: 'unit',+ unit: name,+ unitDisplay: 'narrow',+ maximumFractionDigits,+ });+ const milliseconds = unit('millisecond', 0);+ const seconds = unit('second', 2);+ const wholeSeconds = unit('second', 0);+ const minutes = unit('minute', 0);+ const hours = unit('hour', 0);+ const clock = new Intl.DateTimeFormat(locale, {+ hour: 'numeric',+ minute: '2-digit',+ second: '2-digit',+ hour12,+ });++ const format: TraceFormat = {+ duration: (ms) => {+ const value = Number.isFinite(ms) && ms > 0 ? ms : 0;+ if (value < 1000) {+ return milliseconds.format(value);+ }+ if (value < 60_000) {+ return seconds.format(value / 1000);+ }+ if (value < 3_600_000) {+ return `${minutes.format(Math.floor(value / 60_000))} ${wholeSeconds.format(+ Math.floor((value % 60_000) / 1000),+ )}`;+ }+ return `${hours.format(Math.floor(value / 3_600_000))} ${minutes.format(+ Math.floor((value % 3_600_000) / 60_000),+ )}`;+ },+ clock: (epochMs) => clock.format(epochMs),+ };+ formats.set(key, format);+ return format;+}++/**+ * A record's duration as the ledger and inspector show it. Running is read from the+ * record's status, not from a missing end: a failed record can lack an end too.+ */+export function recordDurationText(+ node: TraceNode,+ format: TraceFormat,+ runningLabel: string,+): string {+ if (node.record.status === 'running') {+ return runningLabel;+ }+ return node.end == null ? UNKNOWN_DURATION : format.duration(node.end - node.start);+}++/** Formats in the app's language and the user's clock setting, as message timestamps do. */+export function useTraceFormat(): TraceFormat {+ const { i18n } = useTranslation();+ const hour12 = useClockFormat();+ return useMemo(() => createTraceFormat(i18n.language, hour12), [i18n.language, hour12]);+}diff --git a/client/src/components/Chat/Trace/index.ts b/client/src/components/Chat/Trace/index.tsnew file mode 100644index 0000000000..18fa96d390--- /dev/null+++ b/client/src/components/Chat/Trace/index.ts@@ -0,0 +1,5 @@+export { default as TraceButton } from './Button';+export { default as TraceSurface } from './Surface';+export { default as useTraceControl } from './useTraceControl';+export type { TraceControl } from './useTraceControl';+export { traceViewerConversationAtom } from './store';diff --git a/client/src/components/Chat/Trace/kinds.ts b/client/src/components/Chat/Trace/kinds.tsnew file mode 100644index 0000000000..3f1e047f9b--- /dev/null+++ b/client/src/components/Chat/Trace/kinds.ts@@ -0,0 +1,59 @@+import { Bot, Zap, Wrench, Sparkles, Workflow } from 'lucide-react';+import type { TTraceRecordKind, TTraceStatus } from 'librechat-data-provider';+import type { LucideIcon } from 'lucide-react';+import type { TranslationKeys } from '~/hooks';++type KindAppearance = {+ icon: LucideIcon;+ label: TranslationKeys;+ /** Static class names: Tailwind cannot see an interpolated `bg-series-${n}`. */+ bar: string;+ /** The generation's time to first token, drawn as a tint of its bar. */+ tint: string;+ fill: string;+};++export const KIND_APPEARANCE: Record<TTraceRecordKind, KindAppearance> = {+ agent: {+ icon: Bot,+ label: 'com_ui_trace_kind_agent',+ bar: 'bg-series-1',+ tint: 'bg-series-1/30',+ fill: 'fill-series-1',+ },+ generation: {+ icon: Sparkles,+ label: 'com_ui_trace_kind_generation',+ bar: 'bg-series-2',+ tint: 'bg-series-2/30',+ fill: 'fill-series-2',+ },+ tool: {+ icon: Wrench,+ label: 'com_ui_trace_kind_tool',+ bar: 'bg-series-3',+ tint: 'bg-series-3/30',+ fill: 'fill-series-3',+ },+ span: {+ icon: Workflow,+ label: 'com_ui_trace_kind_span',+ bar: 'bg-series-6',+ tint: 'bg-series-6/30',+ fill: 'fill-series-6',+ },+ event: {+ icon: Zap,+ label: 'com_ui_trace_kind_event',+ bar: 'bg-series-4',+ tint: 'bg-series-4/30',+ fill: 'fill-series-4',+ },+};++export const STATUS_LABEL: Record<TTraceStatus, TranslationKeys> = {+ ok: 'com_ui_trace_status_ok',+ running: 'com_ui_trace_status_running',+ error: 'com_ui_trace_status_error',+ warning: 'com_ui_trace_status_warning',+};diff --git a/client/src/components/Chat/Trace/model.ts b/client/src/components/Chat/Trace/model.tsnew file mode 100644index 0000000000..900684948e--- /dev/null+++ b/client/src/components/Chat/Trace/model.ts@@ -0,0 +1,453 @@+import type { TTraceRecord } from 'librechat-data-provider';++export type TraceNode = {+ record: TTraceRecord;+ start: number;+ /** Absent while the record is still running: it has a start, not a duration. */+ end?: number;+ /** First streamed token, clamped inside the record's own span. */+ firstToken?: number;+ depth: number;+ parentId: string | null;+ childIds: string[];+};++export type TraceTurn = {+ key: string;+ messageId: string;+ start: number;+ end: number;+ rootIds: string[];+ recordCount: number;+ errorCount: number;+};++export type TraceSummary = {+ duration: number;+ turns: number;+ generations: number;+ toolCalls: number;+ errors: number;+ running: number;+ inputTokens: number;+ outputTokens: number;+ totalTokens: number;+ cost?: number;+};++export type TraceModel = {+ nodes: Map<string, TraceNode>;+ turns: TraceTurn[];+ start: number;+ end: number;+ summary: TraceSummary;+};++export type TraceWindow = { start: number; end: number };++/** `position` and `setSize` count the row's visible siblings, as a tree item's ARIA position does. */+type RowPlacement = { key: string; expanded: boolean; position: number; setSize: number };++export type TraceRow =+ | (RowPlacement & { type: 'turn'; turn: TraceTurn })+ | (RowPlacement & { type: 'record'; node: TraceNode; hasChildren: boolean });++export type TraceFilter = {+ collapsed: ReadonlySet<string>;+ query: string;+ window: TraceWindow | null;+ /** The labels a row shows for its record (kind and status, localized), which search also matches. */+ labelsFor?: (record: TTraceRecord) => readonly string[];+};++const EMPTY_SUMMARY: TraceSummary = {+ duration: 0,+ turns: 0,+ generations: 0,+ toolCalls: 0,+ errors: 0,+ running: 0,+ inputTokens: 0,+ outputTokens: 0,+ totalTokens: 0,+};++export const turnKey = (messageId: string): string => `turn:${messageId}`;++const byStart = (nodes: Map<string, TraceNode>) => (a: string, b: string) => {+ const left = nodes.get(a);+ const right = nodes.get(b);+ return (left?.start ?? 0) - (right?.start ?? 0) || a.localeCompare(b);+};++function toNode(record: TTraceRecord): TraceNode | null {+ const start = Date.parse(record.startTime);+ if (!Number.isFinite(start)) {+ return null;+ }+ const parsedEnd = record.endTime != null ? Date.parse(record.endTime) : Number.NaN;+ const end = Number.isFinite(parsedEnd) ? Math.max(parsedEnd, start) : undefined;+ const parsedToken =+ record.completionStartTime != null ? Date.parse(record.completionStartTime) : Number.NaN;+ const firstToken = Number.isFinite(parsedToken)+ ? Math.min(Math.max(parsedToken, start), end ?? parsedToken)+ : undefined;+ return { record, start, end, firstToken, depth: 0, parentId: null, childIds: [] };+}++/**+ * Cuts every parent cycle so each record hangs from exactly one root. A record+ * whose parent is unloaded, belongs to another turn, or closes a loop becomes a+ * root of its own turn instead of disappearing.+ */+function resolveParents(nodes: Map<string, TraceNode>): void {+ for (const [id, node] of nodes) {+ const parentId = node.record.parentId;+ const parent = parentId != null ? nodes.get(parentId) : undefined;+ node.parentId =+ parent != null && parentId !== id && parent.record.messageId === node.record.messageId+ ? parentId+ : null;+ }++ const settled = new Set<string>();+ for (const id of nodes.keys()) {+ const path = new Set<string>();+ let current: string | null = id;+ let previous: string | null = null;+ while (current != null && !settled.has(current)) {+ if (path.has(current)) {+ const cutAt = nodes.get(previous ?? current);+ if (cutAt) {+ cutAt.parentId = null;+ }+ break;+ }+ path.add(current);+ previous = current;+ current = nodes.get(current)?.parentId ?? null;+ }+ for (const visited of path) {+ settled.add(visited);+ }+ }+}++/** Projects a flat, possibly partial record list into turns of record trees. */+export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {+ const nodes = new Map<string, TraceNode>();+ for (const record of records) {+ const node = toNode(record);+ if (node) {+ nodes.set(record.id, node);+ }+ }+ if (nodes.size === 0) {+ return { nodes, turns: [], start: 0, end: 0, summary: EMPTY_SUMMARY };+ }++ resolveParents(nodes);++ const turnsByMessage = new Map<string, TraceTurn>();+ const summary: TraceSummary = { ...EMPTY_SUMMARY };+ let start = Number.POSITIVE_INFINITY;+ let end = Number.NEGATIVE_INFINITY;+ let cost = 0;+ let pricedRecords = 0;+ let unpricedRecords = 0;++ for (const [id, node] of nodes) {+ const { record } = node;+ const nodeEnd = node.end ?? node.start;+ start = Math.min(start, node.start);+ end = Math.max(end, nodeEnd);++ if (node.parentId != null) {+ nodes.get(node.parentId)?.childIds.push(id);+ }++ const key = turnKey(record.messageId);+ let turn = turnsByMessage.get(record.messageId);+ if (!turn) {+ turn = {+ key,+ messageId: record.messageId,+ start: node.start,+ end: nodeEnd,+ rootIds: [],+ recordCount: 0,+ errorCount: 0,+ };+ turnsByMessage.set(record.messageId, turn);+ }+ turn.start = Math.min(turn.start, node.start);+ turn.end = Math.max(turn.end, nodeEnd);+ turn.recordCount++;+ if (node.parentId == null) {+ turn.rootIds.push(id);+ }++ if (record.status === 'error') {+ turn.errorCount++;+ summary.errors++;+ } else if (record.status === 'running') {+ summary.running++;+ }+ if (record.kind === 'tool') {+ summary.toolCalls++;+ }+ if (record.kind === 'generation') {+ summary.generations++;+ const input = record.usage?.input ?? 0;+ const output = record.usage?.output ?? 0;+ const total = record.usage?.total ?? input + output;+ summary.inputTokens += input;+ summary.outputTokens += output;+ summary.totalTokens += total;+ if (record.cost == null) {+ unpricedRecords++;+ }+ }+ if (record.cost != null) {+ pricedRecords++;+ cost += record.cost;+ }+ }++ const compare = byStart(nodes);+ const turns = [...turnsByMessage.values()].sort((a, b) => a.start - b.start);+ for (const turn of turns) {+ turn.rootIds.sort(compare);+ const stack = turn.rootIds.map((id) => ({ id, depth: 0 }));+ while (stack.length > 0) {+ const entry = stack.pop();+ const node = entry ? nodes.get(entry.id) : undefined;+ if (!entry || !node) {+ continue;+ }+ node.depth = entry.depth;+ node.childIds.sort(compare);+ for (const childId of node.childIds) {+ stack.push({ id: childId, depth: entry.depth + 1 });+ }+ }+ }++ summary.turns = turns.length;+ summary.duration = end - start;+ /** A total that silently skips a model call without a price, with or without usage, would under-report spend, so there is none. */+ if (pricedRecords > 0 && unpricedRecords === 0) {+ summary.cost = cost;+ }+ return { nodes, turns, start, end, summary };+}++function matchesQuery(+ node: TraceNode,+ query: string,+ labelsFor: TraceFilter['labelsFor'],+): boolean {+ if (!query) {+ return true;+ }+ const { record } = node;+ return [record.name, record.model, record.statusMessage, ...(labelsFor?.(record) ?? [])].some(+ (value) => value != null && value.toLowerCase().includes(query),+ );+}++function overlapsWindow(node: TraceNode, window: TraceWindow | null): boolean {+ return window == null || (node.start <= window.end && (node.end ?? node.start) >= window.start);+}++/** Records that match the filter, plus every ancestor so a match keeps its context. */+function visibleIds(+ model: TraceModel,+ query: string,+ window: TraceWindow | null,+ labelsFor: TraceFilter['labelsFor'],+): Set<string> {+ const visible = new Set<string>();+ for (const [id, node] of model.nodes) {+ if (!matchesQuery(node, query, labelsFor) || !overlapsWindow(node, window)) {+ continue;+ }+ let current: string | null = id;+ while (current != null && !visible.has(current)) {+ visible.add(current);+ current = model.nodes.get(current)?.parentId ?? null;+ }+ }+ return visible;+}++/**+ * The ledger's rows in display order. A search or interval selection expands+ * everything it keeps, so a match is never hidden inside a folded parent.+ */+export function flattenRows(+ model: TraceModel,+ { collapsed, query, window, labelsFor }: TraceFilter,+): TraceRow[] {+ const normalizedQuery = query.trim().toLowerCase();+ const filtering = normalizedQuery !== '' || window != null;+ const visible = filtering ? visibleIds(model, normalizedQuery, window, labelsFor) : null;+ const rows: TraceRow[] = [];++ const turns = model.turns.flatMap((turn) => {+ const roots = visible ? turn.rootIds.filter((id) => visible.has(id)) : turn.rootIds;+ return visible && roots.length === 0 ? [] : [{ turn, roots }];+ });++ turns.forEach(({ turn, roots }, turnIndex) => {+ const turnExpanded = filtering || !collapsed.has(turn.key);+ rows.push({+ type: 'turn',+ key: turn.key,+ turn,+ expanded: turnExpanded,+ position: turnIndex + 1,+ setSize: turns.length,+ });+ if (!turnExpanded) {+ return;+ }++ const stack = roots+ .map((id, index) => ({ id, position: index + 1, setSize: roots.length }))+ .reverse();+ while (stack.length > 0) {+ const entry = stack.pop();+ const node = entry != null ? model.nodes.get(entry.id) : undefined;+ if (entry == null || !node) {+ continue;+ }+ const children = visible+ ? node.childIds.filter((childId) => visible.has(childId))+ : node.childIds;+ const expanded = filtering || !collapsed.has(entry.id);+ rows.push({+ type: 'record',+ key: entry.id,+ node,+ expanded,+ hasChildren: children.length > 0,+ position: entry.position,+ setSize: entry.setSize,+ });+ if (!expanded) {+ continue;+ }+ for (let i = children.length - 1; i >= 0; i--) {+ stack.push({ id: children[i], position: i + 1, setSize: children.length });+ }+ }+ });+ return rows;+}++/** Ids a user can fold: every turn and every record with children. */+export function collapsibleKeys(model: TraceModel): string[] {+ const keys = model.turns.map((turn) => turn.key);+ for (const [id, node] of model.nodes) {+ if (node.childIds.length > 0) {+ keys.push(id);+ }+ }+ return keys;+}++/**+ * Packs records into a fixed number of overview lanes the way a network+ * waterfall does: each record takes the first lane free at its start.+ */+export function assignLanes(model: TraceModel, laneCount: number): Map<string, number> {+ const laneEnds: number[] = [];+ const lanes = new Map<string, number>();+ const ordered = [...model.nodes.values()].sort((a, b) => a.start - b.start || a.depth - b.depth);+ for (const node of ordered) {+ let lane = laneEnds.findIndex((laneEnd) => laneEnd <= node.start);+ if (lane === -1) {+ lane = laneEnds.length < laneCount ? laneEnds.length : laneCount - 1;+ }+ laneEnds[lane] = Math.max(laneEnds[lane] ?? 0, node.end ?? node.start);+ lanes.set(node.record.id, lane);+ }+ return lanes;+}++/** Clamps a zoom window inside the trace and keeps it at least `minSpan` wide. */+export function clampWindow(+ window: TraceWindow,+ bounds: TraceWindow,+ minSpan = 1,+): TraceWindow | null {+ const total = bounds.end - bounds.start;+ if (total <= 0) {+ return null;+ }+ const span = Math.min(Math.max(window.end - window.start, minSpan), total);+ if (span >= total) {+ return null;+ }+ const start = Math.min(Math.max(window.start, bounds.start), bounds.end - span);+ return { start, end: start + span };+}++/**+ * Keeps a zoom window on the records still loaded: the part of it inside the+ * trace, or none when it covers none of the trace. A window that already fits+ * is returned as is.+ */+export function fitWindow(+ window: TraceWindow,+ model: Pick<TraceModel, 'start' | 'end'>,+): TraceWindow | null {+ const start = Math.max(window.start, model.start);+ const end = Math.min(window.end, model.end);+ if (end <= start) {+ return null;+ }+ if (start === window.start && end === window.end) {+ return window;+ }+ return clampWindow({ start, end }, { start: model.start, end: model.end }, minimumSpan(model));+}++export const ZOOM_STEP = 0.5;+const PAN_STEP = 0.1;++/** Rescales `view` by `factor` around `anchor`, an absolute timestamp. */+export function zoomWindow(+ model: Pick<TraceModel, 'start' | 'end'>,+ view: TraceWindow | null,+ factor: number,+ anchor?: number,+): TraceWindow | null {+ const bounds = { start: model.start, end: model.end };+ const current = view ?? bounds;+ const pivot = anchor ?? (current.start + current.end) / 2;+ const start = pivot - (pivot - current.start) * factor;+ const end = pivot + (current.end - pivot) * factor;+ return clampWindow({ start, end }, bounds, minimumSpan(model));+}++export function panWindow(+ model: Pick<TraceModel, 'start' | 'end'>,+ view: TraceWindow | null,+ direction: -1 | 1,+): TraceWindow | null {+ if (!view) {+ return null;+ }+ const shift = (view.end - view.start) * PAN_STEP * direction;+ return clampWindow(+ { start: view.start + shift, end: view.end + shift },+ { start: model.start, end: model.end },+ minimumSpan(model),+ );+}++export function minimumSpan(model: Pick<TraceModel, 'start' | 'end'>): number {+ return Math.max((model.end - model.start) / 1000, 1);+}diff --git a/client/src/components/Chat/Trace/store.ts b/client/src/components/Chat/Trace/store.tsnew file mode 100644index 0000000000..b0318acfd2--- /dev/null+++ b/client/src/components/Chat/Trace/store.ts@@ -0,0 +1,8 @@+import { atom } from 'jotai';++/**+ * The conversation whose trace covers the chat surface, or `null` when the chat+ * shows. Keyed by conversation so a trace never survives into another chat.+ * Memory-only: a reload returns to the conversation.+ */+export const traceViewerConversationAtom = atom<string | null>(null);diff --git a/client/src/components/Chat/Trace/useTraceControl.ts b/client/src/components/Chat/Trace/useTraceControl.tsnew file mode 100644index 0000000000..93c4fa1f5a--- /dev/null+++ b/client/src/components/Chat/Trace/useTraceControl.ts@@ -0,0 +1,64 @@+import { useRef, useEffect, useCallback } from 'react';+import { useSetAtom } from 'jotai';+import { useQueryClient } from '@tanstack/react-query';+import { QueryKeys, Constants, resolveTraceViewerConfig } from 'librechat-data-provider';+import type { TTraceViewerConfig } from 'librechat-data-provider';+import { keepNewestTracePage, useConversationTraceAvailabilityQuery } from '~/data-provider';+import { traceViewerConversationAtom } from './store';++export type TraceControl = {+ /** A persisted conversation of the user's with at least one readable trace. */+ show: boolean;+ open: () => void;+};++const UNPERSISTED_IDS = new Set(+ [Constants.NEW_CONVO, Constants.PENDING_CONVO, Constants.SEARCH].map(String),+);++/**+ * The trace entry point for the desktop button and the mobile overflow item, so+ * both surfaces share one visibility rule. Availability is re-read after each+ * run settles, which is when a newly sampled response can make it appear.+ */+export default function useTraceControl({+ conversationId,+ traceViewer,+ isSubmitting,+ enabled = true,+}: {+ conversationId?: string | null;+ traceViewer?: TTraceViewerConfig;+ isSubmitting: boolean;+ enabled?: boolean;+}): TraceControl {+ const setTraceConversation = useSetAtom(traceViewerConversationAtom);+ const persisted = conversationId != null && !UNPERSISTED_IDS.has(conversationId);+ const eligible = enabled && persisted && resolveTraceViewerConfig(traceViewer).enabled;++ const { data } = useConversationTraceAvailabilityQuery(conversationId ?? '', {+ enabled: eligible && !isSubmitting,+ });++ /** A settled run adds a turn to the trace, so pages cached by an earlier open go stale now+ * rather than when their stale time lapses. */+ const queryClient = useQueryClient();+ const wasSubmitting = useRef(isSubmitting);+ useEffect(() => {+ const settled = wasSubmitting.current && !isSubmitting;+ wasSubmitting.current = isSubmitting;+ if (settled && eligible && conversationId != null) {+ keepNewestTracePage(queryClient, conversationId);+ queryClient.invalidateQueries([QueryKeys.conversationTraceRecords, conversationId]);+ queryClient.invalidateQueries([QueryKeys.conversationTraceRecord, conversationId]);+ }+ }, [isSubmitting, eligible, conversationId, queryClient]);++ const open = useCallback(() => {+ if (conversationId != null) {+ setTraceConversation(conversationId);+ }+ }, [conversationId, setTraceConversation]);++ return { show: eligible && data?.available === true, open };+}diff --git a/client/src/components/Chat/Trace/virtual.ts b/client/src/components/Chat/Trace/virtual.tsnew file mode 100644index 0000000000..568d3a843d--- /dev/null+++ b/client/src/components/Chat/Trace/virtual.ts@@ -0,0 +1,54 @@+import { useEffect, useState } from 'react';+import type { RefObject } from 'react';++export type RowWindow = { first: number; last: number };++/**+ * The slice of fixed-height rows inside a scroll container, plus overscan.+ * Rows share one height, so the window is arithmetic rather than measured.+ */+export function useRowWindow(+ scrollRef: RefObject<HTMLElement>,+ count: number,+ rowHeight: number,+ { offset = 0, overscan = 8 }: { offset?: number; overscan?: number } = {},+): RowWindow {+ const [viewport, setViewport] = useState({ top: 0, height: 0 });++ useEffect(() => {+ const element = scrollRef.current;+ if (!element) {+ return;+ }+ let frame = 0;+ const measure = () => {+ frame = 0;+ setViewport((current) =>+ current.top === element.scrollTop && current.height === element.clientHeight+ ? current+ : { top: element.scrollTop, height: element.clientHeight },+ );+ };+ const schedule = () => {+ if (frame === 0) {+ frame = requestAnimationFrame(measure);+ }+ };+ measure();+ element.addEventListener('scroll', schedule, { passive: true });+ const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);+ observer?.observe(element);+ return () => {+ element.removeEventListener('scroll', schedule);+ observer?.disconnect();+ if (frame !== 0) {+ cancelAnimationFrame(frame);+ }+ };+ }, [scrollRef]);++ const visibleCount = Math.ceil((viewport.height || rowHeight * 20) / rowHeight);+ const first = Math.max(0, Math.floor((viewport.top - offset) / rowHeight) - overscan);+ const last = Math.min(count - 1, first + visibleCount + overscan * 2);+ return { first, last };+}diff --git a/client/src/data-provider/Traces/index.ts b/client/src/data-provider/Traces/index.tsnew file mode 100644index 0000000000..3cf1ef310b--- /dev/null+++ b/client/src/data-provider/Traces/index.ts@@ -0,0 +1 @@+export * from './queries';diff --git a/client/src/data-provider/Traces/queries.ts b/client/src/data-provider/Traces/queries.tsnew file mode 100644index 0000000000..caf7c4c629--- /dev/null+++ b/client/src/data-provider/Traces/queries.ts@@ -0,0 +1,105 @@+import { QueryKeys, dataService } from 'librechat-data-provider';+import { useInfiniteQuery, useQuery } from '@tanstack/react-query';+import type {+ QueryClient,+ InfiniteData,+ UseInfiniteQueryResult,+ QueryObserverResult,+ UseQueryOptions,+} from '@tanstack/react-query';+import type {+ TTracePage,+ TTraceAvailability,+ TTraceRecordParams,+ TTraceRecordDetail,+} from 'librechat-data-provider';+import { getResponseStatus } from '~/utils/errors';++const MAX_AVAILABILITY_RETRIES = 10;+const MAX_AVAILABILITY_RETRIES_ON_ERROR = 3;++/** Availability flips only when a response is sampled, so callers re-enable it after a turn. */+export const useConversationTraceAvailabilityQuery = (+ conversationId: string,+ config?: UseQueryOptions<TTraceAvailability>,+): QueryObserverResult<TTraceAvailability> =>+ useQuery<TTraceAvailability>(+ [QueryKeys.conversationTraceAvailability, conversationId],+ () => dataService.getConversationTraceAvailability(conversationId),+ {+ /** A hidden control has no error to show, so a transient failure retries on its own. */+ retry: (failureCount, error) => {+ const status = getResponseStatus(error);+ return (+ failureCount < MAX_AVAILABILITY_RETRIES_ON_ERROR && (status == null || status >= 500)+ );+ },+ refetchOnWindowFocus: false,+ /** The server asks again only while it cannot decide yet, and only a few times. */+ refetchInterval: (data, query) =>+ data?.retryAfterMs != null && query.state.dataUpdateCount < MAX_AVAILABILITY_RETRIES+ ? data.retryAfterMs+ : false,+ ...config,+ },+ );++export const useConversationTraceRecordsQuery = (+ conversationId: string,+ enabled: boolean,+): UseInfiniteQueryResult<TTracePage> =>+ useInfiniteQuery<TTracePage>({+ queryKey: [QueryKeys.conversationTraceRecords, conversationId],+ queryFn: ({ pageParam, signal }) =>+ dataService.getConversationTraceRecords(+ { conversationId, cursor: typeof pageParam === 'string' ? pageParam : undefined },+ signal,+ ),+ getNextPageParam: (lastPage) => lastPage?.nextCursor ?? undefined,+ enabled,+ retry: false,+ staleTime: 30_000,+ refetchOnWindowFocus: false,+ });++/** `sourceId` is the page that listed the record, so the detail reads the same project. */+export const useConversationTraceRecordQuery = (+ {+ conversationId,+ recordId,+ messageId,+ sourceId,+ }: Omit<TTraceRecordParams, 'recordId'> & {+ recordId: string | null;+ },+ enabled: boolean,+): QueryObserverResult<TTraceRecordDetail> =>+ useQuery<TTraceRecordDetail>(+ [QueryKeys.conversationTraceRecord, conversationId, recordId, messageId, sourceId ?? null],+ ({ signal }) =>+ dataService.getConversationTraceRecord(+ { conversationId, recordId: recordId ?? '', messageId, sourceId },+ signal,+ ),+ {+ enabled: enabled && recordId != null,+ retry: false,+ staleTime: 5 * 60_000,+ refetchOnWindowFocus: false,+ },+ );++/**+ * Keeps only the newest page of a conversation's trace, so the next fetch reads+ * one page. Older pages cannot change, but replaying them all through the+ * per-user trace limiter on every refresh would exhaust it; they reload on demand.+ */+export function keepNewestTracePage(queryClient: QueryClient, conversationId: string): void {+ queryClient.setQueryData<InfiniteData<TTracePage>>(+ [QueryKeys.conversationTraceRecords, conversationId],+ (data) =>+ data != null && data.pages.length > 1+ ? { pages: data.pages.slice(0, 1), pageParams: data.pageParams.slice(0, 1) }+ : data,+ );+}diff --git a/client/src/data-provider/index.ts b/client/src/data-provider/index.tsindex 38bb19a958..ea2696ae8d 100644--- a/client/src/data-provider/index.ts+++ b/client/src/data-provider/index.ts@@ -14,6 +14,7 @@ export * from './Projects';export * from './Schedules';export * from './Subagents';export * from './Tools';+export * from './Traces';export * from './connection';export * from './Favorites';export * from './CodeEnvironments';diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex a3fd4d7d7c..018d3f4925 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -2557,6 +2557,82 @@"com_ui_tools_view_favorites_empty": "You haven't favorited anything yet","com_ui_tools_view_made_by_you": "Made by you","com_ui_tools_view_mine_empty": "You haven't created anything yet",+ "com_ui_trace_bar_description": "{{0}}, starts {{1}} in, {{2}}",+ "com_ui_trace_clear_selection": "Clear selection",+ "com_ui_trace_close": "Close trace",+ "com_ui_trace_close_details": "Close details",+ "com_ui_trace_collapse_all": "Collapse all",+ "com_ui_trace_column_duration": "Duration",+ "com_ui_trace_column_name": "Name",+ "com_ui_trace_column_timeline": "Timeline",+ "com_ui_trace_column_tokens": "Tokens",+ "com_ui_trace_content": "Content",+ "com_ui_trace_content_empty": "No input, output or metadata was recorded.",+ "com_ui_trace_content_error": "Couldn't load this record's content.",+ "com_ui_trace_content_hidden": "Input and output aren't shown on this deployment.",+ "com_ui_trace_decoding": "Decoding",+ "com_ui_trace_empty_description": "The tracing service has no records for this conversation yet. New traces can take a minute to arrive after a response finishes.",+ "com_ui_trace_empty_title": "No trace records yet",+ "com_ui_trace_error_changed": "This trace changed since it loaded. Retry to reload it from the newest records.",+ "com_ui_trace_error_generic": "The tracing service couldn't return this trace.",+ "com_ui_trace_error_not_found": "This conversation has no trace available.",+ "com_ui_trace_error_rate_limited": "Too many trace requests. Try again in a minute.",+ "com_ui_trace_error_timeout": "The tracing service didn't respond in time.",+ "com_ui_trace_error_title": "Couldn't load the trace",+ "com_ui_trace_error_unauthorized": "The tracing service rejected this deployment's credentials.",+ "com_ui_trace_error_unsupported": "This tracing service can't serve traces. Langfuse v4 or later is required.",+ "com_ui_trace_expand_all": "Expand all",+ "com_ui_trace_identifiers": "Identifiers",+ "com_ui_trace_input": "Input",+ "com_ui_trace_kind_agent": "Agent",+ "com_ui_trace_kind_event": "Event",+ "com_ui_trace_kind_generation": "Model call",+ "com_ui_trace_kind_span": "Step",+ "com_ui_trace_kind_tool": "Tool",+ "com_ui_trace_load_older": "Load older records",+ "com_ui_trace_loading": "Loading trace",+ "com_ui_trace_metadata": "Metadata",+ "com_ui_trace_model": "Model",+ "com_ui_trace_no_matches": "No records match this search or interval.",+ "com_ui_trace_offset": "Into response",+ "com_ui_trace_open_langfuse": "Open in Langfuse",+ "com_ui_trace_output": "Output",+ "com_ui_trace_overview": "Timeline overview",+ "com_ui_trace_overview_hint": "Drag to focus an interval. Scroll or press plus and minus to zoom, use the arrow keys to pan, and press Escape to reset.",+ "com_ui_trace_partial": "Showing the newest {{0}} records",+ "com_ui_trace_record_id": "Record ID",+ "com_ui_trace_records": "Trace records",+ "com_ui_trace_refresh": "Refresh trace",+ "com_ui_trace_search": "Search records",+ "com_ui_trace_selection": "Showing {{0}} to {{1}}",+ "com_ui_trace_started": "Started",+ "com_ui_trace_status_error": "Error",+ "com_ui_trace_status_ok": "Completed",+ "com_ui_trace_status_running": "In progress",+ "com_ui_trace_status_warning": "Warning",+ "com_ui_trace_summary": "Trace summary",+ "com_ui_trace_summary_cost": "Cost",+ "com_ui_trace_summary_duration": "Duration",+ "com_ui_trace_summary_errors": "Errors",+ "com_ui_trace_summary_generations": "Model calls",+ "com_ui_trace_summary_tokens": "Tokens",+ "com_ui_trace_summary_tools": "Tool calls",+ "com_ui_trace_summary_turns": "Responses",+ "com_ui_trace_timing": "Timing",+ "com_ui_trace_title": "Trace",+ "com_ui_trace_trace_id": "Trace ID",+ "com_ui_trace_truncated": "Truncated to this deployment's content limit.",+ "com_ui_trace_ttft": "Time to first token",+ "com_ui_trace_turn": "Response at {{0}}",+ "com_ui_trace_turn_records": "{{0}} records",+ "com_ui_trace_usage": "Usage",+ "com_ui_trace_usage_cache_read": "Cache read",+ "com_ui_trace_usage_cache_write": "Cache write",+ "com_ui_trace_usage_input": "Input",+ "com_ui_trace_usage_output": "Output",+ "com_ui_trace_usage_reasoning": "Reasoning",+ "com_ui_trace_usage_total": "Total",+ "com_ui_trace_view": "View trace","com_ui_transferred_to": "Transferred to","com_ui_travel": "Travel","com_ui_trust_app": "I trust this application",diff --git a/librechat.example.yaml b/librechat.example.yamlindex 02fad59664..fef8bb068f 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -247,6 +247,26 @@ interface:fileCitations: true# Show the thumbs up/thumbs down feedback buttons on responses (default: true)feedback: true+ # Conversation trace viewer: a waterfall of the model calls and tool spans behind+ # each response, read from the deployment's Langfuse project. The control only+ # appears on the requesting user's own conversations with a sampled trace, and+ # needs a Langfuse release that serves the v2 Observations API.+ # traceViewer:+ # enabled: false+ # # Traces are matched to users by the internal user id, so no trace is shown while+ # # langfuse.trace.userIdField exports another user field.+ # # Return observation input, output and metadata in the record inspector. Input+ # # carries system prompts, agent instructions and tool definitions, which a+ # # user chatting with a shared agent cannot otherwise see.+ # showInputOutput: false+ # # Observations read per request (1-10000); older records load on demand.+ # maxRecords: 1000+ # # Characters kept from each input, output and metadata value (1-1000000).+ # maxContentLength: 50000+ # # Trace reads one user may start per minute (1-1000).+ # requestsPerMinute: 30+ # # Budget for each request to Langfuse, in milliseconds (1000-300000).+ # requestTimeoutMs: 10000# Tools pinned to the prompt bar by default for all users.# Only seeds the initial state — once a user pins/unpins a tool, their choice is kept.# Valid tool keys: artifacts, execute_code, web_search, file_search, skills.diff --git a/packages/api/src/admin/langfuse.handler.spec.ts b/packages/api/src/admin/langfuse.handler.spec.tsindex 2bc5ecb7a1..5db211dbd2 100644--- a/packages/api/src/admin/langfuse.handler.spec.ts+++ b/packages/api/src/admin/langfuse.handler.spec.ts@@ -323,6 +323,7 @@ describe('createAdminLangfuseHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body).toEqual({url: 'https://cloud.langfuse.com/project/project-1/sessions/conversation-1',+ destinationId: getLangfuseDestinationId('https://cloud.langfuse.com', 'project-1'),});expect(deps.getMessages).toHaveBeenCalledWith({@@ -387,6 +388,7 @@ describe('createAdminLangfuseHandlers', () => {expect(linkRes.body).toEqual({url: 'https://cloud.langfuse.com/project/tenant-project-1/sessions/conversation-1',+ destinationId: getLangfuseDestinationId('https://cloud.langfuse.com', 'tenant-project-1'),});expect(getMessages).toHaveBeenCalledWith(expect.objectContaining({@@ -412,6 +414,7 @@ describe('createAdminLangfuseHandlers', () => {expect(res.body).toEqual({url: 'https://langfuse.example/base/path/project/project-1/sessions/conversation-1',+ destinationId: getLangfuseDestinationId('https://langfuse.example/base/path', 'project-1'),});});diff --git a/packages/api/src/admin/langfuse.ts b/packages/api/src/admin/langfuse.tsindex f323ddd424..351343ea9f 100644--- a/packages/api/src/admin/langfuse.ts+++ b/packages/api/src/admin/langfuse.ts@@ -22,7 +22,7 @@ import { redirectPolicyFor, resolveLangfuseHeaders } from '~/langfuse/utils';import { decryptConfigSecret, encryptConfigSecretFields } from './secrets';import { scopeHeadersToDestination } from '~/langfuse/destinations';import { isLangfuseConnectionAvailable } from '~/langfuse/policy';-import { resolveLangfuseSessionUrl } from '~/langfuse/session';+import { resolveLangfuseSession } from '~/langfuse/session';import { mergeHeaders } from '~/utils/headers';const DEFAULT_PRIORITY = 10;@@ -333,13 +333,15 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {}try {- const url = await resolveLangfuseSessionUrl({+ const session = await resolveLangfuseSession({config: readStoredLangfuse(await findBaseConfig()),conversationId,userId,getMessages,});- const response: TLangfuseSessionLinkResponse = { url };+ const response: TLangfuseSessionLinkResponse = session+ ? { url: session.url, destinationId: session.destinationId }+ : { url: null };return res.status(200).json(response);} catch (error) {logger.error('[adminLangfuse] getSessionLink error:', error);diff --git a/packages/api/src/index.ts b/packages/api/src/index.tsindex 782597bb8b..76d96b77e0 100644--- a/packages/api/src/index.ts+++ b/packages/api/src/index.ts@@ -99,6 +99,8 @@ export * from './tools';export * from './web';/* Langfuse */export * from './langfuse';+/* Traces */+export * from './traces';/* Insights */export * from './insights';/* Cache */diff --git a/packages/api/src/langfuse/destinations.ts b/packages/api/src/langfuse/destinations.tsindex 54ccdf122b..1345c3abea 100644--- a/packages/api/src/langfuse/destinations.ts+++ b/packages/api/src/langfuse/destinations.ts@@ -356,14 +356,31 @@ export async function getLangfuseTraceDestinationIds(return destinations.map(({ id }) => id as string);}+/** The trace sampling record a response message stores. */+export type LangfuseTraceMessageFields = {+ langfuseSampled?: boolean;+ langfuseDestinationIds?: string[];+ langfuseRunId?: string;+};++/**+ * The sampling record a response stores for its run's trace. `runId` names the+ * run when it is not the response's own id, as for a failed turn's error row;+ * it is then stored too, so feedback and the trace viewer follow that run.+ */export async function getLangfuseTraceMessageFields(appConfig: AppConfig | undefined,messageId: string,{centralTraceExportEnabled = true,- }: Pick<LangfuseScoreDestinationOptions, 'centralTraceExportEnabled'> = {},-): Promise<{ langfuseSampled: boolean; langfuseDestinationIds?: string[] }> {- const traceId = traceIdForMessage(messageId);+ runId = messageId,+ }: Pick<LangfuseScoreDestinationOptions, 'centralTraceExportEnabled'> & { runId?: string } = {},+): Promise<{+ langfuseSampled: boolean;+ langfuseDestinationIds?: string[];+ langfuseRunId?: string;+}> {+ const traceId = traceIdForMessage(runId);const langfuseSampled = isLangfuseTraceSampled(traceId);return {langfuseSampled,@@ -373,9 +390,35 @@ export async function getLangfuseTraceMessageFields(langfuseSampled,{ centralTraceExportEnabled },),+ ...(runId !== messageId ? { langfuseRunId: runId } : {}),};}+/**+ * The sampling record for a failed turn's error row, which keeps its own id and+ * so names the run that failed. A turn that failed before its run was created+ * has no trace to name, and a destination lookup that fails leaves the row+ * without one rather than failing the error write.+ */+export async function getFailedTurnTraceFields(+ appConfig: AppConfig | undefined,+ {+ messageId,+ runId,+ runCreated,+ }: { messageId: string; runId?: string | null; runCreated: boolean },+): Promise<LangfuseTraceMessageFields> {+ if (!runCreated || typeof runId !== 'string' || runId.length === 0) {+ return {};+ }+ try {+ return await getLangfuseTraceMessageFields(appConfig, messageId, { runId });+ } catch (error) {+ logger.warn('[langfuse] Could not record the failed run trace:', error);+ return {};+ }+}+const centralPublicKey = normalizeString(process.env.LANGFUSE_PUBLIC_KEY);const centralSecretKey = normalizeString(process.env.LANGFUSE_SECRET_KEY);if (centralPublicKey && centralSecretKey) {diff --git a/packages/api/src/langfuse/feedback.spec.ts b/packages/api/src/langfuse/feedback.spec.tsindex b4efa3a085..04ea5dcb40 100644--- a/packages/api/src/langfuse/feedback.spec.ts+++ b/packages/api/src/langfuse/feedback.spec.ts@@ -393,6 +393,53 @@ describe('Langfuse feedback scores', () => {expect(getFetchMock()).toHaveBeenCalledTimes(1);});+ it('records the sampling decision of the run a failed turn stands for', async () => {+ process.env.LANGFUSE_SAMPLE_RATE = '0.5';+ await loadFeedback();+ const { getLangfuseTraceMessageFields } = await import('./destinations');+ const { isLangfuseTraceSampled } = await import('./policy');+ const { traceIdForMessage } = await import('./trace');+ const ids = Array.from({ length: 64 }, (_, index) => `id-${index}`);+ const sampled = (id: string) => isLangfuseTraceSampled(traceIdForMessage(id));+ const runId = ids.find(sampled) as string;+ const rowId = ids.find((id) => !sampled(id)) as string;++ await expect(getLangfuseTraceMessageFields(undefined, rowId, { runId })).resolves.toEqual({+ langfuseSampled: true,+ langfuseDestinationIds: [expect.any(String)],+ langfuseRunId: runId,+ });+ await expect(getLangfuseTraceMessageFields(undefined, runId)).resolves.not.toHaveProperty(+ 'langfuseRunId',+ );+ await expect(getLangfuseTraceMessageFields(undefined, rowId)).resolves.toMatchObject({+ langfuseSampled: false,+ });+ });++ it('names the run of a failed turn only when that run was created', async () => {+ await loadFeedback();+ const { getFailedTurnTraceFields } = await import('./destinations');++ await expect(+ getFailedTurnTraceFields(undefined, {+ messageId: 'user-1_',+ runId: 'run-1',+ runCreated: false,+ }),+ ).resolves.toEqual({});+ await expect(+ getFailedTurnTraceFields(undefined, { messageId: 'user-1_', runId: null, runCreated: true }),+ ).resolves.toEqual({});+ await expect(+ getFailedTurnTraceFields(undefined, {+ messageId: 'user-1_',+ runId: 'run-1',+ runCreated: true,+ }),+ ).resolves.toMatchObject({ langfuseSampled: true, langfuseRunId: 'run-1' });+ });+it('keeps the central destination identity stable when credentials rotate', async () => {const { sendFeedbackScore } = await loadFeedback();const { getLangfuseTraceDestinationIds } = await import('./destinations');diff --git a/packages/api/src/langfuse/identity.ts b/packages/api/src/langfuse/identity.tsindex de1fddb358..a06a0bd856 100644--- a/packages/api/src/langfuse/identity.ts+++ b/packages/api/src/langfuse/identity.ts@@ -39,6 +39,19 @@ function isUserIdField(field: string): field is LangfuseTraceUserIdField {return USER_ID_FIELDS.has(field);}+/**+ * Whether traces are exported under the internal user id: no field is set, or+ * the set field is one the exporter ignores. A user without a value for an+ * allowed field also keeps the internal id, but that is per user and not known+ * from config alone.+ */+export function exportsInternalTraceUserId(+ trace: LangfuseTraceIdentityConfig | undefined,+): boolean {+ const field = trace?.userIdField;+ return field == null || field === DEFAULT_USER_ID_FIELD || !isUserIdField(String(field));+}+function isUserMetadataField(field: unknown): field is LangfuseTraceUserMetadataField {return typeof field === 'string' && USER_METADATA_FIELDS.has(field);}diff --git a/packages/api/src/langfuse/index.ts b/packages/api/src/langfuse/index.tsindex b5461737c8..d7e23bbf5c 100644--- a/packages/api/src/langfuse/index.ts+++ b/packages/api/src/langfuse/index.ts@@ -1,5 +1,6 @@export * from './destinations';export * from './feedback';export * from './policy';+export * from './reader';export * from './trace';export * from './session';diff --git a/packages/api/src/langfuse/reader.spec.ts b/packages/api/src/langfuse/reader.spec.tsnew file mode 100644index 0000000000..20cba287bd--- /dev/null+++ b/packages/api/src/langfuse/reader.spec.ts@@ -0,0 +1,1659 @@+import { resolveTraceViewerConfig } from 'librechat-data-provider';+import type { AppConfig, ConversationTraceRefs } from '@librechat/data-schemas';+import type { LangfuseScoreDestination } from './destinations';+import type { TraceQuery } from '~/traces/types';++process.env.CREDS_KEY =+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';++jest.mock(+ '@librechat/data-schemas',+ () => ({+ logger: { debug: jest.fn(), error: jest.fn(), warn: jest.fn(), info: jest.fn() },+ }),+ { virtual: true },+);++jest.mock('~/admin/secrets', () => ({+ decryptConfigSecret: jest.fn((value: string) => value),+}));++import { createLangfuseTraceReader, resolveLangfuseReadDestinations } from './reader';+import { getLangfuseDestinationId } from './destinations';+import { TraceReadError } from '~/traces/types';+import { traceIdForMessage } from './trace';++const NOW = Date.UTC(2026, 8, 12, 12, 0, 0);+const FIRST_MESSAGE_AT = new Date(Date.UTC(2026, 8, 12, 11, 0, 0));+const RESPONSE_TRACE = traceIdForMessage('response-1');+const TITLE_TRACE = traceIdForMessage('title-response-1');+const FOREIGN_TRACE = traceIdForMessage('someone-elses-response');++const central: LangfuseScoreDestination = {+ id: 'central-id',+ name: 'central',+ baseUrl: 'https://central.langfuse.test',+ authorization: 'Basic central',+};+const connection: LangfuseScoreDestination = {+ id: 'connection-id',+ name: 'connection',+ baseUrl: 'https://tenant.langfuse.test/base/',+ authorization: 'Basic tenant',+ headers: { 'X-Gateway': 'token' },+};++function createRefs(overrides: Partial<ConversationTraceRefs> = {}): ConversationTraceRefs {+ return {+ firstMessageAt: FIRST_MESSAGE_AT,+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['connection-id'] }],+ ...overrides,+ };+}++function createQuery(overrides: Partial<TraceQuery> = {}): TraceQuery {+ return {+ userId: 'owner',+ conversationId: 'convo-1',+ settings: resolveTraceViewerConfig({ enabled: true }),+ ...overrides,+ };+}++function jsonResponse(body: unknown, status = 200): Response {+ return new Response(JSON.stringify(body), {+ status,+ headers: { 'Content-Type': 'application/json' },+ });+}++function observation(overrides: Record<string, unknown> = {}): Record<string, unknown> {+ return {+ id: 'obs-root',+ traceId: RESPONSE_TRACE,+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ projectId: 'project',+ parentObservationId: null,+ type: 'AGENT',+ name: 'AgentGraph',+ level: 'DEFAULT',+ statusMessage: '',+ ...overrides,+ };+}++type RoutedRequest = { origin: string; probe: boolean; traceIds: string[]; cursor: string | null };++function routeOf(url: string): RoutedRequest {+ const parsed = new URL(url);+ const filter: FilterCondition[] = JSON.parse(parsed.searchParams.get('filter') ?? '[]');+ return {+ origin: parsed.origin,+ probe: filter.some(({ column }) => column === 'parentObservationId'),+ traceIds: (filter.find(({ column }) => column === 'traceId')?.value as string[]) ?? [],+ cursor: parsed.searchParams.get('cursor'),+ };+}++function setup({+ refs = createRefs(),+ destinations = [central, connection],+ responses = [] as Array<Response | Error>,+ route,+}: {+ refs?: ConversationTraceRefs;+ destinations?: LangfuseScoreDestination[];+ responses?: Array<Response | Error>;+ /** Answers each Langfuse request by what it asks for, instead of by arrival order. */+ route?: (request: RoutedRequest) => Response | Error;+} = {}) {+ const fetchMock = jest.fn(async (url: string, _init: RequestInit): Promise<Response> => {+ const next = route ? route(routeOf(url)) : responses.shift();+ if (next == null) {+ throw new Error('unexpected fetch');+ }+ if (next instanceof Error) {+ throw next;+ }+ return next;+ });+ /** Same paging contract as the data-schemas query, which has its own database spec. */+ const getConversationTraceRefs = jest.fn(+ async ({+ messageId,+ through,+ limit,+ }: {+ messageId?: string;+ through?: { messageId: string; orderKey: string };+ limit?: number;+ } = {}) => {+ const all = refs.sampledMessages.map((message) => ({+ ...message,+ orderKey: `key:${message.messageId}`,+ }));+ if (messageId != null) {+ return {+ ...refs,+ sampledMessages: all.filter((message) => message.messageId === messageId),+ };+ }+ const end =+ through != null+ ? all.findIndex(+ (message) =>+ message.messageId === through.messageId && message.orderKey === through.orderKey,+ )+ : all.length - 1;+ if (through != null && end === -1) {+ return { ...refs, sampledMessages: [] };+ }+ const start = limit != null ? Math.max(0, end - limit + 1) : 0;+ return { ...refs, sampledMessages: all.slice(start, end + 1) };+ },+ );+ /** Same rule as the data-schemas query, which has its own database spec. */+ const hasSampledTraceMessage = jest.fn(async ({ destinationIds }: { destinationIds: string[] }) =>+ refs.sampledMessages.some(+ ({ langfuseDestinationIds }) =>+ langfuseDestinationIds == null ||+ langfuseDestinationIds.some((id) => destinationIds.includes(id)),+ ),+ );+ const resolveDestinations = jest.fn(async () => destinations);+ const reader = createLangfuseTraceReader({+ getConversationTraceRefs,+ hasSampledTraceMessage,+ resolveDestinations,+ fetch: fetchMock,+ now: () => NOW,+ });+ return {+ reader,+ fetchMock,+ getConversationTraceRefs,+ hasSampledTraceMessage,+ resolveDestinations,+ };+}++function requestedUrl(fetchMock: jest.Mock, call = 0): URL {+ return new URL(String(fetchMock.mock.calls[call][0]));+}++type FilterCondition = { column: string; operator: string; value: string | string[] };++function requestedFilter(fetchMock: jest.Mock, call = 0): FilterCondition[] {+ return JSON.parse(requestedUrl(fetchMock, call).searchParams.get('filter') ?? '[]');+}++function requestedTraceIds(fetchMock: jest.Mock, call = 0): string[] {+ const condition = requestedFilter(fetchMock, call).find(({ column }) => column === 'traceId');+ return (condition?.value as string[]) ?? [];+}++function tracesOf(...messageIds: string[]): string[] {+ return messageIds.flatMap((id) => [traceIdForMessage(id), traceIdForMessage(`title-${id}`)]);+}++const TENANT = 'https://tenant.langfuse.test';+const CENTRAL = 'https://central.langfuse.test';++/** A probe answer: one root observation per trace the project holds. */+function rootsFor(request: RoutedRequest, ...messageIds: string[]): Response {+ const held = new Set(messageIds.map((id) => traceIdForMessage(id)));+ return jsonResponse({+ data: request.traceIds+ .filter((traceId) => held.has(traceId))+ .map((traceId) => ({ id: `root-${traceId}`, traceId })),+ });+}++/** A read answer: one observation per requested turn the project holds. */+function recordsFor(request: RoutedRequest, ...messageIds: string[]): Response {+ return jsonResponse({+ data: messageIds+ .filter((id) => request.traceIds.includes(traceIdForMessage(id)))+ .map((id) => observation({ id, traceId: traceIdForMessage(id) })),+ });+}++/** Every request, as a readable line, in the order the reader made them. */+function calls(fetchMock: jest.Mock): string[] {+ return fetchMock.mock.calls.map(([url]) => {+ const request = routeOf(String(url));+ const host = request.origin === TENANT ? 'tenant' : 'central';+ return `${request.probe ? 'probe' : 'read'} ${host}${request.cursor ? ` @${request.cursor}` : ''}`;+ });+}++function encodeTestCursor(cursor: Record<string, unknown>): string {+ return Buffer.from(JSON.stringify(cursor)).toString('base64url');+}++describe('createLangfuseTraceReader', () => {+ describe('isAvailable', () => {+ it('is unavailable without a sampled response and never reads Langfuse', async () => {+ const { reader, fetchMock, getConversationTraceRefs } = setup({+ refs: createRefs({ sampledMessages: [] }),+ });++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: false });+ expect(getConversationTraceRefs).not.toHaveBeenCalled();+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it('is unavailable when no configured destination received the trace', async () => {+ const { reader } = setup({+ refs: createRefs({+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['retired-id'] }],+ }),+ });++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: false });+ });++ it('stays available when only newer responses reached a readable destination', async () => {+ const { reader, hasSampledTraceMessage } = setup({+ refs: createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['retired-id'] },+ { messageId: 'response-1', langfuseDestinationIds: ['connection-id'] },+ ],+ }),+ });++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: true });+ expect(hasSampledTraceMessage).toHaveBeenCalledWith({+ user: 'owner',+ conversationId: 'convo-1',+ destinationIds: ['central-id', 'connection-id'],+ });+ });++ it('explains once when no destination can read traces at all', async () => {+ const { reader, hasSampledTraceMessage } = setup({ destinations: [] });+ const { logger } = jest.requireMock<{ logger: { warn: jest.Mock } }>(+ '@librechat/data-schemas',+ );+ logger.warn.mockClear();++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: false });+ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: false });++ expect(hasSampledTraceMessage).not.toHaveBeenCalled();+ expect(logger.warn).toHaveBeenCalledTimes(1);+ expect(logger.warn.mock.calls[0][0]).toContain('no destination with read credentials');+ });++ it('answers from one existence query without loading every response or reading Langfuse', async () => {+ const { reader, fetchMock, getConversationTraceRefs, hasSampledTraceMessage } = setup();++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: true });+ expect(hasSampledTraceMessage).toHaveBeenCalledTimes(1);+ expect(getConversationTraceRefs).not.toHaveBeenCalled();+ expect(fetchMock).not.toHaveBeenCalled();+ });+ });++ describe('listRecords', () => {+ it('reads the session from the recorded destination with its credentials and window', async () => {+ const { reader, fetchMock } = setup({ responses: [jsonResponse({ data: [], meta: {} })] });++ await expect(reader.listRecords(createQuery())).resolves.toEqual({+ records: [],+ sourceId: 'connection-id',+ });++ const url = requestedUrl(fetchMock);+ expect(url.origin + url.pathname).toBe(+ 'https://tenant.langfuse.test/base/api/public/v2/observations',+ );+ expect(Object.fromEntries(url.searchParams)).toEqual({+ fields: 'core,basic,time,model,usage',+ limit: '1000',+ filter: expect.any(String),+ });+ expect(requestedFilter(fetchMock)).toEqual([+ { type: 'string', column: 'sessionId', operator: '=', value: 'convo-1' },+ { type: 'stringOptions', column: 'userId', operator: 'any of', value: ['owner'] },+ {+ type: 'stringOptions',+ column: 'traceId',+ operator: 'any of',+ value: [RESPONSE_TRACE, TITLE_TRACE],+ },+ { type: 'datetime', column: 'startTime', operator: '<', value: '2026-09-12T12:10:00.000Z' },+ {+ type: 'datetime',+ column: 'startTime',+ operator: '>=',+ value: '2026-09-12T10:50:00.000Z',+ },+ ]);+ const init = fetchMock.mock.calls[0][1] as RequestInit;+ expect(new Headers(init.headers).get('Authorization')).toBe('Basic tenant');+ expect(new Headers(init.headers).get('X-Gateway')).toBe('token');+ expect(init.redirect).toBe('error');+ });++ it('reads central when it is the only destination recorded on the messages', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['central-id'] }],+ }),+ responses: [jsonResponse({ data: [] })],+ });++ await reader.listRecords(createQuery());++ expect(requestedUrl(fetchMock).origin).toBe('https://central.langfuse.test');+ });++ it('reads the project holding the newest turn first after a conversation moved projects', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['central-id'] },+ { messageId: 'response-1', langfuseDestinationIds: ['central-id'] },+ { messageId: 'response-2', langfuseDestinationIds: ['connection-id'] },+ ],+ });+ const { reader, fetchMock } = setup({+ refs,+ responses: [+ jsonResponse({+ data: [observation({ id: 'newest', traceId: traceIdForMessage('response-2') })],+ }),+ ],+ });++ const page = await reader.listRecords(createQuery());++ expect(requestedUrl(fetchMock).origin).toBe('https://tenant.langfuse.test');+ expect(page).toMatchObject({ sourceId: 'connection-id', records: [{ id: 'newest' }] });++ const later = setup({ refs, responses: [jsonResponse({ data: [] })] });+ await later.reader.listRecords({ ...createQuery(), cursor: page.nextCursor });++ expect(requestedUrl(later.fetchMock).origin).toBe('https://central.langfuse.test');+ });++ it('asks for only the observations exported under the requesting user id', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const { reader, fetchMock } = setup({+ refs,+ route: (request) =>+ request.probe ? rootsFor(request, 'response-1') : recordsFor(request, 'response-1'),+ });++ await reader.listRecords(createQuery());+ await reader.getRecord({ ...createQuery(), recordId: 'response-1', messageId: 'response-1' });++ const owner = {+ type: 'stringOptions',+ column: 'userId',+ operator: 'any of',+ value: ['owner'],+ };+ expect(fetchMock.mock.calls.length).toBeGreaterThanOrEqual(4);+ fetchMock.mock.calls.forEach((_call, index) => {+ expect(requestedFilter(fetchMock, index)).toContainEqual(owner);+ });+ });++ it('shows no trace while traces are exported under a user field that is not the internal id', async () => {+ const { reader, fetchMock, hasSampledTraceMessage } = setup({+ responses: [jsonResponse({ data: [observation()] })],+ });+ const query = createQuery({+ appConfig: { langfuse: { trace: { userIdField: 'name' } } } as AppConfig,+ });++ await expect(reader.isAvailable(query)).resolves.toEqual({ available: false });+ await expect(reader.listRecords(query)).rejects.toMatchObject({ code: 'not_found' });+ await expect(+ reader.getRecord({ ...query, recordId: 'obs-root', messageId: 'response-1' }),+ ).resolves.toBeNull();+ expect(hasSampledTraceMessage).not.toHaveBeenCalled();+ expect(fetchMock).not.toHaveBeenCalled();++ const ignoredField = createQuery({+ appConfig: {+ langfuse: { trace: { userIdField: 'not-a-user-field' } },+ } as unknown as AppConfig,+ });+ await expect(reader.isAvailable(ignoredField)).resolves.toEqual({ available: true });+ });++ it('reads a turn only its preferred project holds without asking any project first', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['connection-id'] }],+ }),+ route: (request) => recordsFor(request, 'response-1'),+ });++ await reader.listRecords(createQuery());++ expect(calls(fetchMock)).toEqual(['read tenant']);+ });++ it('reads a turn two projects could hold from the preferred one that holds it', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const both = setup({+ refs,+ route: (request) =>+ request.probe ? rootsFor(request, 'response-1') : recordsFor(request, 'response-1'),+ });+ const onlyCentral = setup({+ refs,+ route: (request) => {+ const held = request.origin === CENTRAL ? ['response-1'] : [];+ return request.probe ? rootsFor(request, ...held) : recordsFor(request, ...held);+ },+ });++ await both.reader.listRecords(createQuery());+ const page = await onlyCentral.reader.listRecords(createQuery());++ expect(calls(both.fetchMock)).toEqual(['probe tenant', 'probe central', 'read tenant']);+ expect(calls(onlyCentral.fetchMock)).toEqual([+ 'probe tenant',+ 'probe central',+ 'read central',+ ]);+ expect(page).toMatchObject({ sourceId: 'central-id', records: [{ id: 'response-1' }] });+ });++ it('pages turns in order whichever projects hold them', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['central-id'] },+ { messageId: 'legacy-1' },+ { messageId: 'response-2', langfuseDestinationIds: ['connection-id'] },+ { messageId: 'response-3', langfuseDestinationIds: ['central-id'] },+ { messageId: 'response-4', langfuseDestinationIds: ['central-id'] },+ ],+ });+ const held: Record<string, string[]> = {+ [TENANT]: ['response-2'],+ [CENTRAL]: ['response-0', 'legacy-1', 'response-3', 'response-4'],+ };+ const pages: Array<{ sourceId?: string; records: string[] }> = [];+ let cursor: string | undefined;+ do {+ const { reader } = setup({+ refs,+ route: (request) =>+ request.probe+ ? rootsFor(request, ...held[request.origin])+ : recordsFor(request, ...held[request.origin]),+ });+ const page = await reader.listRecords({ ...createQuery(), cursor });+ pages.push({ sourceId: page.sourceId, records: page.records.map(({ id }) => id).sort() });+ cursor = page.nextCursor;+ } while (cursor);++ expect(pages).toEqual([+ { sourceId: 'central-id', records: ['response-3', 'response-4'] },+ { sourceId: 'connection-id', records: ['response-2'] },+ { sourceId: 'central-id', records: ['legacy-1', 'response-0'] },+ ]);+ });++ it('reads a title run from the project that holds it when it landed apart from its run', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const titleTrace = traceIdForMessage('title-response-1');+ const route = (request: RoutedRequest) => {+ const traceIds =+ request.origin === TENANT ? [traceIdForMessage('response-1')] : [titleTrace];+ const asked = traceIds.filter((traceId) => request.traceIds.includes(traceId));+ return jsonResponse({+ data: asked.map((traceId) =>+ request.probe+ ? { id: `root-${traceId}`, traceId }+ : observation({ id: traceId === titleTrace ? 'title' : 'run', traceId }),+ ),+ });+ };+ const pages: Array<{ sourceId?: string; records: string[] }> = [];+ let cursor: string | undefined;+ do {+ const { reader } = setup({ refs, route });+ const page = await reader.listRecords({ ...createQuery(), cursor });+ pages.push({ sourceId: page.sourceId, records: page.records.map(({ id }) => id) });+ cursor = page.nextCursor;+ } while (cursor);++ expect(pages).toEqual([+ { sourceId: 'connection-id', records: ['run'] },+ { sourceId: 'central-id', records: ['title'] },+ ]);+ });++ it('reads a title run that started after its run first when the two sit in different projects', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['connection-id'] },+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const runTrace = traceIdForMessage('response-1');+ const titleTrace = traceIdForMessage('title-response-1');+ const olderTrace = traceIdForMessage('response-0');+ const held: Record<string, Record<string, string>> = {+ [TENANT]: {+ [runTrace]: '2026-09-12T11:30:00.000Z',+ [olderTrace]: '2026-09-12T11:20:00.000Z',+ },+ [CENTRAL]: { [titleTrace]: '2026-09-12T11:30:09.000Z' },+ };+ const route = (request: RoutedRequest) =>+ jsonResponse({+ data: Object.entries(held[request.origin])+ .filter(([traceId]) => request.traceIds.includes(traceId))+ .map(([traceId, startTime]) =>+ request.probe+ ? { id: `root-${traceId}`, traceId, startTime }+ : observation({ id: traceId, traceId, startTime }),+ ),+ });+ const pages: string[][] = [];+ let cursor: string | undefined;+ do {+ const { reader } = setup({ refs, route });+ const page = await reader.listRecords({ ...createQuery(), cursor });+ pages.push(page.records.map(({ id }) => id));+ cursor = page.nextCursor;+ } while (cursor);++ expect(pages).toEqual([[titleTrace], [runTrace, olderTrace]]);+ });++ it('reports a failed read of a title run a probe found, instead of dropping it', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const runTrace = traceIdForMessage('response-1');+ const titleTrace = traceIdForMessage('title-response-1');+ const route = (request: RoutedRequest) => {+ const held = request.origin === TENANT ? runTrace : titleTrace;+ if (request.probe) {+ return jsonResponse({+ data: request.traceIds.includes(held) ? [{ id: `root-${held}`, traceId: held }] : [],+ });+ }+ if (request.origin === CENTRAL) {+ return jsonResponse({ message: 'down' }, 503);+ }+ return jsonResponse({+ data: request.traceIds.includes(runTrace)+ ? [observation({ id: 'run', traceId: runTrace })]+ : [],+ });+ };+ const first = setup({ refs, route });++ const page = await first.reader.listRecords(createQuery());++ expect(page.records.map(({ id }) => id)).toEqual(['run']);+ const later = setup({ refs, route });+ await expect(+ later.reader.listRecords({ ...createQuery(), cursor: page.nextCursor }),+ ).rejects.toMatchObject({ code: 'upstream_error' });+ });++ it('loads sampled responses a segment at a time, ending at the turn a page starts from', async () => {+ const sampledMessages = Array.from({ length: 60 }, (_, index) => ({+ messageId: `response-${index}`,+ langfuseDestinationIds: ['connection-id'],+ }));+ const refs = createRefs({ sampledMessages });+ const first = setup({ refs, route: (request) => recordsFor(request, 'response-59') });++ const page = await first.reader.listRecords(createQuery());++ expect(first.getConversationTraceRefs).toHaveBeenCalledWith(+ expect.objectContaining({ limit: 51 }),+ );+ expect(first.getConversationTraceRefs.mock.calls[0][0]).not.toHaveProperty('through');+ const later = setup({ refs, route: (request) => recordsFor(request, 'response-9') });+ await later.reader.listRecords({ ...createQuery(), cursor: page.nextCursor });++ expect(later.getConversationTraceRefs).toHaveBeenCalledWith(+ expect.objectContaining({+ through: { messageId: 'response-9', orderKey: 'key:response-9' },+ limit: 51,+ }),+ );+ expect(requestedTraceIds(later.fetchMock).sort()).toEqual(+ tracesOf(...sampledMessages.slice(0, 10).map(({ messageId }) => messageId)).sort(),+ );+ });++ it('moves to the next older window of responses within a request when a window has no records', async () => {+ const sampledMessages = Array.from({ length: 60 }, (_, index) => ({+ messageId: `response-${index}`,+ langfuseDestinationIds: ['connection-id'],+ }));+ const { reader, getConversationTraceRefs } = setup({+ refs: createRefs({ sampledMessages }),+ route: (request) => recordsFor(request, 'response-3'),+ });++ const page = await reader.listRecords(createQuery());++ expect(page.records.map(({ id }) => id)).toEqual(['response-3']);+ expect(page.nextCursor).toBeUndefined();+ expect(+ getConversationTraceRefs.mock.calls.map(([input]) => input?.through?.messageId),+ ).toEqual([undefined, 'response-9']);+ });++ it('reports a list read whose cursor repeats instead of serving the same records again', async () => {+ const { reader } = setup({+ route: () =>+ jsonResponse({ data: [observation({ id: 'same' })], meta: { cursor: 'same' } }),+ });++ await expect(+ reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 2000 }) }),+ ),+ ).rejects.toMatchObject({ code: 'upstream_error' });+ });++ it('treats a root lookup that repeats its cursor as a failed project', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'legacy-response' }] }),+ route: (request) => {+ if (request.origin === TENANT && request.probe) {+ return jsonResponse({+ data: [{ id: 'root', traceId: traceIdForMessage('legacy-response') }],+ meta: { cursor: 'same' },+ });+ }+ return request.probe+ ? rootsFor(request, 'legacy-response')+ : recordsFor(request, 'legacy-response');+ },+ });++ const page = await reader.listRecords(createQuery());++ expect(calls(fetchMock)).toEqual([+ 'probe tenant',+ 'probe tenant @same',+ 'probe central',+ 'read central',+ ]);+ expect(page).toMatchObject({ sourceId: 'central-id' });+ });++ it('bounds how many turns one read asks a project for', async () => {+ const sampledMessages = Array.from({ length: 51 }, (_, index) => ({+ messageId: `response-${index}`,+ langfuseDestinationIds: ['connection-id'],+ }));+ const refs = createRefs({ sampledMessages });+ const first = setup({ refs, responses: [jsonResponse({ data: [observation()] })] });++ const page = await first.reader.listRecords(createQuery());++ expect(requestedTraceIds(first.fetchMock).sort()).toEqual(+ tracesOf(...sampledMessages.slice(1).map(({ messageId }) => messageId)).sort(),+ );+ const later = setup({ refs, responses: [jsonResponse({ data: [] })] });+ await later.reader.listRecords({ ...createQuery(), cursor: page.nextCursor });+ expect(requestedTraceIds(later.fetchMock)).toEqual(tracesOf('response-0'));+ });++ it('fails over when the preferred project fails to answer or to read', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const probeFails = setup({+ refs,+ route: (request) => {+ if (request.origin === TENANT) {+ return jsonResponse({ message: 'expired key' }, 401);+ }+ return request.probe+ ? rootsFor(request, 'response-1')+ : recordsFor(request, 'response-1');+ },+ });+ const readFails = setup({+ refs,+ route: (request) => {+ if (request.probe) {+ return rootsFor(request, 'response-1');+ }+ return request.origin === TENANT+ ? jsonResponse({ message: 'down' }, 503)+ : recordsFor(request, 'response-1');+ },+ });++ const afterProbe = await probeFails.reader.listRecords(createQuery());+ const afterRead = await readFails.reader.listRecords(createQuery());++ expect(calls(probeFails.fetchMock)).toEqual([+ 'probe tenant',+ 'probe central',+ 'read central',+ ]);+ expect(calls(readFails.fetchMock)).toEqual([+ 'probe tenant',+ 'probe central',+ 'read tenant',+ 'probe central',+ 'read central',+ ]);+ expect(afterProbe).toMatchObject({ sourceId: 'central-id', records: [{ id: 'response-1' }] });+ expect(afterRead).toMatchObject({ sourceId: 'central-id', records: [{ id: 'response-1' }] });+ });++ it('reports a failure that could hide a turn instead of a partial or empty trace', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['central-id', 'connection-id'] },+ { messageId: 'response-1', langfuseDestinationIds: ['connection-id'] },+ ],+ });+ const route = (request: RoutedRequest) => {+ if (request.origin === CENTRAL) {+ return jsonResponse({ message: 'down' }, 503);+ }+ return request.probe ? rootsFor(request) : recordsFor(request, 'response-1');+ };+ const first = setup({ refs, route });++ const page = await first.reader.listRecords(createQuery());++ expect(page.records.map(({ id }) => id)).toEqual(['response-1']);+ const later = setup({ refs, route });+ await expect(+ later.reader.listRecords({ ...createQuery(), cursor: page.nextCursor }),+ ).rejects.toMatchObject({ code: 'upstream_error' });+ });++ it('reports a failed continuation instead of replaying its segment from another project', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ });+ const first = setup({+ refs,+ route: (request) =>+ request.probe+ ? rootsFor(request, 'response-1')+ : jsonResponse({ data: [observation({ id: 'a' })], meta: { cursor: 'next' } }),+ });+ const { nextCursor } = await first.reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 1 }) }),+ );+ const later = setup({+ refs,+ route: (request) => {+ if (request.probe) {+ return rootsFor(request, 'response-1');+ }+ return request.origin === TENANT+ ? jsonResponse({ message: 'down' }, 503)+ : recordsFor(request, 'response-1');+ },+ });++ await expect(+ later.reader.listRecords({ ...createQuery(), cursor: nextCursor }),+ ).rejects.toMatchObject({ code: 'upstream_error' });+ expect(calls(later.fetchMock)).not.toContain('read central');+ });+ it('reads a turn no project shows a root for yet from the preferred one, since a running turn has none', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'legacy-response' }] }),+ route: (request) =>+ request.probe+ ? rootsFor(request)+ : jsonResponse({+ data: [+ observation({+ id: 'streaming-call',+ parentObservationId: 'root-not-exported',+ traceId: traceIdForMessage('legacy-response'),+ endTime: null,+ }),+ ],+ }),+ });++ const page = await reader.listRecords(createQuery());++ expect(calls(fetchMock)).toEqual(['probe tenant', 'probe central', 'read tenant']);+ expect(page.records).toEqual([+ expect.objectContaining({ id: 'streaming-call', status: 'running' }),+ ]);+ });++ it('reports a continuation the trace no longer matches, or one Langfuse rejects, as changed', async () => {+ const refs = createRefs({+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['connection-id'] }],+ });+ const stale = encodeTestCursor({+ m: 'response-1',+ p: 'key:response-1',+ s: 'connection-id',+ c: 'old',+ h: 'other',+ });+ const staleSegment = setup({ refs, route: (request) => recordsFor(request, 'response-1') });+ const rejected = setup({+ refs,+ route: (request) =>+ request.cursor != null+ ? jsonResponse({ message: 'bad cursor' }, 400)+ : recordsFor(request, 'response-1'),+ });+ const first = setup({+ refs,+ responses: [jsonResponse({ data: [observation({ id: 'a' })], meta: { cursor: 'next' } })],+ });+ const { nextCursor } = await first.reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 1 }) }),+ );++ await expect(+ staleSegment.reader.listRecords({ ...createQuery(), cursor: stale }),+ ).rejects.toMatchObject({ code: 'invalid_request' });+ await expect(+ rejected.reader.listRecords({ ...createQuery(), cursor: nextCursor }),+ ).rejects.toMatchObject({ code: 'invalid_request' });+ expect(calls(staleSegment.fetchMock)).toEqual([]);+ expect(calls(rejected.fetchMock)).toEqual(['read tenant @next']);+ });+ it('reads a failed turn from the trace of the run its error row stands for', async () => {+ const runTrace = traceIdForMessage('run-1');+ const { reader, fetchMock } = setup({+ refs: createRefs({+ sampledMessages: [+ {+ messageId: 'user-1_',+ langfuseRunId: 'run-1',+ langfuseDestinationIds: ['connection-id'],+ },+ ],+ }),+ responses: [+ jsonResponse({+ data: [+ observation({ id: 'failed-call', traceId: runTrace, level: 'ERROR' }),+ observation({ id: 'row-id-trace', traceId: traceIdForMessage('user-1_') }),+ ],+ }),+ ],+ });++ const page = await reader.listRecords(createQuery());++ expect(requestedTraceIds(fetchMock)).toEqual(tracesOf('run-1'));+ expect(page.records).toEqual([+ expect.objectContaining({ id: 'failed-call', messageId: 'user-1_', status: 'error' }),+ ]);+ });++ it('reports a page whose observations all fail to parse as an upstream failure', async () => {+ const { reader } = setup({+ responses: [jsonResponse({ data: [{ id: 'renamed-fields', trace_id: RESPONSE_TRACE }] })],+ });++ await expect(reader.listRecords(createQuery())).rejects.toMatchObject({+ code: 'upstream_error',+ });+ });++ it('passes the tenant scope to both conversation reads', async () => {+ const { reader, getConversationTraceRefs, hasSampledTraceMessage } = setup({+ responses: [jsonResponse({ data: [observation()] })],+ });++ await reader.isAvailable(createQuery({ tenantId: 'tenant-a' }));+ await reader.listRecords(createQuery({ tenantId: 'tenant-a' }));++ expect(hasSampledTraceMessage).toHaveBeenCalledWith(+ expect.objectContaining({ tenantId: 'tenant-a' }),+ );+ expect(getConversationTraceRefs).toHaveBeenCalledWith(+ expect.objectContaining({ tenantId: 'tenant-a' }),+ );+ });++ it('treats two credentials for one project as one source instead of replaying its page', async () => {+ const centralAlias = { ...central, id: 'connection-id', authorization: 'Basic alias' };+ const { reader, fetchMock } = setup({+ destinations: [centralAlias, connection],+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [jsonResponse({ data: [observation()] })],+ });++ const page = await reader.listRecords(createQuery());++ expect(page.nextCursor).toBeUndefined();+ expect(fetchMock).toHaveBeenCalledTimes(1);+ });++ it('normalizes owned observations and drops traces the user does not own', async () => {+ const { reader } = setup({+ responses: [+ jsonResponse({+ data: [+ observation(),+ observation({+ id: 'obs-llm',+ parentObservationId: 'obs-root',+ type: 'GENERATION',+ name: 'llm',+ model: 'claude-haiku-4-5',+ completionStartTime: '2026-09-12T11:30:01.000Z',+ usageDetails: {+ input: 120,+ output: 30,+ total: 150,+ output_reasoning: 10,+ input_cache_read: 80,+ input_cache_creation: 40,+ },+ totalCost: 0.0042,+ }),+ observation({+ id: 'obs-tool',+ parentObservationId: 'obs-root',+ type: 'TOOL',+ name: 'web_search',+ endTime: null,+ }),+ observation({+ id: 'obs-failed',+ parentObservationId: 'obs-root',+ type: 'CHAIN',+ name: 'tool-dispatch',+ level: 'ERROR',+ statusMessage: 'Error: Host tool execution failed',+ }),+ observation({+ id: 'obs-title',+ traceId: TITLE_TRACE,+ type: 'CHAIN',+ name: '',+ providedModelName: 'title-model',+ }),+ observation({ id: 'obs-foreign', traceId: FOREIGN_TRACE }),+ { id: 'malformed' },+ ],+ }),+ ],+ });++ const { records } = await reader.listRecords(createQuery());++ expect(records).toEqual([+ {+ id: 'obs-root',+ traceId: RESPONSE_TRACE,+ messageId: 'response-1',+ parentId: null,+ kind: 'agent',+ name: 'AgentGraph',+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ status: 'ok',+ },+ {+ id: 'obs-llm',+ traceId: RESPONSE_TRACE,+ messageId: 'response-1',+ parentId: 'obs-root',+ kind: 'generation',+ name: 'llm',+ model: 'claude-haiku-4-5',+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ completionStartTime: '2026-09-12T11:30:01.000Z',+ status: 'ok',+ usage: {+ input: 120,+ output: 30,+ total: 150,+ reasoning: 10,+ cacheRead: 80,+ cacheWrite: 40,+ },+ cost: 0.0042,+ },+ {+ id: 'obs-tool',+ traceId: RESPONSE_TRACE,+ messageId: 'response-1',+ parentId: 'obs-root',+ kind: 'tool',+ name: 'web_search',+ startTime: '2026-09-12T11:30:00.000Z',+ status: 'running',+ },+ {+ id: 'obs-failed',+ traceId: RESPONSE_TRACE,+ messageId: 'response-1',+ parentId: 'obs-root',+ kind: 'span',+ name: 'tool-dispatch',+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ status: 'error',+ statusMessage: 'Error: Host tool execution failed',+ },+ {+ id: 'obs-title',+ traceId: TITLE_TRACE,+ messageId: 'response-1',+ parentId: null,+ kind: 'span',+ name: 'chain',+ model: 'title-model',+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ status: 'ok',+ },+ ]);+ });++ it('follows Langfuse cursors up to maxRecords and returns the next cursor', async () => {+ const { reader, fetchMock } = setup({+ responses: [+ jsonResponse({+ data: [observation({ id: 'a' }), observation({ id: 'b' })],+ meta: { cursor: 'cursor-1' },+ }),+ jsonResponse({ data: [observation({ id: 'c' })], meta: { cursor: 'cursor-2' } }),+ ],+ });++ const page = await reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 3 }) }),+ );++ expect(page.records.map(({ id }) => id)).toEqual(['a', 'b', 'c']);+ expect(JSON.parse(Buffer.from(page.nextCursor ?? '', 'base64url').toString())).toEqual({+ m: 'response-1',+ p: 'key:response-1',+ s: 'connection-id',+ c: 'cursor-2',+ h: expect.any(String),+ });+ expect(requestedUrl(fetchMock, 0).searchParams.get('limit')).toBe('3');+ expect(requestedUrl(fetchMock, 0).searchParams.has('cursor')).toBe(false);+ expect(requestedUrl(fetchMock, 1).searchParams.get('limit')).toBe('1');+ expect(requestedUrl(fetchMock, 1).searchParams.get('cursor')).toBe('cursor-1');+ });++ it('continues a page from the same segment after newer turns arrive', async () => {+ const first = setup({+ responses: [jsonResponse({ data: [observation({ id: 'a' })], meta: { cursor: 'next' } })],+ refs: createRefs({+ sampledMessages: [{ messageId: 'response-1', langfuseDestinationIds: ['central-id'] }],+ }),+ });+ const { nextCursor, sourceId } = await first.reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 1 }) }),+ );+ expect(sourceId).toBe('central-id');++ const later = setup({+ responses: [jsonResponse({ data: [observation({ id: 'b' })], meta: { cursor: null } })],+ refs: createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id'] },+ { messageId: 'response-2', langfuseDestinationIds: ['connection-id'] },+ { messageId: 'response-3', langfuseDestinationIds: ['connection-id'] },+ ],+ }),+ });+ const page = await later.reader.listRecords({ ...createQuery(), cursor: nextCursor });++ expect(page).toMatchObject({ sourceId: 'central-id', records: [{ id: 'b' }] });+ expect(page.nextCursor).toBeUndefined();+ expect(requestedUrl(later.fetchMock).origin).toBe('https://central.langfuse.test');+ expect(requestedTraceIds(later.fetchMock)).toEqual(tracesOf('response-1'));+ });++ it('keeps paging a project whose id resolved after the first page', async () => {+ const unresolvedCentral = { ...central, id: undefined };+ const first = setup({+ destinations: [unresolvedCentral],+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [jsonResponse({ data: [observation({ id: 'a' })], meta: { cursor: 'next' } })],+ });+ const { nextCursor, sourceId } = await first.reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 1 }) }),+ );+ const later = setup({+ destinations: [central],+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [jsonResponse({ data: [observation({ id: 'b' })] })],+ });++ const page = await later.reader.listRecords({ ...createQuery(), cursor: nextCursor });++ expect(sourceId).toBe('name:central');+ expect(page.records.map(({ id }) => id)).toEqual(['b']);+ });++ it('rejects a forged cursor, one without a position and a turn the conversation no longer has', async () => {+ const { reader, fetchMock } = setup();++ for (const cursor of [+ 'bm90IGpzb24',+ encodeTestCursor({ m: 'response-1' }),+ encodeTestCursor({ m: 'deleted-response', p: 'key:deleted-response' }),+ ]) {+ await expect(reader.listRecords({ ...createQuery(), cursor })).rejects.toMatchObject({+ code: 'invalid_request',+ });+ }+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it('reports a conversation without an eligible trace as not found', async () => {+ const { reader, fetchMock } = setup({ refs: createRefs({ sampledMessages: [] }) });++ await expect(reader.listRecords(createQuery())).rejects.toMatchObject({ code: 'not_found' });+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it.each([+ [401, 'unauthorized'],+ [403, 'unauthorized'],+ [404, 'unsupported'],+ [429, 'rate_limited'],+ [500, 'upstream_error'],+ [400, 'upstream_error'],+ ])('maps a Langfuse %s to %s', async (status, code) => {+ const failure = jsonResponse({ message: 'nope' }, status);+ const { reader } = setup({ responses: [failure] });++ const error = await reader.listRecords(createQuery()).catch((caught: unknown) => caught);++ expect(error).toBeInstanceOf(TraceReadError);+ expect(error).toMatchObject({ code });+ /** The failed response's body is released, so its connection returns to the pool. */+ expect(failure.bodyUsed).toBe(true);+ });++ it('treats a cursor Langfuse rejects as an invalid request', async () => {+ const { reader } = setup({+ responses: [+ jsonResponse({ data: [observation({ id: 'a' })], meta: { cursor: 'expired' } }),+ jsonResponse({ message: 'bad cursor' }, 400),+ ],+ });++ await expect(+ reader.listRecords(+ createQuery({ settings: resolveTraceViewerConfig({ enabled: true, maxRecords: 2000 }) }),+ ),+ ).rejects.toMatchObject({ code: 'invalid_request' });+ });++ it('stops the Langfuse request when the client goes away', async () => {+ const controller = new AbortController();+ const fetchMock = jest.fn(+ (_url: string, init: RequestInit) =>+ new Promise<Response>((_resolve, reject) => {+ init.signal?.addEventListener('abort', () => reject(init.signal?.reason));+ controller.abort();+ }),+ );+ const reader = createLangfuseTraceReader({+ getConversationTraceRefs: async () => createRefs(),+ hasSampledTraceMessage: async () => true,+ resolveDestinations: async () => [connection],+ fetch: fetchMock,+ now: () => NOW,+ });++ await expect(+ reader.listRecords(createQuery({ signal: controller.signal })),+ ).rejects.toMatchObject({ code: 'upstream_error', message: 'The trace read was cancelled' });+ expect(fetchMock.mock.calls[0][1].signal?.aborted).toBe(true);+ });++ it('bounds each Langfuse request by the configured timeout', async () => {+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');+ const { reader } = setup({ responses: [jsonResponse({ data: [] })] });++ await reader.listRecords(+ createQuery({+ settings: resolveTraceViewerConfig({ enabled: true, requestTimeoutMs: 45_000 }),+ }),+ );++ expect(timeoutSpy).toHaveBeenCalledWith(45_000);+ timeoutSpy.mockRestore();+ });++ it('treats a point-in-time event without an end as completed, not running', async () => {+ const { reader } = setup({+ responses: [+ jsonResponse({+ data: [+ observation({ id: 'event', type: 'EVENT', name: 'checkpoint', endTime: null }),+ observation({ id: 'open-span', type: 'SPAN', endTime: null }),+ ],+ }),+ ],+ });++ const { records } = await reader.listRecords(createQuery());++ expect(records.find(({ id }) => id === 'event')).toMatchObject({+ kind: 'event',+ status: 'ok',+ endTime: '2026-09-12T11:30:00.000Z',+ });+ expect(records.find(({ id }) => id === 'open-span')).toMatchObject({ status: 'running' });+ expect(records.find(({ id }) => id === 'open-span')).not.toHaveProperty('endTime');+ });++ it('maps an aborted request to a timeout and a broken body to an upstream error', async () => {+ const timeout = new Error('The operation was aborted due to timeout');+ timeout.name = 'TimeoutError';+ const { reader } = setup({+ responses: [timeout, new Response('<html>', { status: 200 })],+ });++ await expect(reader.listRecords(createQuery())).rejects.toMatchObject({ code: 'timeout' });+ await expect(reader.listRecords(createQuery())).rejects.toMatchObject({+ code: 'upstream_error',+ });+ });+ });++ describe('getRecord', () => {+ it('reads one observation by id within the session and withholds content by default', async () => {+ const { reader, fetchMock } = setup({+ responses: [jsonResponse({ data: [observation({ input: 'secret prompt' })] })],+ });++ const detail = await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ });++ expect(detail).toEqual({+ record: expect.objectContaining({ id: 'obs-root', messageId: 'response-1' }),+ contentAvailable: false,+ });+ const params = requestedUrl(fetchMock).searchParams;+ expect(params.get('fields')).toBe('core,basic,time,model,usage');+ expect(JSON.parse(params.get('filter') ?? '[]')).toEqual([+ { type: 'string', column: 'id', operator: '=', value: 'obs-root' },+ { type: 'string', column: 'sessionId', operator: '=', value: 'convo-1' },+ { type: 'stringOptions', column: 'userId', operator: 'any of', value: ['owner'] },+ {+ type: 'stringOptions',+ column: 'traceId',+ operator: 'any of',+ value: [RESPONSE_TRACE, TITLE_TRACE],+ },+ { type: 'datetime', column: 'startTime', operator: '<', value: '2026-09-12T12:10:00.000Z' },+ {+ type: 'datetime',+ column: 'startTime',+ operator: '>=',+ value: '2026-09-12T10:50:00.000Z',+ },+ ]);+ });++ it('returns truncated input, output and metadata when the deployment allows it', async () => {+ const { reader, fetchMock } = setup({+ responses: [+ jsonResponse({+ data: [+ observation({+ input: '{"messages":[{"role":"user","content":"hello"}]}',+ output: 'short',+ metadata: { agentId: 'agent_1' },+ }),+ ],+ }),+ ],+ });++ const detail = await reader.getRecord({+ ...createQuery({+ settings: resolveTraceViewerConfig({+ enabled: true,+ showInputOutput: true,+ maxContentLength: 12,+ }),+ }),+ recordId: 'obs-root',+ messageId: 'response-1',+ });++ expect(requestedUrl(fetchMock).searchParams.get('fields')).toBe(+ 'core,basic,time,model,usage,io,metadata',+ );+ expect(detail).toMatchObject({+ contentAvailable: true,+ input: { value: '{"messages":', truncated: true },+ output: { value: 'short', truncated: false },+ metadata: { value: '{"agentId":"', truncated: true },+ });+ });++ it('keeps literal strings that spell an empty object or null', async () => {+ const { reader } = setup({+ responses: [+ jsonResponse({+ data: [observation({ input: '{}', output: 'null', metadata: {} })],+ }),+ ],+ });++ const detail = await reader.getRecord({+ ...createQuery({+ settings: resolveTraceViewerConfig({ enabled: true, showInputOutput: true }),+ }),+ recordId: 'obs-root',+ messageId: 'response-1',+ });++ expect(detail).toMatchObject({+ contentAvailable: true,+ input: { value: '{}', truncated: false },+ output: { value: 'null', truncated: false },+ });+ expect(detail).not.toHaveProperty('metadata');+ });++ it('reads the detail from the project that listed the record', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [+ jsonResponse({ data: [observation()] }),+ jsonResponse({ data: [observation()] }),+ ],+ });++ await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ sourceId: 'central-id',+ });+ await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ sourceId: 'retired-id',+ });++ expect(requestedUrl(fetchMock, 0).origin).toBe('https://central.langfuse.test');+ expect(requestedUrl(fetchMock, 1).origin).toBe('https://tenant.langfuse.test');+ });++ it('fails over a detail read when the pinned project fails', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [+ jsonResponse({ message: 'down' }, 503),+ jsonResponse({ data: [observation()] }),+ ],+ });++ const detail = await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ sourceId: 'connection-id',+ });++ expect(detail?.record.id).toBe('obs-root');+ expect(requestedUrl(fetchMock, 0).origin).toBe('https://tenant.langfuse.test');+ expect(requestedUrl(fetchMock, 1).origin).toBe('https://central.langfuse.test');+ });++ it('keeps probing projects when one answers without the record', async () => {+ const { reader, fetchMock } = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [jsonResponse({ data: [] }), jsonResponse({ data: [observation()] })],+ });++ const detail = await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ sourceId: 'retired-id',+ });++ expect(detail?.record.id).toBe('obs-root');+ expect(requestedUrl(fetchMock, 0).origin).toBe('https://tenant.langfuse.test');+ expect(requestedUrl(fetchMock, 1).origin).toBe('https://central.langfuse.test');+ });++ it('asks every project for a detail no project has answered with, and reports a failure that could hide it', async () => {+ const fanout = setup({+ refs: createRefs({+ sampledMessages: [+ { messageId: 'response-1', langfuseDestinationIds: ['central-id', 'connection-id'] },+ ],+ }),+ responses: [jsonResponse({ data: [] }), jsonResponse({ data: [] })],+ });+ const legacy = setup({+ refs: createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ responses: [jsonResponse({ message: 'down' }, 503), jsonResponse({ data: [] })],+ });++ await expect(+ fanout.reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ }),+ ).resolves.toBeNull();+ expect(fanout.fetchMock).toHaveBeenCalledTimes(2);+ await expect(+ legacy.reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ }),+ ).rejects.toMatchObject({ code: 'upstream_error' });+ expect(legacy.fetchMock).toHaveBeenCalledTimes(2);+ });++ it('authorizes a detail read by the one turn the list attributed it to', async () => {+ const refs = createRefs({+ sampledMessages: [+ { messageId: 'response-0', langfuseDestinationIds: ['connection-id'] },+ { messageId: 'response-1', langfuseDestinationIds: ['connection-id'] },+ ],+ });+ const { reader, fetchMock, getConversationTraceRefs } = setup({+ refs,+ responses: [+ jsonResponse({ data: [observation({ traceId: traceIdForMessage('response-0') })] }),+ ],+ });++ const detail = await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'response-1',+ });++ expect(getConversationTraceRefs).toHaveBeenCalledWith(+ expect.objectContaining({ messageId: 'response-1' }),+ );+ expect(requestedTraceIds(fetchMock)).toEqual(tracesOf('response-1'));+ expect(detail).toBeNull();+ await expect(+ reader.getRecord({ ...createQuery(), recordId: 'obs-root', messageId: 'not-sampled' }),+ ).resolves.toBeNull();+ expect(fetchMock).toHaveBeenCalledTimes(1);+ });++ it('reads the record detail of a failed turn from the trace of its run', async () => {+ const { reader } = setup({+ refs: createRefs({+ sampledMessages: [+ {+ messageId: 'user-1_',+ langfuseRunId: 'run-1',+ langfuseDestinationIds: ['central-id'],+ },+ ],+ }),+ responses: [jsonResponse({ data: [observation({ traceId: traceIdForMessage('run-1') })] })],+ });++ const detail = await reader.getRecord({+ ...createQuery(),+ recordId: 'obs-root',+ messageId: 'user-1_',+ });++ expect(detail?.record).toMatchObject({ id: 'obs-root', messageId: 'user-1_' });+ });++ it('returns null for an observation outside the user-owned traces', async () => {+ const { reader } = setup({+ responses: [jsonResponse({ data: [observation({ traceId: FOREIGN_TRACE })] })],+ });++ await expect(+ reader.getRecord({ ...createQuery(), recordId: 'obs-root', messageId: 'response-1' }),+ ).resolves.toBe(null);+ });+ });++ describe('default destinations', () => {+ const envKeys = [+ 'LANGFUSE_PUBLIC_KEY',+ 'LANGFUSE_SECRET_KEY',+ 'LANGFUSE_PROJECT_ID',+ 'LANGFUSE_BASE_URL',+ 'LANGFUSE_TRACING_ENABLED',+ 'LANGFUSE_SAMPLE_RATE',+ ];++ afterEach(() => {+ for (const key of envKeys) {+ delete process.env[key];+ }+ });++ it('reads the central project with the credentials that exported the trace', async () => {+ process.env.LANGFUSE_PUBLIC_KEY = 'pk';+ process.env.LANGFUSE_SECRET_KEY = 'sk';+ process.env.LANGFUSE_PROJECT_ID = 'central-project';+ process.env.LANGFUSE_BASE_URL = 'https://self-hosted.langfuse.test';+ const fetchMock = jest.fn(+ async (_url: string, _init: RequestInit): Promise<Response> => jsonResponse({ data: [] }),+ );+ const reader = createLangfuseTraceReader({+ resolveDestinations: resolveLangfuseReadDestinations,+ hasSampledTraceMessage: async () => true,+ getConversationTraceRefs: async () =>+ createRefs({+ sampledMessages: [+ {+ messageId: 'response-1',+ langfuseDestinationIds: [+ getLangfuseDestinationId('https://self-hosted.langfuse.test', 'central-project'),+ ],+ },+ ],+ }),+ fetch: fetchMock,+ now: () => NOW,+ });++ await reader.listRecords(createQuery());++ const [url, init] = fetchMock.mock.calls[0];+ expect(new URL(url).origin).toBe('https://self-hosted.langfuse.test');+ expect(new Headers(init.headers).get('Authorization')).toBe(+ `Basic ${Buffer.from('pk:sk').toString('base64')}`,+ );+ });++ it('never waits on the central project lookup, and asks the client to check again', async () => {+ process.env.LANGFUSE_PUBLIC_KEY = 'pk-slow';+ process.env.LANGFUSE_SECRET_KEY = 'sk-slow';+ process.env.LANGFUSE_BASE_URL = 'https://slow.langfuse.test';+ const lookup = jest.spyOn(global, 'fetch').mockImplementation(() => new Promise(() => {}));+ const hasSampledTraceMessage = jest.fn(async () => false);+ const reader = createLangfuseTraceReader({+ getConversationTraceRefs: async () => createRefs(),+ hasSampledTraceMessage,+ resolveDestinations: resolveLangfuseReadDestinations,+ fetch: jest.fn(),+ });++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({+ available: false,+ retryAfterMs: 30_000,+ });++ expect(lookup).toHaveBeenCalledWith(+ 'https://slow.langfuse.test/api/public/projects',+ expect.anything(),+ );+ expect(hasSampledTraceMessage).toHaveBeenCalledWith(+ expect.objectContaining({ destinationIds: [] }),+ );+ lookup.mockRestore();+ });++ it('is unavailable while tracing is disabled', async () => {+ process.env.LANGFUSE_PUBLIC_KEY = 'pk';+ process.env.LANGFUSE_SECRET_KEY = 'sk';+ process.env.LANGFUSE_PROJECT_ID = 'central-project';+ process.env.LANGFUSE_TRACING_ENABLED = 'false';+ const hasSampledTraceMessage = jest.fn(async () => true);+ const reader = createLangfuseTraceReader({+ getConversationTraceRefs: async () =>+ createRefs({ sampledMessages: [{ messageId: 'response-1' }] }),+ hasSampledTraceMessage,+ resolveDestinations: resolveLangfuseReadDestinations,+ fetch: jest.fn(),+ });++ await expect(reader.isAvailable(createQuery())).resolves.toEqual({ available: false });+ expect(hasSampledTraceMessage).not.toHaveBeenCalled();+ });+ });+});diff --git a/packages/api/src/langfuse/reader.ts b/packages/api/src/langfuse/reader.tsnew file mode 100644index 0000000000..2b4d45de6d--- /dev/null+++ b/packages/api/src/langfuse/reader.ts@@ -0,0 +1,1093 @@+import { z } from 'zod';+import { createHash } from 'crypto';+import { logger } from '@librechat/data-schemas';+import type {+ TTraceUsage,+ TTraceRecord,+ TTraceStatus,+ TTraceContent,+ TTraceRecordKind,+} from 'librechat-data-provider';+import type {+ AppConfig,+ ConversationTraceRefs,+ SampledTraceMessage,+} from '@librechat/data-schemas';+import type { LangfuseScoreDestination } from './destinations';+import type { TraceQuery, TraceReader } from '~/traces/types';+import { exportsInternalTraceUserId } from './identity';+import { getScoreDestinations } from './destinations';+import { TraceReadError } from '~/traces/types';+import { mergeHeaders } from '~/utils/headers';+import { redirectPolicyFor } from './utils';+import { traceIdForMessage } from './trace';++const OBSERVATIONS_PATH = '/api/public/v2/observations';+const MAX_PAGE_SIZE = 1000;+/** Langfuse stamps observations with the exporting server's clock; the margin+ * absorbs skew between that clock and the database's message timestamps. */+const TIME_WINDOW_MARGIN_MS = 10 * 60 * 1000;+/** Matches the central project lookup's own retry cadence. */+const IDENTITY_RETRY_MS = 30_000;+const NAME_MAX_LENGTH = 200;+const STATUS_MESSAGE_MAX_LENGTH = 1000;+const LIST_FIELDS = 'core,basic,time,model,usage';+const DETAIL_FIELDS = `${LIST_FIELDS},io,metadata`;+const DESTINATION_PREFERENCE: Record<LangfuseScoreDestination['name'], number> = {+ connection: 0,+ tenant: 1,+ central: 2,+};++const timestampSchema = z.string().refine((value) => !Number.isNaN(Date.parse(value)));+const observationSchema = z.object({+ id: z.string().min(1),+ traceId: z.string().min(1),+ startTime: timestampSchema,+ endTime: timestampSchema.nullish(),+ parentObservationId: z.string().nullish(),+ type: z.string(),+ name: z.string().nullish(),+ level: z.string().nullish(),+ statusMessage: z.string().nullish(),+ completionStartTime: timestampSchema.nullish(),+ /** Langfuse Cloud serves the `model` field group as `model`; its SDK types name it `providedModelName`. */+ model: z.string().nullish(),+ providedModelName: z.string().nullish(),+ usageDetails: z.record(z.number()).nullish(),+ costDetails: z.record(z.number()).nullish(),+ totalCost: z.number().nullish(),+ input: z.unknown(),+ output: z.unknown(),+ metadata: z.unknown(),+});+const pageSchema = z.object({+ data: z.array(z.unknown()),+ meta: z.object({ cursor: z.string().nullish() }).partial().nullish(),+});++type LangfuseObservation = z.infer<typeof observationSchema>;+type OwnedObservation = { observation: LangfuseObservation; messageId: string };++export interface LangfuseTraceReaderDeps {+ getConversationTraceRefs: (input: {+ user: string;+ conversationId: string;+ tenantId?: string;+ messageId?: string;+ through?: { messageId: string; orderKey: string };+ limit?: number;+ }) => Promise<ConversationTraceRefs>;+ hasSampledTraceMessage: (input: {+ user: string;+ conversationId: string;+ tenantId?: string;+ destinationIds: string[];+ }) => Promise<boolean>;+ /** The projects a read may use; production passes {@link resolveLangfuseReadDestinations}. */+ resolveDestinations: (appConfig?: AppConfig) => Promise<LangfuseScoreDestination[]>;+ fetch: (url: string, init: RequestInit) => Promise<Response>;+ now?: () => number;+}++/**+ * The destinations feedback scores use, which carry the read credentials. Never+ * waits on the central project lookup: the process starts it at boot, and a read+ * must not stall behind a `/api/public/projects` call that `requestTimeoutMs`+ * does not govern. Until it resolves, central has no id; availability then asks+ * the client to check again rather than answering a definitive no.+ */+export function resolveLangfuseReadDestinations(+ appConfig?: AppConfig,+): Promise<LangfuseScoreDestination[]> {+ return getScoreDestinations(appConfig, '', true, { waitForCentralProjectId: false });+}++const KIND_BY_TYPE: Record<string, TTraceRecordKind> = {+ AGENT: 'agent',+ GENERATION: 'generation',+ EMBEDDING: 'generation',+ TOOL: 'tool',+ RETRIEVER: 'tool',+ EVENT: 'event',+};++/** Node's fetch returns a connection to its pool only once the body is consumed or cancelled. */+async function release(response: Response): Promise<void> {+ await response.body?.cancel().catch(() => undefined);+}++function clamp(value: string, maxLength: number): string {+ return value.length > maxLength ? value.slice(0, maxLength) : value;+}++function toStatus(observation: LangfuseObservation, endTime?: string | null): TTraceStatus {+ if (observation.level === 'ERROR') {+ return 'error';+ }+ if (observation.level === 'WARNING') {+ return 'warning';+ }+ return endTime ? 'ok' : 'running';+}++function usageValue(details: Record<string, number>, ...keys: string[]): number | undefined {+ for (const key of keys) {+ const value = details[key];+ if (Number.isFinite(value) && value >= 0) {+ return value;+ }+ }+ return undefined;+}++function toUsage(details?: Record<string, number> | null): TTraceUsage | undefined {+ if (!details) {+ return undefined;+ }+ const usage: TTraceUsage = {+ input: usageValue(details, 'input', 'input_tokens', 'prompt_tokens'),+ output: usageValue(details, 'output', 'output_tokens', 'completion_tokens'),+ total: usageValue(details, 'total', 'total_tokens'),+ reasoning: usageValue(details, 'output_reasoning', 'reasoning', 'reasoning_tokens'),+ cacheRead: usageValue(details, 'input_cache_read', 'cache_read', 'cache_read_input_tokens'),+ cacheWrite: usageValue(+ details,+ 'input_cache_creation',+ 'input_cache_write',+ 'cache_creation',+ 'cache_creation_input_tokens',+ ),+ };+ const entries = Object.entries(usage).filter(([, value]) => value != null);+ return entries.length > 0 ? (Object.fromEntries(entries) as TTraceUsage) : undefined;+}++function toCost(observation: LangfuseObservation): number | undefined {+ const cost = observation.totalCost ?? observation.costDetails?.total;+ return cost != null && Number.isFinite(cost) && cost >= 0 ? cost : undefined;+}++function toRecord(observation: LangfuseObservation, messageId: string): TTraceRecord {+ const type = observation.type.toUpperCase();+ /** An event is a point in time and is never given an end, so a missing end is not "running". */+ const endTime = observation.endTime ?? (type === 'EVENT' ? observation.startTime : null);+ const status = toStatus(observation, endTime);+ const name = observation.name?.trim() || observation.type.toLowerCase();+ const statusMessage = observation.statusMessage?.trim();+ const model = (observation.model ?? observation.providedModelName)?.trim();+ const usage = toUsage(observation.usageDetails);+ const cost = toCost(observation);+ return {+ id: observation.id,+ traceId: observation.traceId,+ messageId,+ parentId: observation.parentObservationId || null,+ kind: KIND_BY_TYPE[type] ?? 'span',+ name: clamp(name, NAME_MAX_LENGTH),+ startTime: new Date(observation.startTime).toISOString(),+ status,+ ...(model ? { model: clamp(model, NAME_MAX_LENGTH) } : {}),+ ...(endTime ? { endTime: new Date(endTime).toISOString() } : {}),+ ...(observation.completionStartTime+ ? { completionStartTime: new Date(observation.completionStartTime).toISOString() }+ : {}),+ ...(statusMessage && (status === 'error' || status === 'warning')+ ? { statusMessage: clamp(statusMessage, STATUS_MESSAGE_MAX_LENGTH) }+ : {}),+ ...(usage ? { usage } : {}),+ ...(cost != null ? { cost } : {}),+ };+}++function toContent(value: unknown, maxLength: number): TTraceContent | undefined {+ if (value == null) {+ return undefined;+ }+ /** An empty object or a JSON null carries nothing; a string that spells one is real output. */+ const text = typeof value === 'string' ? value : JSON.stringify(value);+ if (+ text == null ||+ text === '' ||+ (typeof value !== 'string' && (text === '{}' || text === 'null'))+ ) {+ return undefined;+ }+ return text.length > maxLength+ ? { value: text.slice(0, maxLength), truncated: true }+ : { value: text, truncated: false };+}++/** The run whose trace a response reports: its own, or the run a failed turn's error row stands for. */+function runIdOf(message: SampledTraceMessage): string {+ return message.langfuseRunId ?? message.messageId;+}++/** The traces a sampled response owns: its run and that run's title run. */+function traceIdsOf(message: SampledTraceMessage): string[] {+ const runId = runIdOf(message);+ return [traceIdForMessage(runId), traceIdForMessage(`title-${runId}`)];+}++/**+ * Maps every trace a conversation's sampled responses can own to the response+ * that owns it. Langfuse sessions are keyed only by conversation id, which is+ * unique per user rather than globally, so a record whose trace is not in this+ * map is never returned.+ */+function buildTraceOwners(messages: SampledTraceMessage[]): Map<string, string> {+ const owners = new Map<string, string>();+ for (const message of messages) {+ for (const traceId of traceIdsOf(message)) {+ owners.set(traceId, message.messageId);+ }+ }+ return owners;+}++/** Whether a response's trace could be in a project: it names the project, or predates the record. */+function couldHold(destination: LangfuseScoreDestination, message: SampledTraceMessage): boolean {+ const ids = message.langfuseDestinationIds;+ return ids == null || (destination.id != null && ids.includes(destination.id));+}++/** Stable, opaque identity of a destination; its project hash when Langfuse gave one. */+function sourceIdOf(destination: LangfuseScoreDestination): string {+ return destination.id ?? `name:${destination.name}`;+}++/**+ * The projects a conversation can be read from, the tenant's own before+ * central. A message with no recorded destinations predates the record and+ * could be in any of them; a destination no message could be in is dropped, and+ * two credentials for one project are one source, since a cursor could not tell+ * them apart.+ */+function readableSources(+ destinations: LangfuseScoreDestination[],+ messages?: SampledTraceMessage[],+): LangfuseScoreDestination[] {+ return destinations+ .filter(+ (destination) =>+ messages == null || messages.some((message) => couldHold(destination, message)),+ )+ .sort((a, b) => DESTINATION_PREFERENCE[a.name] - DESTINATION_PREFERENCE[b.name])+ .filter(+ (destination, index, ordered) =>+ ordered.findIndex((candidate) => sourceIdOf(candidate) === sourceIdOf(destination)) ===+ index,+ );+}++/** Failures of one project that another project holding the same turns can stand in for. */+const FAILOVER_CODES = new Set([+ 'unauthorized',+ 'unsupported',+ 'timeout',+ 'rate_limited',+ 'upstream_error',+]);++/** A destination named before its project id resolved still matches once the id arrives. */+function isSource(destination: LangfuseScoreDestination, sourceId?: string): boolean {+ return (+ sourceId != null &&+ (sourceIdOf(destination) === sourceId || `name:${destination.name}` === sourceId)+ );+}++/**+ * Turns per evidence window and per segment. Each turn costs two trace ids in a+ * filter, so fifty keep a request URL near 5 KB, well inside proxy limits, while+ * one read still spans a long conversation.+ */+const SEGMENT_TURNS = 50;++/** Root observations only: one row per trace, so a probe of which traces a project holds stays small. */+const ROOT_FILTER = { type: 'null', column: 'parentObservationId', operator: 'is null', value: '' };+const rootSchema = z.object({ traceId: z.string().min(1), startTime: timestampSchema.nullish() });++const cursorSchema = z.object({+ /** The newest turn of the segment being read. */+ m: z.string().min(1),+ /** That turn's position in the response order, which the next request resumes from. */+ p: z.string().min(1).max(64).optional(),+ /** The trace of that turn the segment starts at, when it starts partway through the turn. */+ k: z.enum(['r', 't']).optional(),+ /** The project reading it. */+ s: z.string().min(1).optional(),+ /** That project's Langfuse cursor. */+ c: z.string().min(1).optional(),+ /** The segment's trace set, so a Langfuse cursor is only resumed against the filter that issued it. */+ h: z.string().min(1).max(64).optional(),+});++type TraceCursor = z.infer<typeof cursorSchema>;++function encodeCursor(cursor: TraceCursor): string {+ return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');+}++function decodeCursor(value: string): TraceCursor {+ try {+ const parsed = cursorSchema.safeParse(+ JSON.parse(Buffer.from(value, 'base64url').toString('utf8')),+ );+ if (parsed.success) {+ return parsed.data;+ }+ } catch {+ /* falls through to the rejection below */+ }+ throw new TraceReadError('invalid_request', 'The page cursor is not one this server issued');+}++function segmentKey(traceIds: string[]): string {+ return createHash('sha256').update(traceIds.join(','), 'utf8').digest('base64url').slice(0, 16);+}++type LangfuseFilter = Array<{+ type: string;+ column: string;+ operator: string;+ value: string | string[];+}>;++type TraceKind = 'run' | 'title';+const KIND_BY_CODE: Record<'r' | 't', TraceKind> = { r: 'run', t: 'title' };++/**+ * Observations exported for the requesting user. The trace ids a conversation+ * owns derive from message ids, which a request can influence, so a colliding+ * id must still never return someone else's trace: every read also requires+ * the internal user id the server stamped on the trace at export.+ */+function ownerFilter(query: TraceQuery): LangfuseFilter[number] {+ return { type: 'stringOptions', column: 'userId', operator: 'any of', value: [query.userId] };+}++/**+ * Whether traces carry the internal user id. A deployment that exports another+ * user field as the trace `userId` has no immutable principal on its traces:+ * names and usernames repeat, and emails and provider ids repeat across+ * tenants. So its traces are never shown.+ */+function keyedByInternalId(appConfig?: AppConfig): boolean {+ const trace = appConfig?.langfuse?.trace;+ if (exportsInternalTraceUserId(trace)) {+ return true;+ }+ const field = trace?.userIdField;+ warnOnce(+ `user_id_field:${field}`,+ `[traces] The trace viewer shows no traces while langfuse.trace.userIdField is "${field}": only the internal user id identifies who a trace belongs to.`,+ );+ return false;+}++function startTimeFilter(window: { from?: string; to: string }): LangfuseFilter {+ return [+ { type: 'datetime', column: 'startTime', operator: '<', value: window.to },+ ...(window.from+ ? [{ type: 'datetime', column: 'startTime', operator: '>=', value: window.from }]+ : []),+ ];+}++function statusError(status: number, hasCursor: boolean): TraceReadError {+ if (status === 401 || status === 403) {+ return new TraceReadError('unauthorized', `Langfuse responded with ${status}`);+ }+ if (status === 404) {+ return new TraceReadError(+ 'unsupported',+ 'Langfuse has no v2 Observations API at this destination (self-hosted releases before v4)',+ );+ }+ if (status === 429) {+ return new TraceReadError('rate_limited', 'Langfuse is rate limiting trace reads');+ }+ if (status === 400 && hasCursor) {+ return new TraceReadError('invalid_request', 'Langfuse rejected the page cursor');+ }+ return new TraceReadError('upstream_error', `Langfuse responded with ${status}`);+}++/** Configuration problems already reported, so a per-request check cannot flood the log. */+const reportedWarnings = new Set<string>();++function warnOnce(key: string, message: string): void {+ if (reportedWarnings.has(key)) {+ return;+ }+ reportedWarnings.add(key);+ logger.warn(message);+}++function isTimeout(error: unknown): boolean {+ return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');+}++export function createLangfuseTraceReader({+ getConversationTraceRefs,+ hasSampledTraceMessage,+ resolveDestinations,+ fetch: fetchImpl,+ now = Date.now,+}: LangfuseTraceReaderDeps): TraceReader {+ async function readableDestinations(appConfig?: AppConfig): Promise<LangfuseScoreDestination[]> {+ const destinations = await resolveDestinations(appConfig);+ if (destinations.length === 0) {+ warnOnce(+ 'no_destination',+ '[traces] The trace viewer is enabled, but Langfuse tracing is disabled or has no destination with read credentials, so no conversation shows a trace.',+ );+ }+ return destinations;+ }++ /** The one sampled response a detail read is for, with the projects that could hold its traces. */+ async function loadTurn(query: TraceQuery, messageId: string) {+ const [refs, destinations] = await Promise.all([+ getConversationTraceRefs({+ user: query.userId,+ conversationId: query.conversationId,+ tenantId: query.tenantId,+ messageId,+ }),+ readableDestinations(query.appConfig),+ ]);+ return { refs, sources: readableSources(destinations, refs.sampledMessages) };+ }++ function timeWindow(refs: ConversationTraceRefs): { from?: string; to: string } {+ const earliest = [refs.firstMessageAt, refs.sampledMessages[0]?.createdAt]+ .map((value) => (value == null ? Number.NaN : new Date(value).getTime()))+ .filter((value) => Number.isFinite(value));+ return {+ ...(earliest.length > 0+ ? { from: new Date(Math.min(...earliest) - TIME_WINDOW_MARGIN_MS).toISOString() }+ : {}),+ to: new Date(now() + TIME_WINDOW_MARGIN_MS).toISOString(),+ };+ }++ async function requestPage(+ destination: LangfuseScoreDestination,+ params: URLSearchParams,+ query: TraceQuery,+ hasCursor: boolean,+ ): Promise<z.infer<typeof pageSchema>> {+ const url = `${destination.baseUrl.replace(/\/+$/, '')}${OBSERVATIONS_PATH}?${params.toString()}`;+ const timeout = AbortSignal.timeout(query.settings.requestTimeoutMs);+ const signal = query.signal ? AbortSignal.any([query.signal, timeout]) : timeout;+ const failed = (error: unknown, fallback: TraceReadError): TraceReadError => {+ if (query.signal?.aborted) {+ return new TraceReadError('upstream_error', 'The trace read was cancelled');+ }+ return isTimeout(error)+ ? new TraceReadError('timeout', 'Langfuse did not respond in time')+ : fallback;+ };++ let response: Response;+ try {+ response = await fetchImpl(url, {+ headers: mergeHeaders(destination.headers, { Authorization: destination.authorization }),+ signal,+ ...redirectPolicyFor(destination.headers),+ });+ } catch (error) {+ throw failed(+ error,+ new TraceReadError(+ 'upstream_error',+ `Langfuse request failed: ${error instanceof Error ? error.name : 'unknown error'}`,+ ),+ );+ }+ if (!response.ok) {+ await release(response);+ throw statusError(response.status, hasCursor);+ }+ let body: unknown;+ try {+ body = await response.json();+ } catch (error) {+ throw failed(+ error,+ new TraceReadError('upstream_error', 'Langfuse returned an invalid response'),+ );+ }+ const parsed = pageSchema.safeParse(body);+ if (!parsed.success) {+ throw new TraceReadError('upstream_error', 'Langfuse returned an unexpected response');+ }+ return parsed.data;+ }++ function parseRows(rows: unknown[], owners: Map<string, string>): OwnedObservation[] {+ const observations: OwnedObservation[] = [];+ let malformed = 0;+ for (const row of rows) {+ const parsed = observationSchema.safeParse(row);+ if (!parsed.success) {+ malformed++;+ continue;+ }+ const messageId = owners.get(parsed.data.traceId);+ if (messageId != null) {+ observations.push({ observation: parsed.data, messageId });+ }+ }+ if (malformed > 0) {+ logger.warn(`[langfuse] Skipped ${malformed} malformed observation(s) in a trace read`);+ }+ /** Rows that all fail the schema mean the API changed shape, not that the trace is empty. */+ if (malformed > 0 && malformed === rows.length) {+ throw new TraceReadError(+ 'upstream_error',+ 'Langfuse returned observations in an unknown shape',+ );+ }+ return observations;+ }++ return {+ async isAvailable(query) {+ const destinations = await readableDestinations(query.appConfig);+ if (destinations.length === 0 || !keyedByInternalId(query.appConfig)) {+ return { available: false };+ }+ const available = await hasSampledTraceMessage({+ user: query.userId,+ conversationId: query.conversationId,+ tenantId: query.tenantId,+ destinationIds: destinations.flatMap(({ id }) => (id != null ? [id] : [])),+ });+ if (available) {+ return { available: true };+ }+ /** A response recorded against central cannot match until central's id resolves. */+ const identityPending = destinations.some(({ name, id }) => name === 'central' && id == null);+ return identityPending+ ? { available: false, retryAfterMs: IDENTITY_RETRY_MS }+ : { available: false };+ },++ async listRecords(query) {+ const continuation = query.cursor != null ? decodeCursor(query.cursor) : undefined;+ if (!keyedByInternalId(query.appConfig)) {+ throw new TraceReadError('not_found', 'Traces here are not keyed by the internal user id');+ }+ /**+ * Sampled responses load a segment's worth at a time, ending at the turn+ * being read, plus one older response that says where the next page starts.+ * A long conversation's pages then never reload the responses before them.+ */+ const loadWindow = async (through?: { messageId: string; orderKey: string }) => {+ const refs = await getConversationTraceRefs({+ user: query.userId,+ conversationId: query.conversationId,+ tenantId: query.tenantId,+ ...(through != null ? { through } : {}),+ limit: SEGMENT_TURNS + 1,+ });+ const peek =+ refs.sampledMessages.length > SEGMENT_TURNS ? refs.sampledMessages[0] : undefined;+ return {+ refs,+ peek,+ messages: peek ? refs.sampledMessages.slice(1) : refs.sampledMessages,+ };+ };+ if (continuation != null && continuation.p == null) {+ throw new TraceReadError(+ 'invalid_request',+ 'The page cursor is not one this server issued',+ );+ }+ const [initial, destinations] = await Promise.all([+ loadWindow(+ continuation?.p != null+ ? { messageId: continuation.m, orderKey: continuation.p }+ : undefined,+ ),+ readableDestinations(query.appConfig),+ ]);+ const sources = readableSources(destinations);+ let { messages, peek } = initial;+ let owners = buildTraceOwners(messages);+ const timeFilter = startTimeFilter(timeWindow(initial.refs));+ const scopeFilter = (traceIds: string[]): LangfuseFilter => [+ { type: 'string', column: 'sessionId', operator: '=', value: query.conversationId },+ ownerFilter(query),+ { type: 'stringOptions', column: 'traceId', operator: 'any of', value: traceIds },+ ...timeFilter,+ ];++ let turn = messages.length - 1;+ let startKind: TraceKind | undefined;+ if (continuation != null) {+ startKind = continuation.k != null ? KIND_BY_CODE[continuation.k] : undefined;+ if (messages[turn]?.messageId !== continuation.m) {+ throw new TraceReadError(+ 'invalid_request',+ 'The page cursor names a turn this conversation no longer has',+ );+ }+ } else if (messages.length === 0 || sources.length === 0) {+ throw new TraceReadError('not_found', 'No sampled trace for this conversation');+ }++ /**+ * What this request learned per project: the trace ids it asked about, the+ * ones the project holds, and a failure that rules the project out.+ * Recorded destinations only say where a trace was eligible to go, so a+ * trace more than one project could hold is read from one shown to hold it.+ */+ const probed = new Map<string, Set<string>>();+ const found = new Map<string, Set<string>>();+ /** Root start times the probes saw, which order a turn's traces when they sit in different projects. */+ const rootStarts = new Map<string, string>();+ const failures = new Map<string, TraceReadError>();+ const isFailed = (source: LangfuseScoreDestination) => failures.has(sourceIdOf(source));+ const isFailover = (error: unknown): error is TraceReadError =>+ !query.signal?.aborted && error instanceof TraceReadError && FAILOVER_CODES.has(error.code);+ const candidatesFor = (message: SampledTraceMessage) =>+ sources.filter((source) => couldHold(source, message));+ const holdsTrace = (source: LangfuseScoreDestination, traceId: string) =>+ !isFailed(source) && (found.get(sourceIdOf(source))?.has(traceId) ?? false);++ /** Asks a project which of `traceIds` it holds a root observation for. */+ async function probe(source: LangfuseScoreDestination, traceIds: string[]): Promise<void> {+ const sourceId = sourceIdOf(source);+ const asked = probed.get(sourceId) ?? new Set<string>();+ const pending = traceIds.filter((traceId) => !asked.has(traceId));+ if (isFailed(source) || pending.length === 0) {+ return;+ }+ const present = found.get(sourceId) ?? new Set<string>();+ const filter = JSON.stringify([...scopeFilter(pending), ROOT_FILTER]);+ try {+ let cursor: string | undefined;+ const seenCursors = new Set<string>();+ do {+ const params = new URLSearchParams({+ fields: 'core',+ limit: String(MAX_PAGE_SIZE),+ filter,+ });+ if (cursor) {+ params.set('cursor', cursor);+ }+ const page = await requestPage(source, params, query, cursor != null);+ let parsed = 0;+ for (const row of page.data) {+ const root = rootSchema.safeParse(row);+ if (root.success) {+ parsed++;+ present.add(root.data.traceId);+ if (root.data.startTime != null) {+ rootStarts.set(root.data.traceId, new Date(root.data.startTime).toISOString());+ }+ }+ }+ if (page.data.length > 0 && parsed === 0) {+ throw new TraceReadError(+ 'upstream_error',+ 'Langfuse returned observations in an unknown shape',+ );+ }+ cursor = page.data.length > 0 ? page.meta?.cursor || undefined : undefined;+ /** A cursor that repeats would page forever, each request under its own timeout. */+ if (cursor != null && seenCursors.has(cursor)) {+ throw new TraceReadError('upstream_error', 'Langfuse repeated a page cursor');+ }+ if (cursor != null) {+ seenCursors.add(cursor);+ }+ } while (cursor);+ } catch (error) {+ if (!isFailover(error)) {+ throw error;+ }+ failures.set(sourceId, error);+ return;+ }+ for (const traceId of pending) {+ asked.add(traceId);+ }+ probed.set(sourceId, asked);+ found.set(sourceId, present);+ }++ /**+ * Looks each trace of the turns in `[lowest, highest]` that more than one+ * project could hold up in those projects, preferred first, until one holds+ * it. A turn's run and title run are exported separately, so each trace+ * needs its own evidence.+ */+ async function gatherEvidence(lowest: number, highest: number): Promise<void> {+ for (const source of sources) {+ const pending: string[] = [];+ for (let index = lowest; index <= highest; index++) {+ const message = messages[index];+ if (!couldHold(source, message) || candidatesFor(message).length < 2) {+ continue;+ }+ for (const traceId of traceIdsOf(message)) {+ if (!sources.some((other) => other !== source && holdsTrace(other, traceId))) {+ pending.push(traceId);+ }+ }+ }+ await probe(source, pending);+ }+ }++ type TraceUnit = { turn: number; kind: TraceKind; first: boolean; traceId: string };+ /**+ * A turn's traces in reading order, newest first: a title run seen to start+ * after its run (a title generated once the response finished) comes first;+ * otherwise the run does. The order only matters when the two sit in+ * different projects, and then both roots, and so their start times, are known.+ */+ const tracesOf = (index: number): Array<Pick<TraceUnit, 'kind' | 'traceId'>> => {+ const [run, title] = traceIdsOf(messages[index]);+ const runStart = rootStarts.get(run);+ const titleStart = rootStarts.get(title);+ const titleFirst = runStart != null && titleStart != null && titleStart > runStart;+ const ordered: Array<Pick<TraceUnit, 'kind' | 'traceId'>> = [+ { kind: 'run', traceId: run },+ { kind: 'title', traceId: title },+ ];+ return titleFirst ? ordered.reverse() : ordered;+ };+ const unitsFrom = (+ start: number,+ kind: TraceKind | undefined,+ lowest: number,+ ): TraceUnit[] => {+ const units: TraceUnit[] = [];+ for (let index = start; index >= lowest; index--) {+ const traces = tracesOf(index);+ const from =+ index === start && kind != null+ ? Math.max(+ 0,+ traces.findIndex((trace) => trace.kind === kind),+ )+ : 0;+ traces.slice(from).forEach((trace, position) => {+ units.push({ turn: index, first: from + position === 0, ...trace });+ });+ }+ return units;+ };++ /**+ * The project a trace is read from: the only one that could hold it, or the+ * preferred one shown to hold it (`prefer` when that one does). `undefined`+ * when no project shows it, which is normal for a title run a turn never+ * had and for a run whose root is not exported yet. Throws when a failed+ * project could hold a turn's run and no other shows it.+ */+ function holderFor(+ unit: TraceUnit,+ prefer?: LangfuseScoreDestination,+ ): LangfuseScoreDestination | undefined {+ const candidates = candidatesFor(messages[unit.turn]);+ if (candidates.length === 1 && !isFailed(candidates[0])) {+ return candidates[0];+ }+ const holding = candidates.filter((source) => holdsTrace(source, unit.traceId));+ if (holding.length > 0) {+ return prefer != null && holding.includes(prefer) ? prefer : holding[0];+ }+ /** A run could be in any failed project; a title run only where a probe found it, since+ * most turns never had one. */+ const failed = candidates.find(+ (source) =>+ isFailed(source) &&+ (unit.kind === 'run' || (found.get(sourceIdOf(source))?.has(unit.traceId) ?? false)),+ );+ if (failed != null) {+ throw failures.get(sourceIdOf(failed));+ }+ return undefined;+ }++ /**+ * The traces from `units[0]` that one project reads in a single stretch of+ * pages: consecutive traces it is shown to hold, plus traces no project+ * shows that it could hold. One project per segment keeps pages in turn+ * order and lets its own cursor page through records sharing a start time.+ */+ function segmentOf(units: TraceUnit[]) {+ const first = units[0];+ const eligible = (source: LangfuseScoreDestination, unit: TraceUnit) =>+ couldHold(source, messages[unit.turn]);+ let holder = holderFor(first);+ for (let index = 1; holder == null && index < units.length; index++) {+ let placed: LangfuseScoreDestination | undefined;+ try {+ placed = holderFor(units[index]);+ } catch {+ break;+ }+ if (placed != null && eligible(placed, first)) {+ holder = placed;+ }+ }+ holder ??= candidatesFor(messages[first.turn]).find((source) => !isFailed(source));+ if (holder == null) {+ return null;+ }+ const traceIds: string[] = [];+ let end = 0;+ while (end < units.length && traceIds.length < SEGMENT_TURNS * 2) {+ const unit = units[end];+ let placed: LangfuseScoreDestination | undefined;+ try {+ placed = holderFor(unit, holder);+ } catch (error) {+ if (end === 0) {+ throw error;+ }+ /** An unverifiable run reports its failure once it is the newest trace left. */+ break;+ }+ if (placed == null ? !eligible(holder, unit) : placed !== holder) {+ break;+ }+ traceIds.push(unit.traceId);+ end++;+ }+ return { holder, end, traceIds };+ }++ /** Reads a segment from its project until its records or this request's record budget run out. */+ async function readFrom(+ destination: LangfuseScoreDestination,+ traceIds: string[],+ startCursor?: string,+ ) {+ const filter = JSON.stringify(scopeFilter(traceIds));+ const records: TTraceRecord[] = [];+ let cursor = startCursor;+ let remaining = query.settings.maxRecords;+ const followed = new Set<string>(startCursor != null ? [startCursor] : []);++ for (;;) {+ const params = new URLSearchParams({+ fields: LIST_FIELDS,+ limit: String(Math.min(MAX_PAGE_SIZE, remaining)),+ filter,+ });+ if (cursor) {+ params.set('cursor', cursor);+ }+ const page = await requestPage(destination, params, query, cursor != null);+ for (const { observation, messageId } of parseRows(page.data, owners)) {+ records.push(toRecord(observation, messageId));+ }+ remaining -= page.data.length;+ const next = page.meta?.cursor || undefined;+ if (!next || page.data.length === 0) {+ return { records };+ }+ /** A cursor that repeats would hand every later page the same records. */+ if (followed.has(next)) {+ throw new TraceReadError('upstream_error', 'Langfuse repeated a page cursor');+ }+ followed.add(next);+ if (remaining <= 0) {+ return { records, next };+ }+ cursor = next;+ }+ }++ /** A continuation that no longer matches the trace; the viewer reloads from the newest page. */+ const changed = () =>+ new TraceReadError('invalid_request', 'The trace changed since this page was loaded');+ const cursorAt = (message: SampledTraceMessage, kind?: TraceKind): TraceCursor => ({+ m: message.messageId,+ ...(message.orderKey != null ? { p: message.orderKey } : {}),+ ...(kind != null ? { k: kind === 'title' ? ('t' as const) : ('r' as const) } : {}),+ });+ const positionOf = (unit: Pick<TraceUnit, 'turn' | 'kind' | 'first'>): TraceCursor =>+ cursorAt(messages[unit.turn], unit.first ? undefined : unit.kind);++ let resume = continuation?.c != null ? continuation : undefined;+ let firstSourceId: string | undefined;+ for (;;) {+ if (turn < 0) {+ if (peek == null) {+ break;+ }+ ({ messages, peek } = await loadWindow(+ peek.orderKey != null+ ? { messageId: peek.messageId, orderKey: peek.orderKey }+ : undefined,+ ));+ owners = buildTraceOwners(messages);+ turn = messages.length - 1;+ startKind = undefined;+ continue;+ }+ const lowest = Math.max(0, turn - SEGMENT_TURNS + 1);+ await gatherEvidence(lowest, turn);+ const units = unitsFrom(turn, startKind, lowest);+ const segment = units.length > 0 ? segmentOf(units) : null;+ const after = segment != null ? units[segment.end] : units[1];+ const advance = () => {+ turn = after != null ? after.turn : lowest - 1;+ startKind = after != null && !after.first ? after.kind : undefined;+ };+ if (segment == null) {+ if (resume != null) {+ throw changed();+ }+ /** No readable project could hold this trace. */+ advance();+ continue;+ }++ const sourceId = sourceIdOf(segment.holder);+ const key = segmentKey(segment.traceIds);+ let cursor: string | undefined;+ if (resume != null) {+ if (resume.h !== key || !isSource(segment.holder, resume.s)) {+ throw changed();+ }+ cursor = resume.c;+ resume = undefined;+ }++ let result: Awaited<ReturnType<typeof readFrom>>;+ try {+ result = await readFrom(segment.holder, segment.traceIds, cursor);+ } catch (error) {+ /** A continuation stays on its project, so pages already shown are never replayed; a+ * fresh read can move to another project shown to hold the same traces. */+ if (cursor != null || !isFailover(error)) {+ throw error;+ }+ failures.set(sourceId, error);+ continue;+ }++ firstSourceId ??= sourceId;+ if (result.next) {+ return {+ records: result.records,+ sourceId,+ nextCursor: encodeCursor({+ ...positionOf(units[0]),+ s: sourceId,+ c: result.next,+ h: key,+ }),+ };+ }+ if (result.records.length > 0) {+ let nextCursor: string | undefined;+ if (after != null) {+ nextCursor = encodeCursor(positionOf(after));+ } else if (lowest > 0) {+ nextCursor = encodeCursor(cursorAt(messages[lowest - 1]));+ } else if (peek != null) {+ nextCursor = encodeCursor(cursorAt(peek));+ }+ return { records: result.records, sourceId, ...(nextCursor ? { nextCursor } : {}) };+ }+ advance();+ }+ return { records: [], ...(firstSourceId ? { sourceId: firstSourceId } : {}) };+ },++ async getRecord(query) {+ if (!keyedByInternalId(query.appConfig)) {+ return null;+ }+ const { refs, sources } = await loadTurn(query, query.messageId);+ const pinned = sources.find((candidate) => isSource(candidate, query.sourceId));+ const candidates = pinned+ ? [pinned, ...sources.filter((entry) => entry !== pinned)]+ : sources;+ if (candidates.length === 0) {+ return null;+ }+ const owners = buildTraceOwners(refs.sampledMessages);+ const window = timeWindow(refs);+ const includeContent = query.settings.showInputOutput;+ const filter: LangfuseFilter = [+ { type: 'string', column: 'id', operator: '=', value: query.recordId },+ { type: 'string', column: 'sessionId', operator: '=', value: query.conversationId },+ ownerFilter(query),+ {+ type: 'stringOptions',+ column: 'traceId',+ operator: 'any of',+ value: refs.sampledMessages.flatMap(traceIdsOf),+ },+ ...startTimeFilter(window),+ ];+ const params = new URLSearchParams({+ fields: includeContent ? DETAIL_FIELDS : LIST_FIELDS,+ limit: '1',+ filter: JSON.stringify(filter),+ });+ /** A project that answers without the record proves nothing about the others, so each is asked in turn. */+ let lastFailure: TraceReadError | undefined;+ let match: OwnedObservation | undefined;+ for (const destination of candidates) {+ let page: z.infer<typeof pageSchema>;+ try {+ page = await requestPage(destination, params, query, false);+ } catch (error) {+ if (+ query.signal?.aborted ||+ !(error instanceof TraceReadError) ||+ !FAILOVER_CODES.has(error.code)+ ) {+ throw error;+ }+ lastFailure = error;+ continue;+ }+ match = parseRows(page.data, owners).find(+ ({ observation }) => observation.id === query.recordId,+ );+ if (match) {+ break;+ }+ }+ if (!match) {+ if (lastFailure != null) {+ throw lastFailure;+ }+ return null;+ }+ const { observation, messageId } = match;+ const record = toRecord(observation, messageId);+ if (!includeContent) {+ return { record, contentAvailable: false };+ }+ const maxLength = query.settings.maxContentLength;+ const input = toContent(observation.input, maxLength);+ const output = toContent(observation.output, maxLength);+ const metadata = toContent(observation.metadata, maxLength);+ return {+ record,+ contentAvailable: true,+ ...(input ? { input } : {}),+ ...(output ? { output } : {}),+ ...(metadata ? { metadata } : {}),+ };+ },+ };+}diff --git a/packages/api/src/langfuse/session.ts b/packages/api/src/langfuse/session.tsindex 2acb939c65..8d2150045b 100644--- a/packages/api/src/langfuse/session.ts+++ b/packages/api/src/langfuse/session.ts@@ -11,12 +11,18 @@ export interface LangfuseSessionLinkParams {getMessages: MessageMethods['getMessages'];}-export async function resolveLangfuseSessionUrl({+export interface LangfuseSession {+ url: string;+ /** Identity of the project `url` opens (see `getLangfuseDestinationId`). */+ destinationId: string;+}++export async function resolveLangfuseSession({config,conversationId,userId,getMessages,-}: LangfuseSessionLinkParams): Promise<string | null> {+}: LangfuseSessionLinkParams): Promise<LangfuseSession | null> {if (!isLangfuseConnectionAvailable()) {return null;}@@ -45,5 +51,11 @@ export async function resolveLangfuseSessionUrl({const sessionUrl = new URL(destination.baseUrl);const basePath = sessionUrl.pathname.replace(/\/+$/, '');sessionUrl.pathname = `${basePath}/project/${encodeURIComponent(projectId)}/sessions/${encodeURIComponent(conversationId)}`;- return sessionUrl.toString();+ return { url: sessionUrl.toString(), destinationId };+}++export async function resolveLangfuseSessionUrl(+ params: LangfuseSessionLinkParams,+): Promise<string | null> {+ return (await resolveLangfuseSession(params))?.url ?? null;}diff --git a/packages/api/src/langfuse/trace.spec.ts b/packages/api/src/langfuse/trace.spec.tsnew file mode 100644index 0000000000..7ae08a1d9f--- /dev/null+++ b/packages/api/src/langfuse/trace.spec.ts@@ -0,0 +1,21 @@+import { withoutTraceRefs } from './trace';++describe('withoutTraceRefs', () => {+ it('replaces a copied trace record with an explicit unsampled one', () => {+ const copy = withoutTraceRefs({+ messageId: 'copy-1',+ text: 'Hi',+ langfuseSampled: true,+ langfuseDestinationIds: ['destination-a'],+ langfuseRunId: 'run-a',+ });++ expect(copy).toEqual({ messageId: 'copy-1', text: 'Hi', langfuseSampled: false });+ });++ it('marks a row that never carried a record as unsampled, so feedback never recomputes sampling', () => {+ const row: { messageId: string; langfuseSampled?: boolean } = { messageId: 'copy-2' };++ expect(withoutTraceRefs(row)).toEqual({ messageId: 'copy-2', langfuseSampled: false });+ });+});diff --git a/packages/api/src/langfuse/trace.ts b/packages/api/src/langfuse/trace.tsindex 0bc80633c8..7306753bfe 100644--- a/packages/api/src/langfuse/trace.ts+++ b/packages/api/src/langfuse/trace.ts@@ -1,5 +1,30 @@import { createHash } from 'crypto';+type TraceRefFields = {+ langfuseSampled?: boolean | null;+ langfuseDestinationIds?: string[] | null;+ langfuseRunId?: string | null;+};+export function traceIdForMessage(messageId: string): string {return createHash('sha256').update(messageId, 'utf8').digest('hex').slice(0, 32);}++/**+ * Replaces a message's trace sampling record with an explicit "never traced".+ * A copied or client-authored row carries an id no run was traced under, so the+ * source's record would claim a trace the row never produced — for feedback+ * scores and the trace viewer alike — while a missing record would let a+ * feedback score recompute sampling for a trace that does not exist.+ */+export function withoutTraceRefs<T extends TraceRefFields>(+ message: T,+): Omit<T, keyof TraceRefFields> & { langfuseSampled: false } {+ const {+ langfuseSampled: _sampled,+ langfuseDestinationIds: _destinations,+ langfuseRunId: _runId,+ ...rest+ } = message;+ return { ...rest, langfuseSampled: false };+}diff --git a/packages/api/src/traces/handlers.spec.ts b/packages/api/src/traces/handlers.spec.tsnew file mode 100644index 0000000000..c5a546126d--- /dev/null+++ b/packages/api/src/traces/handlers.spec.ts@@ -0,0 +1,425 @@+import http from 'http';+import express from 'express';+import request from 'supertest';+import { MemoryStore } from 'express-rate-limit';+import { TRACE_RECORD_ID_MAX_LENGTH } from 'librechat-data-provider';+import type { TTracePage, TTraceRecordDetail, TTraceViewerConfig } from 'librechat-data-provider';+import type { AppConfig } from '@librechat/data-schemas';+import type { RequestHandler } from 'express';+import type { AddressInfo } from 'net';+import type { TraceHandlerDeps, TraceRequest, TraceRouteHandler } from './handlers';+import type { TraceReader } from './types';+import { createTraceReadLimiter } from './limiter';+import { createTraceHandlers } from './handlers';+import { TraceReadError } from './types';++jest.mock('@librechat/data-schemas', () => ({+ logger: { debug: jest.fn(), error: jest.fn(), warn: jest.fn(), info: jest.fn() },+}));++const record: TTraceRecordDetail['record'] = {+ id: 'obs-1',+ traceId: 'trace-1',+ messageId: 'response-1',+ parentId: null,+ kind: 'agent',+ name: 'AgentGraph',+ startTime: '2026-09-12T11:30:00.000Z',+ endTime: '2026-09-12T11:30:05.000Z',+ status: 'ok',+};++function createReader(overrides: Partial<TraceReader> = {}): jest.Mocked<TraceReader> {+ return {+ isAvailable: jest.fn(async () => ({ available: true })),+ listRecords: jest.fn(async (): Promise<TTracePage> => ({ records: [record] })),+ getRecord: jest.fn(+ async (): Promise<TTraceRecordDetail> => ({ record, contentAvailable: false }),+ ),+ ...overrides,+ } as jest.Mocked<TraceReader>;+}++function createApp({+ reader = createReader(),+ traceViewer = { enabled: true },+ userId = 'owner',+ tenantId,+ contextCost,+ getConvoOwnership = jest.fn(async () => ({ user: userId, tenantId })),+}: {+ reader?: TraceReader;+ traceViewer?: TTraceViewerConfig;+ tenantId?: string;+ contextCost?: boolean;+ getConvoOwnership?: TraceHandlerDeps['getConvoOwnership'];+ userId?: string;+} = {}) {+ const handlers = createTraceHandlers({ reader, getConvoOwnership });+ const app = express();+ app.use((req, _res, next) => {+ Object.assign(req, {+ user: { id: userId, role: 'USER', tenantId },+ config: { interfaceConfig: { traceViewer, contextCost } } as AppConfig,+ });+ next();+ });+ const limiter = createTraceReadLimiter();+ const route =+ (handler: TraceRouteHandler): RequestHandler =>+ (req, res) =>+ handler(req as TraceRequest, res);+ app.get('/api/traces/:conversationId/availability', route(handlers.availability));+ app.get('/api/traces/:conversationId/records', limiter, route(handlers.records));+ app.get('/api/traces/:conversationId/records/:recordId', limiter, route(handlers.record));+ return { app, reader, getConvoOwnership };+}++describe('trace handlers', () => {+ it('passes an owned conversation to the reader with resolved settings', async () => {+ const reader = createReader();+ const { app, getConvoOwnership } = createApp({+ reader,+ traceViewer: { enabled: true, maxRecords: 50 },+ });++ const response = await request(app).get('/api/traces/convo-1/records?cursor=abc%3D');++ expect(response.status).toBe(200);+ expect(response.headers['cache-control']).toBe('private, no-store');+ expect(response.body).toEqual({ records: [record] });+ expect(getConvoOwnership).toHaveBeenCalledWith('owner', 'convo-1', null);+ expect(reader.listRecords).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'owner',+ conversationId: 'convo-1',+ cursor: 'abc=',+ settings: expect.objectContaining({ enabled: true, maxRecords: 50 }),+ }),+ );+ });++ it('answers availability without a trace for the disabled viewer', async () => {+ const reader = createReader();+ const { app, getConvoOwnership } = createApp({ reader, traceViewer: { enabled: false } });++ const availability = await request(app).get('/api/traces/convo-1/availability');+ const records = await request(app).get('/api/traces/convo-1/records');++ expect(availability.body).toEqual({ available: false });+ expect(records.status).toBe(404);+ expect(records.body).toEqual({ error: expect.any(String), errorCode: 'disabled' });+ expect(getConvoOwnership).not.toHaveBeenCalled();+ expect(reader.isAvailable).not.toHaveBeenCalled();+ });++ it.each([+ ['a missing conversation', null],+ ["another user's conversation", { user: 'someone-else' }],+ ['a subagent child thread', { user: 'owner', subagentThread: { parentConversationId: 'p' } }],+ ])('treats %s as not found and never reads the trace', async (_label, conversation) => {+ const reader = createReader();+ const { app } = createApp({ reader, getConvoOwnership: jest.fn(async () => conversation) });++ const availability = await request(app).get('/api/traces/convo-1/availability');+ const records = await request(app).get('/api/traces/convo-1/records');+ const detail = await request(app).get('/api/traces/convo-1/records/obs-1?message=response-1');++ expect(availability.body).toEqual({ available: false });+ expect(records.status).toBe(404);+ expect(records.body.errorCode).toBe('not_found');+ expect(detail.status).toBe(404);+ expect(reader.listRecords).not.toHaveBeenCalled();+ expect(reader.getRecord).not.toHaveBeenCalled();+ });++ it("scopes ownership and reads to the requester's tenant", async () => {+ const reader = createReader();+ const { app, getConvoOwnership } = createApp({ reader, tenantId: 'tenant-a' });+ const crossTenant = createApp({+ reader: createReader(),+ tenantId: 'tenant-a',+ getConvoOwnership: jest.fn(async () => ({ user: 'owner', tenantId: 'tenant-b' })),+ });++ await request(app).get('/api/traces/convo-1/records');+ const refused = await request(crossTenant.app).get('/api/traces/convo-1/records');++ expect(getConvoOwnership).toHaveBeenCalledWith('owner', 'convo-1', 'tenant-a');+ expect(reader.listRecords).toHaveBeenCalledWith(+ expect.objectContaining({ userId: 'owner', tenantId: 'tenant-a' }),+ );+ expect(refused.status).toBe(404);+ });++ it('starts the availability lookup alongside the ownership check', async () => {+ let readerStarted: () => void = () => undefined;+ const started = new Promise<void>((resolve) => {+ readerStarted = resolve;+ });+ const reader = createReader({+ isAvailable: jest.fn(async () => {+ readerStarted();+ return { available: true };+ }),+ });+ /** Owned only if the lookup was already running; a serial handler times out to unowned. */+ const getConvoOwnership = jest.fn(async () =>+ Promise.race([+ started.then(() => ({ user: 'owner' })),+ new Promise<null>((resolve) => setTimeout(() => resolve(null), 200)),+ ]),+ );+ const { app } = createApp({ reader, getConvoOwnership });++ const response = await request(app).get('/api/traces/convo-1/availability');++ expect(response.body).toEqual({ available: true });+ });++ it('passes a retry hint through only for an owned conversation', async () => {+ const reader = createReader({+ isAvailable: jest.fn(async () => ({ available: false, retryAfterMs: 30_000 })),+ });+ const owned = createApp({ reader });+ const unowned = createApp({ reader, getConvoOwnership: jest.fn(async () => null) });++ const ownedResponse = await request(owned.app).get('/api/traces/convo-1/availability');+ const unownedResponse = await request(unowned.app).get('/api/traces/convo-1/availability');++ expect(ownedResponse.body).toEqual({ available: false, retryAfterMs: 30_000 });+ expect(unownedResponse.body).toEqual({ available: false });+ });++ it('answers unavailable for an unowned conversation even when the lookup fails', async () => {+ const reader = createReader({+ isAvailable: jest.fn(async () => {+ throw new TraceReadError('upstream_error', 'lookup failed');+ }),+ });+ const unowned = createApp({ reader, getConvoOwnership: jest.fn(async () => null) });+ const owned = createApp({ reader });++ const unownedResponse = await request(unowned.app).get('/api/traces/convo-1/availability');+ const ownedResponse = await request(owned.app).get('/api/traces/convo-1/availability');++ expect(unownedResponse.status).toBe(200);+ expect(unownedResponse.body).toEqual({ available: false });+ expect(ownedResponse.status).toBe(502);+ });++ it('rejects the new-conversation placeholder and malformed cursors', async () => {+ const reader = createReader();+ const { app } = createApp({ reader });++ const placeholder = await request(app).get('/api/traces/new/records');+ const cursor = await request(app).get('/api/traces/convo-1/records?cursor=%7B%22x%22%7D');+ const oversized = await request(app).get(+ `/api/traces/convo-1/records?cursor=${'a'.repeat(5000)}`,+ );++ expect(placeholder.status).toBe(400);+ expect(cursor.status).toBe(400);+ expect(cursor.body.errorCode).toBe('invalid_request');+ expect(oversized.status).toBe(400);+ expect(reader.listRecords).not.toHaveBeenCalled();+ });++ it.each([+ ['rate_limited', 429],+ ['timeout', 504],+ ['unauthorized', 502],+ ['unsupported', 501],+ ['upstream_error', 502],+ ] as const)('maps a %s read failure to %s', async (code, status) => {+ const reader = createReader({+ listRecords: jest.fn(async () => {+ throw new TraceReadError(code, 'internal detail');+ }),+ });+ const { app } = createApp({ reader });++ const response = await request(app).get('/api/traces/convo-1/records');++ expect(response.status).toBe(status);+ expect(response.body.errorCode).toBe(code);+ expect(response.body.error).not.toContain('internal detail');+ });++ it('hides unexpected failures behind a generic 500', async () => {+ const reader = createReader({+ getRecord: jest.fn(async () => {+ throw new Error('mongo exploded at 10.0.0.1');+ }),+ });+ const { app } = createApp({ reader });++ const response = await request(app).get('/api/traces/convo-1/records/obs-1?message=response-1');++ expect(response.status).toBe(500);+ expect(JSON.stringify(response.body)).not.toContain('10.0.0.1');+ });++ it('withholds costs unless context cost is enabled', async () => {+ const pricedRecord = { ...record, cost: 0.25 };+ const createPricedApp = (contextCost?: boolean) =>+ createApp({+ contextCost,+ reader: createReader({+ listRecords: jest.fn(async () => ({ records: [pricedRecord] })),+ getRecord: jest.fn(async () => ({ record: pricedRecord, contentAvailable: false })),+ }),+ }).app;++ const hidden = createPricedApp();+ const shown = createPricedApp(true);++ const hiddenList = await request(hidden).get('/api/traces/convo-1/records');+ const hiddenDetail = await request(hidden).get(+ '/api/traces/convo-1/records/obs-1?message=response-1',+ );+ const shownList = await request(shown).get('/api/traces/convo-1/records');+ const shownDetail = await request(shown).get(+ '/api/traces/convo-1/records/obs-1?message=response-1',+ );++ expect(hiddenList.body.records[0]).not.toHaveProperty('cost');+ expect(hiddenDetail.body.record).not.toHaveProperty('cost');+ expect(shownList.body.records[0].cost).toBe(0.25);+ expect(shownDetail.body.record.cost).toBe(0.25);+ });++ it('returns 404 when the reader has no such record', async () => {+ const reader = createReader({ getRecord: jest.fn(async () => null) });+ const { app } = createApp({ reader });++ const response = await request(app).get(+ '/api/traces/convo-1/records/obs-missing?message=response-1',+ );++ expect(response.status).toBe(404);+ expect(reader.getRecord).toHaveBeenCalledWith(+ expect.objectContaining({ conversationId: 'convo-1', recordId: 'obs-missing' }),+ );+ });++ it('reads a detail for the turn and source that listed it, and rejects a malformed or missing one', async () => {+ const reader = createReader();+ const { app } = createApp({ reader });++ await request(app).get(+ '/api/traces/convo-1/records/obs-1?message=response-1&source=central-id',+ );+ const oversized = await request(app).get(+ `/api/traces/convo-1/records/obs-1?message=response-1&source=${'s'.repeat(200)}`,+ );++ const withoutTurn = await request(app).get('/api/traces/convo-1/records/obs-1');+ const longTurn = 'r'.repeat(TRACE_RECORD_ID_MAX_LENGTH + 1);+ const longTurnDetail = await request(app).get(+ `/api/traces/convo-1/records/obs-1?message=${longTurn}`,+ );++ expect(reader.getRecord).toHaveBeenCalledWith(+ expect.objectContaining({+ recordId: 'obs-1',+ messageId: 'response-1',+ sourceId: 'central-id',+ }),+ );+ expect(oversized.status).toBe(400);+ expect(withoutTurn.status).toBe(400);+ /** A response id is stored at whatever length the request gave it; the turn it listed opens. */+ expect(longTurnDetail.status).toBe(200);+ expect(reader.getRecord).toHaveBeenCalledWith(expect.objectContaining({ messageId: longTurn }));+ expect(reader.getRecord).toHaveBeenCalledTimes(2);+ });++ it('aborts the read when the client disconnects before the response', async () => {+ let signal: AbortSignal | undefined;+ let readerStarted: () => void = () => undefined;+ const started = new Promise<void>((resolve) => {+ readerStarted = resolve;+ });+ const reader = createReader({+ listRecords: jest.fn(+ (query) =>+ new Promise<TTracePage>((_resolve, reject) => {+ signal = query.signal;+ readerStarted();+ query.signal?.addEventListener('abort', () =>+ reject(new TraceReadError('upstream_error', 'The trace read was cancelled')),+ );+ }),+ ),+ });+ const { app } = createApp({ reader });+ const server = app.listen(0);+ const { port } = server.address() as AddressInfo;++ const clientRequest = http.get(`http://127.0.0.1:${port}/api/traces/convo-1/records`);+ clientRequest.on('error', () => undefined);+ await started;+ clientRequest.destroy();+ await new Promise<void>((resolve) => signal?.addEventListener('abort', () => resolve()));+ await new Promise<void>((resolve) => server.close(() => resolve()));++ expect(signal?.aborted).toBe(true);+ const { logger } = jest.requireMock<{ logger: { warn: jest.Mock } }>('@librechat/data-schemas');+ expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('cancelled'));+ });++ it('counts the same user id in two tenants as two principals', async () => {+ const store = new MemoryStore();+ const limiter = createTraceReadLimiter({ store });+ const handlers = createTraceHandlers({+ reader: createReader(),+ getConvoOwnership: jest.fn(async (user, _conversationId, tenantId) => ({+ user,+ tenantId,+ })),+ });+ const appFor = (tenantId?: string) => {+ const app = express();+ app.use((req, _res, next) => {+ Object.assign(req, {+ user: { id: 'shared-user-id', tenantId },+ config: { interfaceConfig: { traceViewer: { enabled: true, requestsPerMinute: 1 } } },+ });+ next();+ });+ app.get('/records/:conversationId', limiter, (req, res) =>+ handlers.records(req as TraceRequest, res),+ );+ return app;+ };++ const tenantA = await request(appFor('tenant-a')).get('/records/convo-1');+ const tenantB = await request(appFor('tenant-b')).get('/records/convo-1');+ const tenantless = await request(appFor()).get('/records/convo-1');+ const tenantAAgain = await request(appFor('tenant-a')).get('/records/convo-1');++ expect([tenantA.status, tenantB.status, tenantless.status, tenantAAgain.status]).toEqual([+ 200, 200, 200, 429,+ ]);+ });++ it('limits trace reads per user with the configured ceiling', async () => {+ const reader = createReader();+ const { app } = createApp({+ reader,+ userId: 'limited-user',+ traceViewer: { enabled: true, requestsPerMinute: 2 },+ });++ const statuses = [];+ for (let i = 0; i < 3; i++) {+ statuses.push((await request(app).get('/api/traces/convo-1/records')).status);+ }+ const availability = await request(app).get('/api/traces/convo-1/availability');++ expect(statuses).toEqual([200, 200, 429]);+ expect(availability.status).toBe(200);+ expect(reader.listRecords).toHaveBeenCalledTimes(2);+ });+});diff --git a/packages/api/src/traces/handlers.ts b/packages/api/src/traces/handlers.tsnew file mode 100644index 0000000000..5e0563bfeb--- /dev/null+++ b/packages/api/src/traces/handlers.ts@@ -0,0 +1,288 @@+import { logger } from '@librechat/data-schemas';+import {+ Constants,+ TRACE_CURSOR_MAX_LENGTH,+ TRACE_RECORD_ID_MAX_LENGTH,+ TRACE_SOURCE_ID_MAX_LENGTH,+ resolveTraceViewerConfig,+} from 'librechat-data-provider';+import type {+ TTraceRecord,+ TTraceErrorCode,+ TTraceAvailability,+ TTraceErrorResponse,+} from 'librechat-data-provider';+import type { Request, Response } from 'express';+import type { TraceQuery, TraceReader } from './types';+import type { ServerRequest } from '~/types/http';+import { TraceReadError } from './types';++const CONVERSATION_ID_MAX_LENGTH = 256;+const CURSOR_PATTERN = /^[A-Za-z0-9+/=_-]+$/;++export type TraceRequest = ServerRequest & Request<{ conversationId?: string; recordId?: string }>;++type ConversationOwnership = {+ user?: string | null;+ tenantId?: string | null;+ subagentThread?: object | null;+} | null;++/** Resolves once the response is sent; Express route handlers return nothing. */+export type TraceRouteHandler = (req: TraceRequest, res: Response) => Promise<void>;++type RespondingHandler = (req: TraceRequest, res: Response) => Promise<Response>;++const toRouteHandler =+ (handler: RespondingHandler): TraceRouteHandler =>+ async (req, res) => {+ await handler(req, res);+ };++export interface TraceHandlers {+ availability: TraceRouteHandler;+ records: TraceRouteHandler;+ record: TraceRouteHandler;+}++export interface TraceHandlerDeps {+ reader: TraceReader;+ /** `tenantId: null` is the tenantless scope, as the subagent thread views pass it. */+ getConvoOwnership: (+ userId: string,+ conversationId: string,+ tenantId: string | null,+ ) => Promise<ConversationOwnership>;+}++const ERROR_STATUS: Record<TTraceErrorCode, number> = {+ disabled: 404,+ not_found: 404,+ invalid_request: 400,+ rate_limited: 429,+ timeout: 504,+ unauthorized: 502,+ unsupported: 501,+ upstream_error: 502,+};++const ERROR_MESSAGES: Record<TTraceErrorCode, string> = {+ disabled: 'Trace viewer is not enabled',+ not_found: 'Trace not found',+ invalid_request: 'Invalid trace request',+ rate_limited: 'Too many trace requests. Try again shortly.',+ timeout: 'The tracing service did not respond in time',+ unauthorized: 'The tracing service rejected the configured credentials',+ unsupported: 'The tracing service does not support trace reads',+ upstream_error: 'The tracing service could not return this trace',+};++function sendTraceError(res: Response, errorCode: TTraceErrorCode): Response {+ const body: TTraceErrorResponse = { error: ERROR_MESSAGES[errorCode], errorCode };+ return res.status(ERROR_STATUS[errorCode]).json(body);+}++/** Aborts once the client disconnects before the response finished. */+function abortOnDisconnect(res: Response): AbortSignal {+ const controller = new AbortController();+ res.once('close', () => {+ if (!res.writableFinished) {+ controller.abort();+ }+ });+ return controller.signal;+}++/**+ * Ids that reach a Langfuse filter keep a length cap; a message id only names a+ * stored row, which the app persists at any length, so the detail read accepts+ * whatever the list returned.+ */+function isValidId(value: unknown, maxLength = Number.POSITIVE_INFINITY): value is string {+ return typeof value === 'string' && value.length > 0 && value.length <= maxLength;+}++function firstQueryValue(value: unknown): string | undefined {+ if (Array.isArray(value)) {+ return firstQueryValue(value[0]);+ }+ return typeof value === 'string' ? value : undefined;+}++type ScopeResult = { query: TraceQuery } | { errorCode: TTraceErrorCode };++/** Costs follow `interface.contextCost`, the same switch that shows them in chat. */+function applyCostPolicy(record: TTraceRecord, includeCost: boolean): TTraceRecord {+ if (includeCost || record.cost == null) {+ return record;+ }+ const { cost: _cost, ...withoutCost } = record;+ return withoutCost;+}++/**+ * Trace routes for a user's own conversations. Every response is gated on+ * ownership of the conversation; the reader then narrows the backend's session+ * to the traces that user's responses produced.+ */+export function createTraceHandlers({+ reader,+ getConvoOwnership,+}: TraceHandlerDeps): TraceHandlers {+ function prepareScope(req: TraceRequest, res: Response): ScopeResult {+ const settings = resolveTraceViewerConfig(req.config?.interfaceConfig?.traceViewer);+ if (!settings.enabled) {+ return { errorCode: 'disabled' };+ }++ const userId = req.user?.id ?? req.user?._id?.toString();+ const tenantId = req.user?.tenantId || undefined;+ const { conversationId } = req.params;+ if (!userId) {+ return { errorCode: 'not_found' };+ }+ if (+ !isValidId(conversationId, CONVERSATION_ID_MAX_LENGTH) ||+ conversationId === Constants.NEW_CONVO+ ) {+ return { errorCode: 'invalid_request' };+ }++ return {+ query: {+ userId,+ tenantId,+ conversationId,+ appConfig: req.config,+ settings,+ signal: abortOnDisconnect(res),+ },+ };+ }++ /** Child threads share their parent's session, and reads of them already+ * answer as missing (see message validation), so they do too here. */+ async function isOwned({ userId, tenantId, conversationId }: TraceQuery): Promise<boolean> {+ const conversation = await getConvoOwnership(userId, conversationId, tenantId ?? null);+ return (+ conversation != null &&+ conversation.user === userId &&+ (conversation.tenantId || undefined) === tenantId &&+ conversation.subagentThread == null+ );+ }++ async function resolveScope(req: TraceRequest, res: Response): Promise<ScopeResult> {+ const scope = prepareScope(req, res);+ if ('errorCode' in scope) {+ return scope;+ }+ return (await isOwned(scope.query)) ? scope : { errorCode: 'not_found' };+ }++ function handleFailure(res: Response, error: unknown, action: string): Response {+ if (res.writableEnded || res.destroyed) {+ return res;+ }+ if (error instanceof TraceReadError) {+ if (error.code !== 'not_found') {+ logger.warn(`[traces] ${action} failed (${error.code}): ${error.message}`);+ }+ return sendTraceError(res, error.code);+ }+ logger.error(+ `[traces] ${action} failed: ${error instanceof Error ? error.message : String(error)}`,+ );+ return res.status(500).json({ error: 'Internal Server Error', errorCode: 'upstream_error' });+ }++ async function availability(req: TraceRequest, res: Response): Promise<Response> {+ res.set('Cache-Control', 'private, no-store');+ try {+ const scope = prepareScope(req, res);+ if ('errorCode' in scope) {+ return res.status(200).json({ available: false });+ }+ /** Both reads are scoped to the requesting user, so they start together on+ * the conversation-load path; nothing is answered until ownership holds. */+ const availability = reader.isAvailable(scope.query).then(+ (value) => ({ value }),+ (error: unknown) => ({ error }),+ );+ const [owned, result] = await Promise.all([isOwned(scope.query), availability]);+ if (!owned) {+ return res.status(200).json({ available: false });+ }+ if ('error' in result) {+ throw result.error;+ }+ const body: TTraceAvailability = result.value;+ return res.status(200).json(body);+ } catch (error) {+ return handleFailure(res, error, 'availability');+ }+ }++ async function records(req: TraceRequest, res: Response): Promise<Response> {+ res.set('Cache-Control', 'private, no-store');+ try {+ const scope = await resolveScope(req, res);+ if ('errorCode' in scope) {+ return sendTraceError(res, scope.errorCode);+ }+ const cursor = firstQueryValue(req.query.cursor);+ if (+ cursor != null &&+ (cursor.length === 0 ||+ cursor.length > TRACE_CURSOR_MAX_LENGTH ||+ !CURSOR_PATTERN.test(cursor))+ ) {+ return sendTraceError(res, 'invalid_request');+ }+ const page = await reader.listRecords({ ...scope.query, cursor });+ const includeCost = req.config?.interfaceConfig?.contextCost === true;+ return res.status(200).json({+ ...page,+ records: page.records.map((entry) => applyCostPolicy(entry, includeCost)),+ });+ } catch (error) {+ return handleFailure(res, error, 'records');+ }+ }++ async function record(req: TraceRequest, res: Response): Promise<Response> {+ res.set('Cache-Control', 'private, no-store');+ try {+ const scope = await resolveScope(req, res);+ if ('errorCode' in scope) {+ return sendTraceError(res, scope.errorCode);+ }+ const { recordId } = req.params;+ const sourceId = firstQueryValue(req.query.source);+ const messageId = firstQueryValue(req.query.message);+ if (+ !isValidId(recordId, TRACE_RECORD_ID_MAX_LENGTH) ||+ !isValidId(messageId) ||+ (sourceId != null && !isValidId(sourceId, TRACE_SOURCE_ID_MAX_LENGTH))+ ) {+ return sendTraceError(res, 'invalid_request');+ }+ const detail = await reader.getRecord({ ...scope.query, recordId, messageId, sourceId });+ if (!detail) {+ return sendTraceError(res, 'not_found');+ }+ const includeCost = req.config?.interfaceConfig?.contextCost === true;+ return res+ .status(200)+ .json({ ...detail, record: applyCostPolicy(detail.record, includeCost) });+ } catch (error) {+ return handleFailure(res, error, 'record');+ }+ }++ return {+ availability: toRouteHandler(availability),+ records: toRouteHandler(records),+ record: toRouteHandler(record),+ };+}diff --git a/packages/api/src/traces/index.ts b/packages/api/src/traces/index.tsnew file mode 100644index 0000000000..a1c0a184f6--- /dev/null+++ b/packages/api/src/traces/index.ts@@ -0,0 +1,3 @@+export * from './types';+export * from './limiter';+export * from './handlers';diff --git a/packages/api/src/traces/limiter.ts b/packages/api/src/traces/limiter.tsnew file mode 100644index 0000000000..414e5775c0--- /dev/null+++ b/packages/api/src/traces/limiter.ts@@ -0,0 +1,42 @@+import { rateLimit } from 'express-rate-limit';+import { resolveTraceViewerConfig } from 'librechat-data-provider';+import type { TTraceErrorResponse } from 'librechat-data-provider';+import type { Store } from 'express-rate-limit';+import type { RequestHandler } from 'express';+import type { ServerRequest } from '~/types/http';++const WINDOW_MS = 60 * 1000;+const TENANTLESS = '~tenantless';++/**+ * Per-user limit on trace reads, which spend the tracing backend's own API+ * quota. The ceiling is read per request from `interface.traceViewer`, so a+ * config override applies without a restart; must run after config middleware.+ */+export function createTraceReadLimiter({+ store,+}: {+ /** Shared counter store (e.g. Redis) from the caller; omitted, counts stay in this process. */+ store?: Store;+} = {}): RequestHandler {+ return rateLimit({+ windowMs: WINDOW_MS,+ max: (req) =>+ resolveTraceViewerConfig((req as ServerRequest).config?.interfaceConfig?.traceViewer)+ .requestsPerMinute,+ handler: (_req, res) => {+ const body: TTraceErrorResponse = {+ error: 'Too many trace requests. Try again shortly.',+ errorCode: 'rate_limited',+ };+ res.status(429).json(body);+ },+ /** Tenants can share one store, so a user's bucket is named within their tenant. */+ keyGenerator: (req) => {+ const user = (req as ServerRequest).user;+ const userId = String(user?.id ?? user?._id?.toString() ?? '');+ return `${user?.tenantId || TENANTLESS}:${userId}`;+ },+ store,+ });+}diff --git a/packages/api/src/traces/types.ts b/packages/api/src/traces/types.tsnew file mode 100644index 0000000000..8c919fcd56--- /dev/null+++ b/packages/api/src/traces/types.ts@@ -0,0 +1,50 @@+import type {+ TTracePage,+ TTraceAvailability,+ TTraceErrorCode,+ TTraceRecordDetail,+ TResolvedTraceViewerConfig,+} from 'librechat-data-provider';+import type { AppConfig } from '@librechat/data-schemas';++/** One authorized read: the caller has already proven `userId` owns `conversationId`. */+export interface TraceQuery {+ userId: string;+ /** The requester's tenant; `undefined` is the tenantless scope, never "any tenant". */+ tenantId?: string;+ conversationId: string;+ appConfig?: AppConfig;+ settings: TResolvedTraceViewerConfig;+ /** Aborts when the client goes away, so an abandoned read stops spending backend quota. */+ signal?: AbortSignal;+}++/**+ * The seam between LibreChat's trace routes and a tracing backend. An+ * implementation maps its storage into the provider-neutral records, so adding+ * a backend is a new reader rather than a branch in the routes or the client.+ */+export interface TraceReader {+ /**+ * Whether a trace may exist. Runs alongside the ownership check, so it may+ * read only the requesting user's own data and never the backend's records.+ */+ isAvailable(query: TraceQuery): Promise<TTraceAvailability>;+ listRecords(query: TraceQuery & { cursor?: string }): Promise<TTracePage>;+ /** `null` when the record is absent or outside the conversation's traces. */+ /** `messageId` is the turn the list attributed the record to, so only that turn's traces are+ * looked up; `sourceId` pins the read to the page that listed the record when still readable. */+ getRecord(+ query: TraceQuery & { recordId: string; messageId: string; sourceId?: string },+ ): Promise<TTraceRecordDetail | null>;+}++export class TraceReadError extends Error {+ readonly code: TTraceErrorCode;++ constructor(code: TTraceErrorCode, message: string) {+ super(message);+ this.name = 'TraceReadError';+ this.code = code;+ }+}diff --git a/packages/data-provider/specs/config-schemas.spec.ts b/packages/data-provider/specs/config-schemas.spec.tsindex 4e4b3ded1f..110fdc47a4 100644--- a/packages/data-provider/specs/config-schemas.spec.ts+++ b/packages/data-provider/specs/config-schemas.spec.ts@@ -15,6 +15,8 @@ import {MAX_SUBAGENTS,MAX_SUBAGENTS_CEILING,setMaxSubagents,+ traceViewerDefaults,+ resolveTraceViewerConfig,} from '../src/config';import {tModelSpecPresetSchema,@@ -1870,3 +1872,52 @@ describe('configSchema langfuse', () => {expect(result.success).toBe(false);});});++describe('interface.traceViewer', () => {+ it('accepts the documented fields and rejects out-of-range limits', () => {+ const parse = (traceViewer: Record<string, unknown>) =>+ interfaceSchema.safeParse({ traceViewer }).success;++ expect(+ parse({+ enabled: true,+ showInputOutput: true,+ maxRecords: 500,+ maxContentLength: 2000,+ requestsPerMinute: 10,+ requestTimeoutMs: 30_000,+ }),+ ).toBe(true);+ expect(parse({ requestTimeoutMs: 999 })).toBe(false);+ expect(parse({ requestTimeoutMs: 300_001 })).toBe(false);+ expect(parse({ maxRecords: 0 })).toBe(false);+ expect(parse({ maxRecords: 10_001 })).toBe(false);+ expect(parse({ maxContentLength: 1.5 })).toBe(false);+ expect(parse({ requestsPerMinute: 1001 })).toBe(false);+ });++ it('keeps the viewer off with the documented defaults when unset', () => {+ expect(resolveTraceViewerConfig(undefined)).toEqual(traceViewerDefaults);+ expect(interfaceSchema.parse({}).traceViewer).toBeUndefined();+ });++ it('re-validates overrides that bypassed the schema', () => {+ expect(+ resolveTraceViewerConfig({+ enabled: 'true',+ showInputOutput: 1,+ maxRecords: 50_000,+ maxContentLength: -5,+ requestsPerMinute: Number.NaN,+ requestTimeoutMs: 50,+ }),+ ).toEqual({+ enabled: false,+ showInputOutput: false,+ maxRecords: 10_000,+ maxContentLength: traceViewerDefaults.maxContentLength,+ requestsPerMinute: traceViewerDefaults.requestsPerMinute,+ requestTimeoutMs: traceViewerDefaults.requestTimeoutMs,+ });+ });+});diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.tsindex 7c41728256..cddee914fe 100644--- a/packages/data-provider/src/api-endpoints.ts+++ b/packages/data-provider/src/api-endpoints.ts@@ -467,6 +467,25 @@ export const skillFile = (id: string, relativePath: string) =>export const insights = () => `${BASE_URL}/api/insights`;export const insightsAccess = () => `${insights()}/access`;+/* Conversation traces */+export const conversationTrace = (conversationId: string) =>+ `${BASE_URL}/api/traces/${encodeURIComponent(conversationId)}`;+export const conversationTraceAvailability = (conversationId: string) =>+ `${conversationTrace(conversationId)}/availability`;+export const conversationTraceRecords = (conversationId: string, cursor?: string) =>+ `${conversationTrace(conversationId)}/records${+ cursor ? `?${new URLSearchParams({ cursor }).toString()}` : ''+ }`;+export const conversationTraceRecord = (+ conversationId: string,+ recordId: string,+ messageId: string,+ sourceId?: string,+) =>+ `${conversationTrace(conversationId)}/records/${encodeURIComponent(recordId)}?${new URLSearchParams(+ { message: messageId, ...(sourceId ? { source: sourceId } : {}) },+ ).toString()}`;+export const adminSkillsSync = () => `${BASE_URL}/api/admin/skills/sync`;export const adminSkillsSyncStatus = () => `${adminSkillsSync()}/status`;export const adminSkillsSyncRun = () => `${adminSkillsSync()}/run`;diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 965fb2ee4e..c44708b0ac 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -1859,6 +1859,81 @@ const mcpServersSchema = zexport type TMcpServersConfig = z.infer<typeof mcpServersSchema>;+/** Values the trace viewer uses for any `interface.traceViewer` field left unset. */+export const traceViewerDefaults = {+ enabled: false,+ showInputOutput: false,+ maxRecords: 1000,+ maxContentLength: 50_000,+ requestsPerMinute: 30,+ requestTimeoutMs: 10_000,+} as const;++type TraceViewerLimitField =+ | 'maxRecords'+ | 'maxContentLength'+ | 'requestsPerMinute'+ | 'requestTimeoutMs';++/** Inclusive bounds for the numeric `interface.traceViewer` fields. */+export const traceViewerLimits: Readonly<+ Record<TraceViewerLimitField, { readonly min: number; readonly max: number }>+> = {+ maxRecords: { min: 1, max: 10_000 },+ maxContentLength: { min: 1, max: 1_000_000 },+ requestsPerMinute: { min: 1, max: 1000 },+ requestTimeoutMs: { min: 1000, max: 300_000 },+};++const boundedIntegerSchema = (field: TraceViewerLimitField) =>+ z.number().int().min(traceViewerLimits[field].min).max(traceViewerLimits[field].max).optional();++const traceViewerSchema = z.object({+ /** Shows the conversation trace control for traces this deployment exported. */+ enabled: z.boolean().optional(),+ /** Returns observation input, output and metadata in the record inspector. */+ showInputOutput: z.boolean().optional(),+ /** Observations read from the tracing backend per request. */+ maxRecords: boundedIntegerSchema('maxRecords'),+ /** Characters kept from each input, output and metadata value before truncation. */+ maxContentLength: boundedIntegerSchema('maxContentLength'),+ /** Trace reads one user may start per minute. */+ requestsPerMinute: boundedIntegerSchema('requestsPerMinute'),+ /** Budget for each round trip to the tracing backend, in milliseconds. */+ requestTimeoutMs: boundedIntegerSchema('requestTimeoutMs'),+});++export type TTraceViewerConfig = z.infer<typeof traceViewerSchema>;+export type TResolvedTraceViewerConfig = {+ enabled: boolean;+ showInputOutput: boolean;+} & Record<TraceViewerLimitField, number>;++function boundedInteger(value: unknown, field: TraceViewerLimitField): number {+ const { min, max } = traceViewerLimits[field];+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= min+ ? Math.min(value, max)+ : traceViewerDefaults[field];+}++/**+ * Fills unset or invalid `interface.traceViewer` fields from+ * {@link traceViewerDefaults}. Admin config overrides reach runtime without+ * schema validation, so every consumer reads the section through this.+ */+export function resolveTraceViewerConfig(+ config?: Partial<Record<keyof TTraceViewerConfig, unknown>> | null,+): TResolvedTraceViewerConfig {+ return {+ enabled: config?.enabled === true,+ showInputOutput: config?.showInputOutput === true,+ maxRecords: boundedInteger(config?.maxRecords, 'maxRecords'),+ maxContentLength: boundedInteger(config?.maxContentLength, 'maxContentLength'),+ requestsPerMinute: boundedInteger(config?.requestsPerMinute, 'requestsPerMinute'),+ requestTimeoutMs: boundedInteger(config?.requestTimeoutMs, 'requestTimeoutMs'),+ };+}+export enum RetentionMode {ALL = 'all',TEMPORARY = 'temporary',@@ -1934,6 +2009,7 @@ export const interfaceSchema = z.optional(),fileSearch: z.boolean().optional(),fileCitations: z.boolean().optional(),+ traceViewer: traceViewerSchema.optional(),/** Tool keys (and `'mcp'` or an MCP server name) pinned to the prompt bar by default */defaultPinnedTools: z.array(z.string()).optional(),buildInfo: z.boolean().optional(),diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.tsindex feaeb68c11..4684f67961 100644--- a/packages/data-provider/src/data-service.ts+++ b/packages/data-provider/src/data-service.ts@@ -1,4 +1,11 @@import type { AxiosResponse } from 'axios';+import type {+ TTracePage,+ TTracePageParams,+ TTraceAvailability,+ TTraceRecordParams,+ TTraceRecordDetail,+} from './types/traces';import type { TInsightsAccessResponse, TInsightsParams, TInsightsResponse } from './types/insights';import type { TFileConfig } from './file-config';import type * as t from './types';@@ -36,6 +43,32 @@ export function getInsightsAccess(): Promise<TInsightsAccessResponse> {return request.get(endpoints.insightsAccess());}+export function getConversationTraceAvailability(+ conversationId: string,+): Promise<TTraceAvailability> {+ return request.get(endpoints.conversationTraceAvailability(conversationId));+}++export function getConversationTraceRecords(+ { conversationId, cursor }: TTracePageParams,+ signal?: AbortSignal,+): Promise<TTracePage> {+ return request.get(+ endpoints.conversationTraceRecords(conversationId, cursor),+ signal ? { signal } : undefined,+ );+}++export function getConversationTraceRecord(+ { conversationId, recordId, messageId, sourceId }: TTraceRecordParams,+ signal?: AbortSignal,+): Promise<TTraceRecordDetail> {+ return request.get(+ endpoints.conversationTraceRecord(conversationId, recordId, messageId, sourceId),+ signal ? { signal } : undefined,+ );+}+export function getLangfuseConnection(): Promise<t.TLangfuseConnectionStatus> {return request.get(endpoints.adminLangfuseConnection());}diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.tsindex 397a3535ff..bacce9be3a 100644--- a/packages/data-provider/src/index.ts+++ b/packages/data-provider/src/index.ts@@ -39,6 +39,7 @@ export * from './types/runs';export * from './types/web';export * from './types/graph';export * from './types/insights';+export * from './types/traces';export * from './types/subagents';export * from './types/queuedTurns';/* access permissions */diff --git a/packages/data-provider/src/keys.ts b/packages/data-provider/src/keys.tsindex 456efb8574..01c8455f6b 100644--- a/packages/data-provider/src/keys.ts+++ b/packages/data-provider/src/keys.ts@@ -11,6 +11,9 @@ export enum QueryKeys {searchEnabled = 'searchEnabled',langfuseConnection = 'langfuseConnection',langfuseSessionLink = 'langfuseSessionLink',+ conversationTraceAvailability = 'conversationTraceAvailability',+ conversationTraceRecords = 'conversationTraceRecords',+ conversationTraceRecord = 'conversationTraceRecord',user = 'user',name = 'name', // user key namemodels = 'models',diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.tsindex c159aecbf1..7bad8a4e16 100644--- a/packages/data-provider/src/types.ts+++ b/packages/data-provider/src/types.ts@@ -1061,4 +1061,6 @@ export type TLangfuseConnectionTestResponse =export type TLangfuseSessionLinkResponse = {url: string | null;+ /** Opaque identity of the project `url` opens, so a caller can tell whether it holds what it showed. */+ destinationId?: string;};diff --git a/packages/data-provider/src/types/traces.ts b/packages/data-provider/src/types/traces.tsnew file mode 100644index 0000000000..f1f4a3e5b3--- /dev/null+++ b/packages/data-provider/src/types/traces.ts@@ -0,0 +1,106 @@+/**+ * Provider-neutral conversation trace contract. The server maps whatever its+ * tracing backend stores into these shapes, so the client never sees a+ * backend's field names, credentials, URL structure or API version.+ */++export type TTraceRecordKind = 'agent' | 'generation' | 'tool' | 'span' | 'event';++/** `running` marks a record with no end time yet; it has a start but no duration. */+export type TTraceStatus = 'ok' | 'warning' | 'error' | 'running';++export type TTraceUsage = {+ input?: number;+ output?: number;+ total?: number;+ reasoning?: number;+ cacheRead?: number;+ cacheWrite?: number;+};++export type TTraceRecord = {+ id: string;+ traceId: string;+ /** The response message whose turn produced this record; groups records into turns. */+ messageId: string;+ /** `null` for a root; may name a record that is not loaded (or does not exist). */+ parentId: string | null;+ kind: TTraceRecordKind;+ name: string;+ model?: string;+ /** ISO-8601 timestamps. */+ startTime: string;+ endTime?: string;+ /** First streamed token of a generation; splits its span into TTFT and decoding. */+ completionStartTime?: string;+ status: TTraceStatus;+ statusMessage?: string;+ usage?: TTraceUsage;+ /** Total cost in USD, when the backend priced the record. */+ cost?: number;+};++export type TTraceErrorCode =+ | 'disabled'+ | 'not_found'+ | 'invalid_request'+ | 'rate_limited'+ | 'timeout'+ | 'unauthorized'+ | 'unsupported'+ | 'upstream_error';++export type TTraceErrorResponse = {+ error: string;+ errorCode: TTraceErrorCode;+};++export type TTraceAvailability = {+ available: boolean;+ /** Set when the backend cannot decide yet; ask again after this many milliseconds. */+ retryAfterMs?: number;+};++export type TTracePageParams = {+ conversationId: string;+ cursor?: string;+};++export type TTraceRecordParams = {+ conversationId: string;+ recordId: string;+ /** The turn the list attributed the record to; its traces are what authorize the read. */+ messageId: string;+ /** The `sourceId` of the page that listed the record, so its detail reads the same project. */+ sourceId?: string;+};++/**+ * Newest turns first; `nextCursor` loads the next older page. A turn's records+ * may continue on the following page, and their order within a turn is not+ * defined, so a client groups records by turn and orders them by time.+ */+export type TTracePage = {+ records: TTraceRecord[];+ nextCursor?: string;+ /** Opaque identity of the backend project that served the page. */+ sourceId?: string;+};++export type TTraceContent = {+ value: string;+ truncated: boolean;+};++export type TTraceRecordDetail = {+ record: TTraceRecord;+ /** False when the deployment withholds input, output and metadata. */+ contentAvailable: boolean;+ input?: TTraceContent;+ output?: TTraceContent;+ metadata?: TTraceContent;+};++export const TRACE_CURSOR_MAX_LENGTH = 4096;+export const TRACE_SOURCE_ID_MAX_LENGTH = 128;+export const TRACE_RECORD_ID_MAX_LENGTH = 256;diff --git a/packages/data-schemas/src/app/interface.spec.ts b/packages/data-schemas/src/app/interface.spec.tsindex ec46835078..495760f6f8 100644--- a/packages/data-schemas/src/app/interface.spec.ts+++ b/packages/data-schemas/src/app/interface.spec.ts@@ -235,4 +235,23 @@ describe('loadDefaultInterface', () => {expect(interfaceConfig).not.toHaveProperty('defaultPinnedTools');});++ it('passes the trace viewer section through unchanged', async () => {+ const traceViewer = { enabled: true, showInputOutput: false, maxRecords: 200 };+ const interfaceConfig = await loadDefaultInterface({+ config: { interface: { traceViewer } },+ configDefaults: getConfigDefaults(),+ });++ expect(interfaceConfig?.traceViewer).toEqual(traceViewer);+ });++ it('leaves the trace viewer unset when not configured', async () => {+ const interfaceConfig = await loadDefaultInterface({+ config: {},+ configDefaults: getConfigDefaults(),+ });++ expect(interfaceConfig?.traceViewer).toBeUndefined();+ });});diff --git a/packages/data-schemas/src/app/interface.ts b/packages/data-schemas/src/app/interface.tsindex d396393be9..5793763dd6 100644--- a/packages/data-schemas/src/app/interface.ts+++ b/packages/data-schemas/src/app/interface.ts@@ -60,6 +60,7 @@ export async function loadDefaultInterface({webSearch: interfaceConfig?.webSearch,fileSearch: interfaceConfig?.fileSearch,fileCitations: interfaceConfig?.fileCitations,+ traceViewer: interfaceConfig?.traceViewer,defaultPinnedTools: interfaceConfig?.defaultPinnedTools,peoplePicker: interfaceConfig?.peoplePicker,marketplace: interfaceConfig?.marketplace,diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.tsindex eca37034d6..1c7f4563ef 100644--- a/packages/data-schemas/src/methods/index.ts+++ b/packages/data-schemas/src/methods/index.ts@@ -73,6 +73,8 @@ import {type SubagentTaskResultClaim,type BackgroundToolResultClaim,type BackgroundToolResultRecord,+ type ConversationTraceRefs,+ type SampledTraceMessage,} from './message';import {createConversationMethods,@@ -532,6 +534,8 @@ export type {SubagentTaskResultClaim,BackgroundToolResultClaim,BackgroundToolResultRecord,+ ConversationTraceRefs,+ SampledTraceMessage,ConversationMethods,AgentEventActorReconciliationStorageMetrics,ChatProjectMethods,diff --git a/packages/data-schemas/src/methods/message.spec.ts b/packages/data-schemas/src/methods/message.spec.tsindex bf3c9d20a2..eb2083d5a1 100644--- a/packages/data-schemas/src/methods/message.spec.ts+++ b/packages/data-schemas/src/methods/message.spec.ts@@ -800,6 +800,7 @@ describe('Message Operations', () => {...mockMessageData,langfuseSampled: true,langfuseDestinationIds: ['destination-1'],+ langfuseRunId: 'run-1',});const result = await updateMessage(mockCtx.userId, {@@ -809,6 +810,7 @@ describe('Message Operations', () => {expect(result?.langfuseSampled).toBe(true);expect(result?.langfuseDestinationIds).toEqual(['destination-1']);+ expect(result?.langfuseRunId).toBe('run-1');});it('should throw an error if message is not found', async () => {@@ -2115,6 +2117,7 @@ describe('Message Operations', () => {contextMeta: { anything: true },langfuseSampled: true,langfuseDestinationIds: ['lf-1'],+ langfuseRunId: 'run-1',metadata: {usage: { input: 10, output: 20 },thoughtSignatures: { tool_1: 'opaque' },@@ -2184,6 +2187,7 @@ describe('Message Operations', () => {'contextMeta','langfuseSampled','langfuseDestinationIds',+ 'langfuseRunId','subagentTask',]) {expect(hidden[field]).toBeUndefined();diff --git a/packages/data-schemas/src/methods/message.traces.spec.ts b/packages/data-schemas/src/methods/message.traces.spec.tsnew file mode 100644index 0000000000..50525f89b6--- /dev/null+++ b/packages/data-schemas/src/methods/message.traces.spec.ts@@ -0,0 +1,364 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type { IMessage } from '..';+import { tenantStorage } from '~/config/tenantContext';+import { createMessageMethods } from './message';+import { createModels } from '../models';++jest.mock('~/config/winston', () => ({+ error: jest.fn(),+ warn: jest.fn(),+ info: jest.fn(),+ debug: jest.fn(),+}));++const TENANT_A = 'tenant-aaaaaaaaaaaaaaaaaaaa';+const TENANT_B = 'tenant-bbbbbbbbbbbbbbbbbbbb';++let mongoServer: MongoMemoryServer;+let Message: mongoose.Model<IMessage>;+let methods: ReturnType<typeof createMessageMethods>;++function at(minutes: number): Date {+ return new Date(Date.UTC(2026, 8, 1, 12, minutes));+}++/** Inserts raw rows; `isCreatedByUser` gets the schema's default, as a Mongoose write would. */+async function seed(messages: Array<Partial<IMessage>>): Promise<void> {+ await Message.collection.insertMany(+ messages.map((message) => ({ isCreatedByUser: false, ...message })),+ );+}++beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+ createModels(mongoose);+ Message = mongoose.models.Message as mongoose.Model<IMessage>;+ methods = createMessageMethods(mongoose);+});++afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer.stop();+});++beforeEach(async () => {+ await Message.deleteMany({});+});++describe('getConversationTraceRefs', () => {+ it('returns the first message time and sampled responses oldest first', async () => {+ await seed([+ { messageId: 'user-1', conversationId: 'convo', user: 'owner', createdAt: at(1) },+ {+ messageId: 'response-2',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(4),+ langfuseSampled: true,+ },+ {+ messageId: 'response-1',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(2),+ langfuseSampled: true,+ langfuseDestinationIds: ['destination-a'],+ },+ {+ messageId: 'response-unsampled',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(3),+ langfuseSampled: false,+ },+ {+ messageId: 'user-5_',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(5),+ error: true,+ langfuseSampled: true,+ langfuseRunId: 'run-5',+ },+ ]);++ const refs = await methods.getConversationTraceRefs({ user: 'owner', conversationId: 'convo' });++ expect(refs).toEqual({+ firstMessageAt: at(1),+ sampledMessages: [+ {+ messageId: 'response-1',+ createdAt: at(2),+ orderKey: expect.any(String),+ langfuseDestinationIds: ['destination-a'],+ },+ { messageId: 'response-2', createdAt: at(4), orderKey: expect.any(String) },+ {+ messageId: 'user-5_',+ createdAt: at(5),+ orderKey: expect.any(String),+ langfuseRunId: 'run-5',+ },+ ],+ });+ });++ it('orders responses saved in the same millisecond by id, so every read rebuilds one order', async () => {+ const later = new mongoose.Types.ObjectId('66e2d7a0a1b2c3d4e5f60002');+ const earlier = new mongoose.Types.ObjectId('66e2d7a0a1b2c3d4e5f60001');+ await seed([+ {+ _id: later,+ messageId: 'second',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(2),+ langfuseSampled: true,+ },+ {+ _id: earlier,+ messageId: 'first',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(2),+ langfuseSampled: true,+ },+ ] as Array<Partial<IMessage>>);++ const refs = await methods.getConversationTraceRefs({ user: 'owner', conversationId: 'convo' });++ expect(refs.sampledMessages.map(({ messageId }) => messageId)).toEqual(['first', 'second']);+ });++ it('reads a bounded page of sampled responses ending at a position a previous read returned', async () => {+ await seed(+ [1, 2, 3, 4, 5].map((index) => ({+ messageId: `response-${index}`,+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(index),+ langfuseSampled: true,+ })),+ );+ const read = (input: Record<string, unknown>) =>+ methods.getConversationTraceRefs({ user: 'owner', conversationId: 'convo', ...input });+ const ids = (refs: { sampledMessages: Array<{ messageId: string }> }) =>+ refs.sampledMessages.map(({ messageId }) => messageId);++ const newest = await read({ limit: 2 });+ expect(ids(newest)).toEqual(['response-4', 'response-5']);+ const all = await read({});+ const third = all.sampledMessages[2];+ const findOne = jest.spyOn(Message, 'findOne');+ await read({ through: { messageId: third.messageId, orderKey: third.orderKey }, limit: 2 });+ /** One round trip: the only other lookup is the conversation's first message, run alongside. */+ expect(findOne).toHaveBeenCalledTimes(1);+ findOne.mockRestore();+ expect(+ ids(+ await read({ through: { messageId: third.messageId, orderKey: third.orderKey }, limit: 2 }),+ ),+ ).toEqual(['response-2', 'response-3']);+ expect(+ ids(await read({ through: { messageId: 'response-1', orderKey: third.orderKey }, limit: 2 })),+ ).toEqual([]);+ expect(+ ids(await read({ through: { messageId: third.messageId, orderKey: 'forged' }, limit: 2 })),+ ).toEqual([]);+ /** A time past the Date range parses to a number but not to a date; it resumes nothing. */+ const beyondDateRange = `${'z'.repeat(16)}.${third.orderKey?.split('.')[1]}`;+ expect(+ ids(+ await read({+ through: { messageId: third.messageId, orderKey: beyondDateRange },+ limit: 2,+ }),+ ),+ ).toEqual([]);+ expect(ids(await read({ messageId: 'response-2' }))).toEqual(['response-2']);+ expect(ids(await read({ messageId: 'someone-elses-response' }))).toEqual([]);+ expect(ids(all)).toHaveLength(5);+ });++ it('never treats a client-authored row as a sampled response', async () => {+ await seed([+ {+ messageId: 'server-response',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(1),+ isCreatedByUser: false,+ isUserSubmitted: false,+ langfuseSampled: true,+ },+ {+ messageId: 'forged-victim-response-id',+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(2),+ isCreatedByUser: false,+ isUserSubmitted: true,+ langfuseSampled: true,+ },+ ]);++ const refs = await methods.getConversationTraceRefs({ user: 'owner', conversationId: 'convo' });++ expect(refs.sampledMessages.map(({ messageId }) => messageId)).toEqual(['server-response']);+ });++ it("never returns another user's messages from a conversation with the same id", async () => {+ await seed([+ {+ messageId: 'victim-response',+ conversationId: 'shared-id',+ user: 'victim',+ createdAt: at(0),+ langfuseSampled: true,+ },+ { messageId: 'own-user', conversationId: 'shared-id', user: 'owner', createdAt: at(5) },+ ]);++ const refs = await methods.getConversationTraceRefs({+ user: 'owner',+ conversationId: 'shared-id',+ });++ expect(refs).toEqual({ firstMessageAt: at(5), sampledMessages: [] });+ });++ it('reads only the active tenant', async () => {+ await tenantStorage.run({ tenantId: TENANT_A }, () =>+ Message.create({+ messageId: 'tenant-a-response',+ conversationId: 'convo',+ user: 'owner',+ langfuseSampled: true,+ }),+ );+ await tenantStorage.run({ tenantId: TENANT_B }, () =>+ Message.create({+ messageId: 'tenant-b-response',+ conversationId: 'convo',+ user: 'owner',+ langfuseSampled: true,+ }),+ );++ const refs = await tenantStorage.run({ tenantId: TENANT_B }, () =>+ methods.getConversationTraceRefs({+ user: 'owner',+ conversationId: 'convo',+ tenantId: TENANT_B,+ }),+ );++ expect(refs.sampledMessages.map(({ messageId }) => messageId)).toEqual(['tenant-b-response']);+ });++ it('scopes to the given tenant even without request tenant context', async () => {+ await seed([+ { messageId: 'tenantless', conversationId: 'convo', user: 'owner', langfuseSampled: true },+ {+ messageId: 'tenant-a',+ conversationId: 'convo',+ user: 'owner',+ tenantId: TENANT_A,+ langfuseSampled: true,+ },+ ]);++ const tenantless = await methods.getConversationTraceRefs({+ user: 'owner',+ conversationId: 'convo',+ });+ const scoped = await methods.getConversationTraceRefs({+ user: 'owner',+ conversationId: 'convo',+ tenantId: TENANT_A,+ });+ const tenantlessExists = await methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: [],+ });+ await Message.deleteMany({ tenantId: { $exists: false } });+ const tenantlessAfter = await methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: [],+ });++ expect(tenantless.sampledMessages.map(({ messageId }) => messageId)).toEqual(['tenantless']);+ expect(scoped.sampledMessages.map(({ messageId }) => messageId)).toEqual(['tenant-a']);+ expect(tenantlessExists).toBe(true);+ expect(tenantlessAfter).toBe(false);+ });+});++describe('hasSampledTraceMessage', () => {+ const sampled = (messageId: string, overrides: Partial<IMessage> = {}): Partial<IMessage> => ({+ messageId,+ conversationId: 'convo',+ user: 'owner',+ createdAt: at(1),+ langfuseSampled: true,+ isCreatedByUser: false,+ ...overrides,+ });++ it('finds a newer response held by a readable destination after older ones went elsewhere', async () => {+ await seed([+ sampled('old', { createdAt: at(1), langfuseDestinationIds: ['retired'] }),+ sampled('new', { createdAt: at(9), langfuseDestinationIds: ['current'] }),+ ]);++ await expect(+ methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: ['current'],+ }),+ ).resolves.toBe(true);+ await expect(+ methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: ['elsewhere'],+ }),+ ).resolves.toBe(false);+ });++ it('counts a response with no recorded destinations for any destination', async () => {+ await seed([sampled('unrecorded')]);++ await expect(+ methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: [],+ }),+ ).resolves.toBe(true);+ });++ it('ignores unsampled responses, an empty destination record, other users and client-authored rows', async () => {+ await seed([+ sampled('unsampled', { langfuseSampled: false }),+ sampled('recorded-none', { langfuseDestinationIds: [] }),+ sampled('someone-else', { user: 'victim' }),+ sampled('forged-by-client', { isUserSubmitted: true }),+ sampled('user-turn', { isCreatedByUser: true }),+ ]);++ await expect(+ methods.hasSampledTraceMessage({+ user: 'owner',+ conversationId: 'convo',+ destinationIds: ['current'],+ }),+ ).resolves.toBe(false);+ });+});diff --git a/packages/data-schemas/src/methods/message.ts b/packages/data-schemas/src/methods/message.tsindex ed0f3e0af9..c8aae0d623 100644--- a/packages/data-schemas/src/methods/message.ts+++ b/packages/data-schemas/src/methods/message.ts@@ -419,6 +419,36 @@ const SUBAGENT_VIEW_CONTROL_STRING_CODE_POINT_LIMIT = 128;* never the `news` collection). The JSON export mirrors this cache, so* fields removed here also leave user exports.*/+/**+ * A response the server generated and sampled into a trace. Its trace fields are+ * an ownership claim, so rows a client authored (the message-create route and+ * imports stamp `isUserSubmitted: true`) never count, even if one was persisted+ * with forged fields before those writes stripped them.+ */+/** A response's position in trace order: its creation time, then its `_id`. */+function traceOrderKey(createdAt: Date, id: Types.ObjectId): string {+ return `${createdAt.getTime().toString(36)}.${id.toString()}`;+}++function parseTraceOrderKey(key: string): { createdAt: Date; id: string } | undefined {+ const [time, hex] = key.split('.');+ const createdAt = new Date(Number.parseInt(time ?? '', 36));+ if (Number.isNaN(createdAt.getTime()) || hex == null || !/^[0-9a-f]{24}$/.test(hex)) {+ return undefined;+ }+ return { createdAt, id: hex };+}++/** An explicit tenant scope, so a read without request tenant context still cannot span tenants. */+const traceTenantScope = (tenantId?: string) =>+ tenantId == null ? { tenantId: { $exists: false } } : { tenantId };++const SERVER_AUTHORED_SAMPLED_RESPONSE = {+ langfuseSampled: true,+ isCreatedByUser: false,+ isUserSubmitted: { $ne: true },+} as const;+export const CLIENT_MESSAGE_SELECT: string = ['-_id','-__v',@@ -431,6 +461,7 @@ export const CLIENT_MESSAGE_SELECT: string = ['-contextMeta','-langfuseSampled','-langfuseDestinationIds',+ '-langfuseRunId','-metadata.thoughtSignatures','-content.tool_call.backgroundTask.resultClaim','-content.tool_call.backgroundTask.completionWakeup',@@ -572,6 +603,25 @@ export type ParentSubagentTaskRecord = {>;};+/** A response message whose run was sampled into a trace. */+export interface SampledTraceMessage {+ messageId: string;+ createdAt?: Date;+ /** Opaque ids of the tracing destinations eligible to hold the trace, when recorded. */+ langfuseDestinationIds?: string[];+ /** The run whose trace this response reports, when it is not the message's own id. */+ langfuseRunId?: string;+ /** Opaque position in the conversation's response order, which a later read can resume from. */+ orderKey?: string;+}++export interface ConversationTraceRefs {+ /** Creation time of the user's earliest message in the conversation. */+ firstMessageAt?: Date;+ /** Sampled response messages, oldest first. */+ sampledMessages: SampledTraceMessage[];+}+export interface MessageMethods {saveMessage(ctx: {@@ -586,6 +636,32 @@ export interface MessageMethods {},metadata?: { context?: string },): Promise<IMessage | null | undefined>;+ /**+ * Reads the references a trace viewer needs for one of the user's+ * conversations: when it began and which responses were sampled into traces.+ */+ getConversationTraceRefs(input: {+ user: string;+ conversationId: string;+ tenantId?: string;+ /** Only this response, when it is a sampled one. */+ messageId?: string;+ /** The newest response to include, by the `orderKey` a previous read returned for it. */+ through?: { messageId: string; orderKey: string };+ /** The most responses to return, newest first from `through`; all of them when absent. */+ limit?: number;+ }): Promise<ConversationTraceRefs>;+ /**+ * Whether any of the user's responses in the conversation was sampled into a+ * trace that one of `destinationIds` can hold. A response with no recorded+ * destinations predates the record and counts for every destination.+ */+ hasSampledTraceMessage(input: {+ user: string;+ conversationId: string;+ tenantId?: string;+ destinationIds: string[];+ }): Promise<boolean>;recordSubagentTaskControlReceipt(input: {userId: string;conversationId: string;@@ -1859,6 +1935,7 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messaendpoint: updatedMessage.endpoint,langfuseSampled: updatedMessage.langfuseSampled,langfuseDestinationIds: updatedMessage.langfuseDestinationIds,+ langfuseRunId: updatedMessage.langfuseRunId,};} catch (err) {logger.error('Error updating message:', err);@@ -3313,6 +3390,121 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa);}+ async function getConversationTraceRefs({+ user,+ conversationId,+ tenantId,+ messageId,+ through,+ limit,+ }: {+ user: string;+ conversationId: string;+ tenantId?: string;+ messageId?: string;+ through?: { messageId: string; orderKey: string };+ limit?: number;+ }): Promise<ConversationTraceRefs> {+ try {+ const Message = mongoose.models.Message as Model<IMessage>;+ const scope = { user, conversationId, ...traceTenantScope(tenantId) };+ const anchor = through != null ? parseTraceOrderKey(through.orderKey) : undefined;+ const range =+ anchor != null+ ? {+ $or: [+ { createdAt: { $lt: anchor.createdAt } },+ {+ createdAt: anchor.createdAt,+ _id: { $lte: new mongoose.Types.ObjectId(anchor.id) },+ },+ ],+ }+ : {};+ const query = Message.find({+ ...scope,+ ...SERVER_AUTHORED_SAMPLED_RESPONSE,+ ...(messageId != null ? { messageId } : {}),+ ...range,+ }).select('_id messageId createdAt langfuseDestinationIds langfuseRunId');+ const bounded = limit != null;+ /** `_id` breaks ties between responses saved in the same millisecond, so every page+ * request rebuilds the same turn order its cursor was positioned in. */+ const sorted = bounded+ ? query.sort({ createdAt: -1, _id: -1 }).limit(limit)+ : query.sort({ createdAt: 1, _id: 1 });+ const [first, rows] = await Promise.all([+ Message.findOne(scope)+ .select('createdAt -_id')+ .sort({ createdAt: 1 })+ .lean<Pick<IMessage, 'createdAt'>>(),+ through != null && anchor == null+ ? []+ : sorted.lean<+ Array<+ Pick<+ IMessage,+ 'messageId' | 'createdAt' | 'langfuseDestinationIds' | 'langfuseRunId'+ > & { _id: Types.ObjectId }+ >+ >(),+ ]);+ const sampled = bounded ? rows.reverse() : rows;+ /** A position that no longer names its response (deleted, or never issued) resumes nothing. */+ if (through != null && sampled[sampled.length - 1]?.messageId !== through.messageId) {+ return { firstMessageAt: first?.createdAt, sampledMessages: [] };+ }+ return {+ firstMessageAt: first?.createdAt,+ sampledMessages: sampled+ .filter((message) => typeof message.messageId === 'string')+ .map(({ _id, messageId: id, createdAt, langfuseDestinationIds, langfuseRunId }) => ({+ messageId: id,+ ...(createdAt != null ? { createdAt, orderKey: traceOrderKey(createdAt, _id) } : {}),+ ...(Array.isArray(langfuseDestinationIds) ? { langfuseDestinationIds } : {}),+ ...(typeof langfuseRunId === 'string' && langfuseRunId.length > 0+ ? { langfuseRunId }+ : {}),+ })),+ };+ } catch (err) {+ logger.error('Error getting conversation trace references:', err);+ throw err;+ }+ }++ async function hasSampledTraceMessage({+ user,+ conversationId,+ tenantId,+ destinationIds,+ }: {+ user: string;+ conversationId: string;+ tenantId?: string;+ destinationIds: string[];+ }): Promise<boolean> {+ try {+ const Message = mongoose.models.Message as Model<IMessage>;+ const match = await Message.findOne({+ user,+ conversationId,+ ...traceTenantScope(tenantId),+ ...SERVER_AUTHORED_SAMPLED_RESPONSE,+ $or: [+ { langfuseDestinationIds: null },+ { langfuseDestinationIds: { $in: destinationIds } },+ ],+ })+ .select('_id')+ .lean();+ return match != null;+ } catch (err) {+ logger.error('Error checking for a sampled trace message:', err);+ throw err;+ }+ }+/*** Retrieves a single message from the database.*/@@ -3411,6 +3603,8 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): MessareleaseSubagentTaskResultClaim,deleteMessagesSince,getMessages,+ getConversationTraceRefs,+ hasSampledTraceMessage,getMessagesForSubagentThreadView,listSubagentTasksForThreads,getMessage,diff --git a/packages/data-schemas/src/schema/message.ts b/packages/data-schemas/src/schema/message.tsindex 0bd3609e85..cb88fc01b5 100644--- a/packages/data-schemas/src/schema/message.ts+++ b/packages/data-schemas/src/schema/message.ts@@ -126,6 +126,9 @@ const messageSchema: Schema<IMessage> = new Schema(type: [String],default: undefined,},+ langfuseRunId: {+ type: String,+ },_meiliIndex: {type: Boolean,required: false,diff --git a/packages/data-schemas/src/types/message.ts b/packages/data-schemas/src/types/message.tsindex 56c381c91e..d2628b6110 100644--- a/packages/data-schemas/src/types/message.ts+++ b/packages/data-schemas/src/types/message.ts@@ -77,6 +77,8 @@ export interface IMessage extends Document {};langfuseSampled?: boolean;langfuseDestinationIds?: string[];+ /** The run whose trace this response reports, when that run's id is not the message's own (a failed turn's error row). */+ langfuseRunId?: string;_meiliIndex?: boolean;files?: unknown[];plugin?: {