Skip to content

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

🔭 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.js
index 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.js
index 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, addTit
errorText: generationError,
liveUserMessage: userMessage,
liveResponseMessageId,
+ runCreated: client?.run != null,
sender: client?.sender,
initialAgentId: verifiedInitialAgentId,
}),
diff --git a/api/server/index.js b/api/server/index.js
index 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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, res
if (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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.tsx
index 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>
<Header
parentConversationId={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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.json
index 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.yaml
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 965fb2ee4e..c44708b0ac 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1859,6 +1859,81 @@ const mcpServersSchema = z
export 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.ts
index 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.ts
index 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.ts
index 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 name
models = 'models',
diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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')): Messa
endpoint: 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')): Messa
releaseSubagentTaskResultClaim,
deleteMessagesSince,
getMessages,
+ getConversationTraceRefs,
+ hasSampledTraceMessage,
getMessagesForSubagentThreadView,
listSubagentTasksForThreads,
getMessage,
diff --git a/packages/data-schemas/src/schema/message.ts b/packages/data-schemas/src/schema/message.ts
index 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.ts
index 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?: {