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: Trace Viewer Roles, Agent Identity and Tool Rounds (#16098)

Danny Avilafa1e470b8d79
diff --git a/client/src/components/Chat/Trace/Inspector.tsx b/client/src/components/Chat/Trace/Inspector.tsx
index cf931d64be..a4b17d8d3d 100644
--- a/client/src/components/Chat/Trace/Inspector.tsx
+++ b/client/src/components/Chat/Trace/Inspector.tsx
@@ -1,17 +1,21 @@
-import { memo, useId } from 'react';
-import { X } from 'lucide-react';
-import { Button, Spinner } from '@librechat/client';
+import { memo, useId, useState } from 'react';
+import copy from 'copy-to-clipboard';
+import { Link } from 'react-router-dom';
+import { X, Copy, Check, MessageSquare } from 'lucide-react';
+import { Button, Spinner, buttonVariants } from '@librechat/client';
import type { TTraceContent } from 'librechat-data-provider';
import type { ReactNode } from 'react';
+import type { RecordPresentation, ToolCallView } from './present';
import type { TranslationKeys } from '~/hooks';
import type { TraceNode } from './model';
+import StackedToolIcons from '~/components/Chat/Messages/Content/ToolOutput/StackedToolIcons';
import { useConversationTraceRecordQuery } from '~/data-provider';
import { useTraceFormat, recordDurationText } from './format';
import { formatCost, formatTokens } from '~/utils/tokens';
-import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';
+import { appearanceOf, STATUS_LABEL } from './kinds';
+import { cn, renderAgentAvatar } from '~/utils';
import { formatJSON } from '~/utils/json';
import { useLocalize } from '~/hooks';
-import { cn } from '~/utils';
type Field = { label: TranslationKeys; value: ReactNode };
@@ -110,9 +114,100 @@ function RecordContent({
);
}
+const COPIED_MS = 2000;
+const CALL_CONTENT_LENGTH = 4000;
+
+function toContent(value?: string): TTraceContent | undefined {
+ if (value == null) {
+ return undefined;
+ }
+ const truncated = value.length > CALL_CONTENT_LENGTH;
+ return { value: truncated ? value.slice(0, CALL_CONTENT_LENGTH) : value, truncated };
+}
+
+/** The saved agent a record ran: who it is, its id to copy, and a chat with it one click away. */
+function AgentCard({ agent, agentId }: { agent: RecordPresentation['agent']; agentId: string }) {
+ const localize = useLocalize();
+ const [copied, setCopied] = useState(false);
+ const copyId = () => {
+ copy(agentId);
+ setCopied(true);
+ setTimeout(() => setCopied(false), COPIED_MS);
+ };
+ return (
+ <section className="flex flex-col gap-3">
+ {agent?.description != null && agent.description !== '' && (
+ <p className="text-sm text-text-secondary">{agent.description}</p>
+ )}
+ {agent == null && (
+ <p className="text-sm text-text-secondary">{localize('com_ui_trace_agent_unavailable')}</p>
+ )}
+ <div className="flex items-center gap-1 rounded-lg border border-border-light bg-surface-primary-alt py-0.5 pl-2.5 pr-0.5">
+ <span className="min-w-0 flex-1 select-all truncate font-mono text-xs text-text-secondary">
+ {agentId}
+ </span>
+ <Button
+ size="icon-sm"
+ variant="ghost"
+ onClick={copyId}
+ aria-label={localize(copied ? 'com_ui_copied' : 'com_ui_trace_copy_agent_id')}
+ >
+ {copied ? (
+ <Check className="size-4" aria-hidden="true" />
+ ) : (
+ <Copy className="size-4" aria-hidden="true" />
+ )}
+ </Button>
+ </div>
+ {agent != null && (
+ <Link
+ to={`/c/new?agent_id=${encodeURIComponent(agentId)}`}
+ className={cn(buttonVariants({ variant: 'default', size: 'sm' }), 'self-start')}
+ >
+ <MessageSquare className="size-4" aria-hidden="true" />
+ {localize('com_ui_trace_chat_with_agent')}
+ </Link>
+ )}
+ </section>
+ );
+}
+
+/** A tool round's calls as the chat's own tool cards hold them: no trace read, no content gate. */
+function ToolCalls({
+ calls,
+ mcpIconMap,
+}: {
+ calls: ToolCallView[];
+ mcpIconMap: Map<string, string>;
+}) {
+ const localize = useLocalize();
+ return (
+ <section className="flex flex-col gap-3">
+ {calls.map((call, index) => (
+ <div key={`${call.name}-${index}`} className="flex flex-col gap-1.5">
+ <h4 className="flex items-center gap-1.5 text-sm font-medium">
+ <StackedToolIcons toolNames={[call.name]} mcpIconMap={mcpIconMap} />
+ <span className="min-w-0 truncate">{call.title}</span>
+ {call.caption != null && (
+ <span className="truncate text-xs font-normal text-text-secondary">
+ {call.caption}
+ </span>
+ )}
+ </h4>
+ <ContentBlock label="com_ui_trace_tool_sent" content={toContent(call.input)} />
+ <ContentBlock label="com_ui_trace_tool_returned" content={toContent(call.output)} />
+ </div>
+ ))}
+ <p className="text-xs text-text-secondary">{localize('com_ui_trace_from_conversation')}</p>
+ </section>
+ );
+}
+
/** Details for the selected record; input and output load only when the deployment allows them. */
function Inspector({
node,
+ presentation,
+ mcpIconMap,
turnStart,
sourceId,
conversationId,
@@ -122,6 +217,8 @@ function Inspector({
onClose,
}: {
node: TraceNode;
+ presentation: RecordPresentation;
+ mcpIconMap: Map<string, string>;
turnStart: number;
/** The page source that listed this record. */
sourceId?: string;
@@ -135,7 +232,7 @@ function Inspector({
const format = useTraceFormat();
const headingId = useId();
const { record } = node;
- const appearance = KIND_APPEARANCE[record.kind];
+ const appearance = appearanceOf(record);
const Icon = appearance.icon;
const { usage } = record;
@@ -186,9 +283,21 @@ function 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" />
+ {presentation.agent !== undefined &&
+ renderAgentAvatar(presentation.agent, { size: 'icon', showBorder: false })}
+ {presentation.agent === undefined && presentation.toolNames != null && (
+ <StackedToolIcons toolNames={presentation.toolNames} mcpIconMap={mcpIconMap} />
+ )}
+ {presentation.agent === undefined && presentation.toolNames == null && (
+ <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}
+ {presentation.title}
+ {presentation.caption != null && (
+ <span className="ml-1.5 text-xs font-normal text-text-secondary">
+ {presentation.caption}
+ </span>
+ )}
</h3>
<Button
size="icon-sm"
@@ -230,6 +339,17 @@ function Inspector({
{record.statusMessage}
</p>
)}
+ {record.agentId != null && presentation.agent !== undefined && (
+ <AgentCard agent={presentation.agent} agentId={record.agentId} />
+ )}
+ {presentation.calls == null && presentation.preview != null && (
+ <p className="whitespace-pre-wrap break-words rounded-lg border border-border-light bg-surface-primary-alt p-2 text-sm">
+ {presentation.preview}
+ </p>
+ )}
+ {presentation.calls != null && (
+ <ToolCalls calls={presentation.calls} mcpIconMap={mcpIconMap} />
+ )}
<Section title="com_ui_trace_timing" fields={timing} />
<Section
title="com_ui_trace_model"
@@ -241,6 +361,14 @@ function Inspector({
<Section
title="com_ui_trace_identifiers"
fields={[
+ ...(presentation.technicalName != null
+ ? [
+ {
+ label: 'com_ui_trace_recorded_as' as const,
+ value: <span className="font-mono text-xs">{presentation.technicalName}</span>,
+ },
+ ]
+ : []),
{
label: 'com_ui_trace_record_id',
value: <span className="select-all font-mono text-xs">{record.id}</span>,
diff --git a/client/src/components/Chat/Trace/Ledger.tsx b/client/src/components/Chat/Trace/Ledger.tsx
index e979cc082a..af2f2ac86f 100644
--- a/client/src/components/Chat/Trace/Ledger.tsx
+++ b/client/src/components/Chat/Trace/Ledger.tsx
@@ -1,6 +1,7 @@
import { memo, useId, useMemo, useState } from 'react';
import { ChevronRight, CircleAlert, CircleDashed } from 'lucide-react';
import type { RefObject, CSSProperties, KeyboardEvent } from 'react';
+import type { Agent } from 'librechat-data-provider';
import type {
TraceRow,
TraceNode,
@@ -11,13 +12,15 @@ import type {
TraceScale,
TraceWindow,
} from './model';
-import { spanOf, stepSpan, turnSpan, turnKey, boundsOf } from './model';
+import type { RecordPresentation } from './present';
+import StackedToolIcons from '~/components/Chat/Messages/Content/ToolOutput/StackedToolIcons';
+import { spanOf, stepSpan, turnSpan, turnKey, boundsOf, isLabelRecord } from './model';
import { useTraceFormat, recordDurationText } from './format';
-import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';
+import { appearanceOf, STATUS_LABEL } from './kinds';
+import { cn, renderAgentAvatar } from '~/utils';
import { formatTokens } from '~/utils/tokens';
import { useRowWindow } from './virtual';
import { useLocalize } from '~/hooks';
-import { cn } from '~/utils';
const ROW_HEIGHT = 32;
const HEADER_HEIGHT = 28;
@@ -47,7 +50,7 @@ function RecordBar({
domain: Domain;
}) {
const { record } = node;
- const appearance = KIND_APPEARANCE[record.kind];
+ const appearance = appearanceOf(record);
const solid = record.status === 'error' ? 'bg-status-error' : appearance.bar;
if (scale === 'time' && node.end == null) {
@@ -122,7 +125,12 @@ function Ledger({
view,
selectedId,
treeRef,
- previewFor,
+ presentFor,
+ askedFor,
+ toolTitleFor,
+ agentOf,
+ unrecordedCalls,
+ mcpIconMap,
onSelect,
onToggle,
}: {
@@ -132,7 +140,15 @@ function Ledger({
view: TraceWindow | null;
selectedId: string | null;
treeRef: RefObject<HTMLDivElement>;
- previewFor: (node: TraceNode) => string | undefined;
+ presentFor: (node: TraceNode) => RecordPresentation;
+ /** The user message a response answered, which tells one response from another. */
+ askedFor: (messageId: string) => string | undefined;
+ /** A tool's name as the chat's tool cards give it. */
+ toolTitleFor: (name: string) => string;
+ agentOf: (agentId: string) => Agent | undefined;
+ /** Tool calls the trace names no record for, by response, as the chat's messages count them. */
+ unrecordedCalls: ReadonlyMap<string, number>;
+ mcpIconMap: Map<string, string>;
onSelect: (id: string) => void;
onToggle: (key: string) => void;
}) {
@@ -255,25 +271,33 @@ function Ledger({
/>
);
- const turnSummary = (turn: TraceTurn) =>
- [
- localize(turn.steps === 1 ? 'com_ui_trace_steps_count_one' : 'com_ui_trace_steps_count', {
- count: turn.steps,
- }),
+ const turnSummary = (turn: TraceTurn) => {
+ const toolCalls = turn.toolCalls + (unrecordedCalls.get(turn.messageId) ?? 0);
+ const asked = askedFor(turn.messageId);
+ /** The counts come first: the question is the part a narrow row can afford to truncate. */
+ return [
localize(
- turn.toolCalls === 1
- ? 'com_ui_trace_tool_calls_count_one'
- : 'com_ui_trace_tool_calls_count',
- { count: turn.toolCalls },
+ turn.generations === 1
+ ? 'com_ui_trace_model_calls_count_one'
+ : 'com_ui_trace_model_calls_count',
+ { count: turn.generations },
),
+ localize(
+ toolCalls === 1 ? 'com_ui_trace_tool_calls_count_one' : 'com_ui_trace_tool_calls_count',
+ { count: toolCalls },
+ ),
+ ...(asked ? [localize('com_ui_trace_asked', { 0: asked })] : []),
].join(' · ');
+ };
const stepDescription = (step: TraceStep) => {
const names = [...step.toolNames];
const tools = names
.slice(0, STEP_TOOL_NAMES)
.map(([name, count]) =>
- count > 1 ? localize('com_ui_trace_tool_times', { 0: name, 1: String(count) }) : name,
+ count > 1
+ ? localize('com_ui_trace_tool_times', { 0: toolTitleFor(name), 1: String(count) })
+ : toolTitleFor(name),
);
if (names.length > STEP_TOOL_NAMES) {
tools.push(
@@ -294,6 +318,7 @@ function Ledger({
span,
messageId,
indent,
+ agents = [],
}: {
label: string;
description: string;
@@ -302,6 +327,7 @@ function Ledger({
span: TraceSpan;
messageId: string;
indent: number;
+ agents?: TraceTurn['agents'];
},
) => {
const active = activeRow?.key === row.key;
@@ -330,7 +356,32 @@ function Ledger({
<span className="flex min-w-0 items-center gap-1.5" style={{ paddingLeft: indent }}>
{chevron(row.expanded)}
<span className="shrink-0 truncate">{label}</span>
- <span className="min-w-0 truncate font-normal text-text-secondary">{description}</span>
+ {agents.map(({ agentId, recordId }) => {
+ const agent = agentOf(agentId);
+ const name = agent?.name || localize('com_ui_agent');
+ return (
+ <button
+ key={agentId}
+ type="button"
+ aria-label={localize('com_ui_trace_agent_details', { 0: name })}
+ onClick={(event) => {
+ event.stopPropagation();
+ onSelect(recordId);
+ }}
+ onKeyDown={(event) => event.stopPropagation()}
+ className={cn(
+ 'flex max-w-[45%] shrink-0 items-center gap-1 rounded-full border border-border-light py-0.5 pl-0.5 pr-2 font-medium hover:bg-surface-hover',
+ selectedId === recordId && 'bg-surface-active-alt',
+ )}
+ >
+ {renderAgentAvatar(agent ?? null, { size: 'icon', showBorder: false })}
+ <span className="truncate">{name}</span>
+ </button>
+ );
+ })}
+ <span className="min-w-0 shrink-[3] truncate font-normal text-text-secondary">
+ {description}
+ </span>
{errorCount > 0 && (
<CircleAlert aria-hidden="true" className="size-3.5 shrink-0 text-status-error" />
)}
@@ -359,6 +410,7 @@ function Ledger({
span: turnSpan(turn, scale),
messageId: turn.messageId,
indent: 0,
+ agents: turn.agents,
});
}
if (row.type === 'step') {
@@ -381,7 +433,7 @@ function Ledger({
const { record } = node;
const active = activeRow?.key === row.key;
const turnStart = model.turns.find((turn) => turn.messageId === record.messageId)?.start;
- const appearance = KIND_APPEARANCE[record.kind];
+ const appearance = appearanceOf(record);
const Icon = appearance.icon;
const running = record.status === 'running';
const duration = recordDurationText(node, format, localize(STATUS_LABEL.running));
@@ -389,8 +441,12 @@ function Ledger({
record.status === 'error' || record.status === 'warning'
? `${duration}, ${localize(STATUS_LABEL[record.status])}`
: duration;
- const preview = previewFor(node);
- const name = preview != null ? `${record.name}: ${preview}` : record.name;
+ const presentation = presentFor(node);
+ const { title, caption, preview, technicalName, toolNames } = presentation;
+ const name = [caption != null ? `${title} (${caption})` : title, preview]
+ .filter((part) => part != null)
+ .join(': ');
+ const isLabel = isLabelRecord(record);
return (
<div
@@ -433,16 +489,47 @@ function Ledger({
>
{row.hasChildren && chevron(row.expanded)}
</span>
- <Icon aria-hidden="true" className="size-3.5 shrink-0 text-text-secondary" />
- <span className="min-w-[3ch] max-w-[60%] truncate">{record.name}</span>
+ {presentation.agent !== undefined &&
+ renderAgentAvatar(presentation.agent, { size: 'icon', showBorder: false })}
+ {presentation.agent === undefined && toolNames != null && (
+ <span className="flex shrink-0 items-center">
+ <StackedToolIcons toolNames={toolNames} mcpIconMap={mcpIconMap} />
+ </span>
+ )}
+ {presentation.agent === undefined && toolNames == null && (
+ <Icon aria-hidden="true" className="size-3.5 shrink-0 text-text-secondary" />
+ )}
+ <span
+ className={cn(
+ 'max-w-[60%] truncate',
+ isLabel ? 'shrink-0 text-text-secondary' : 'min-w-[3ch] shrink-[0.25]',
+ )}
+ >
+ {title}
+ </span>
+ {caption != null && (
+ <span className="hidden shrink-[2] truncate text-xs text-text-secondary sm:inline">
+ {caption}
+ </span>
+ )}
{preview != null && (
<span
- className="min-w-[4ch] flex-1 truncate text-xs text-text-secondary"
+ className={cn(
+ 'min-w-[4ch] shrink-[3] truncate text-xs',
+ isLabel
+ ? 'rounded-full bg-surface-tertiary px-2 py-0.5 font-medium text-text-primary'
+ : 'flex-1 text-text-secondary',
+ )}
title={preview}
>
{preview}
</span>
)}
+ {model.mode === 'full' && technicalName != null && (
+ <span className="hidden min-w-0 shrink-[6] truncate font-mono text-[11px] text-text-tertiary lg:inline">
+ {technicalName}
+ </span>
+ )}
{record.model != null && (
<span className="hidden min-w-0 shrink-[4] truncate text-xs text-text-secondary sm:inline">
{record.model}
diff --git a/client/src/components/Chat/Trace/Summary.tsx b/client/src/components/Chat/Trace/Summary.tsx
index 6287623643..862db53580 100644
--- a/client/src/components/Chat/Trace/Summary.tsx
+++ b/client/src/components/Chat/Trace/Summary.tsx
@@ -10,15 +10,22 @@ type SummaryItem = { key: string; label: TranslationKeys; value: string; alert?:
function TraceSummaryBar({
summary,
+ unrecordedCalls,
showCost,
currency,
}: {
summary: TraceSummary;
+ /** Tool calls the trace names no record for, by response, as the chat's messages count them. */
+ unrecordedCalls?: ReadonlyMap<string, number>;
showCost: boolean;
currency?: { code: string; rate: number };
}) {
const localize = useLocalize();
const format = useTraceFormat();
+ let toolCalls = summary.toolCalls;
+ for (const count of unrecordedCalls?.values() ?? []) {
+ toolCalls += count;
+ }
const items: SummaryItem[] = [
{
key: 'duration',
@@ -31,7 +38,16 @@ function TraceSummaryBar({
label: 'com_ui_trace_summary_generations',
value: String(summary.generations),
},
- { key: 'tools', label: 'com_ui_trace_summary_tools', value: String(summary.toolCalls) },
+ { key: 'tools', label: 'com_ui_trace_summary_tools', value: String(toolCalls) },
+ ...(summary.labels > 0
+ ? [
+ {
+ key: 'labels',
+ label: 'com_ui_trace_summary_labels' as const,
+ value: String(summary.labels),
+ },
+ ]
+ : []),
{
key: 'tokens',
label: 'com_ui_trace_summary_tokens',
diff --git a/client/src/components/Chat/Trace/Timeline.tsx b/client/src/components/Chat/Trace/Timeline.tsx
index 0e616b24ab..2c95c252d4 100644
--- a/client/src/components/Chat/Trace/Timeline.tsx
+++ b/client/src/components/Chat/Trace/Timeline.tsx
@@ -13,8 +13,8 @@ import {
minimumSpan,
sequenceLane,
} from './model';
-import { KIND_APPEARANCE } from './kinds';
import { useTraceFormat } from './format';
+import { appearanceOf } from './kinds';
import { useLocalize } from '~/hooks';
import { cn } from '~/utils';
@@ -200,7 +200,7 @@ function Timeline({
const lane = lanes?.get(record.id) ?? sequenceLane(record);
const y = TOP_PADDING + lane * (LANE_HEIGHT + LANE_GAP);
const fill =
- record.status === 'error' ? 'fill-status-error' : KIND_APPEARANCE[record.kind].fill;
+ record.status === 'error' ? 'fill-status-error' : appearanceOf(record).fill;
if (scale === 'time' && node.end == null) {
return (
<rect
diff --git a/client/src/components/Chat/Trace/Viewer.tsx b/client/src/components/Chat/Trace/Viewer.tsx
index 5a10159cf8..483f891f6e 100644
--- a/client/src/components/Chat/Trace/Viewer.tsx
+++ b/client/src/components/Chat/Trace/Viewer.tsx
@@ -42,9 +42,12 @@ import {
buildTraceModel,
collapsibleKeys,
} from './model';
-import { buildPreviews, buildPreviewIndex } from './preview';
+import { buildPreviews, buildPreviewIndex, buildActivityIndex } from './preview';
+import { useMCPIconMap, useMCPServerNames } from '~/hooks/MCP';
import { traceModeAtom, traceScaleAtom } from './store';
-import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';
+import { presentTool, presentRecord } from './present';
+import { appearanceOf, STATUS_LABEL } from './kinds';
+import { useAgentsMapContext } from '~/Providers';
import { useTraceFormat } from './format';
import { useLocalize } from '~/hooks';
import Inspector from './Inspector';
@@ -63,6 +66,8 @@ const ERROR_MESSAGES: Partial<Record<TTraceErrorCode, TranslationKeys>> = {
};
const PRESSED = 'bg-surface-active-alt';
+/** A response's header quotes the question it answered; the row truncates what does not fit. */
+const ASKED_LENGTH = 120;
function errorCodeOf(error: unknown): TTraceErrorCode | undefined {
return axios.isAxiosError<TTraceErrorResponse>(error)
@@ -170,17 +175,67 @@ export default function Viewer({
(node: TraceNode) => previewIndex.get(node.record.id),
[previewIndex],
);
+ const activity = useMemo(
+ () => buildActivityIndex(model, previews, partialMessageId),
+ [model, previews, partialMessageId],
+ );
+ const agentsMap = useAgentsMapContext();
+ const mcpIconMap = useMCPIconMap();
+ const mcpServerNames = useMCPServerNames();
+ const agentOf = useCallback((agentId: string) => agentsMap?.[agentId], [agentsMap]);
+ const presentFor = useMemo(() => {
+ const sources = { localize, activity, previewOf, mcpServerNames, agentOf };
+ const presented = new Map<string, ReturnType<typeof presentRecord>>();
+ return (node: TraceNode) => {
+ const cached = presented.get(node.record.id);
+ if (cached != null) {
+ return cached;
+ }
+ const presentation = presentRecord(node, sources);
+ presented.set(node.record.id, presentation);
+ return presentation;
+ };
+ }, [localize, activity, previewOf, mcpServerNames, agentOf]);
+ const toolTitleFor = useCallback(
+ (name: string) => presentTool(name, { localize, mcpServerNames }).title,
+ [localize, mcpServerNames],
+ );
+ /** The user message each response answered: what tells one response from another in the ledger. */
+ const askedByResponse = useMemo(() => {
+ const textById = new Map<string, string>();
+ const asked = new Map<string, string>();
+ for (const message of messages ?? []) {
+ if (message.isCreatedByUser) {
+ textById.set(message.messageId, message.text);
+ }
+ }
+ for (const message of messages ?? []) {
+ const text = message.isCreatedByUser
+ ? undefined
+ : textById.get(message.parentMessageId ?? '')?.trim();
+ if (text) {
+ asked.set(message.messageId, text.replace(/\s+/g, ' ').slice(0, ASKED_LENGTH));
+ }
+ }
+ return asked;
+ }, [messages]);
+ const askedFor = useCallback(
+ (messageId: string) => askedByResponse.get(messageId),
+ [askedByResponse],
+ );
const labelsFor = useCallback(
(record: TTraceRecord) => {
const node = model.nodes.get(record.id);
- const preview = node != null ? previewOf(node) : undefined;
+ const presentation = node != null ? presentFor(node) : undefined;
return [
- localize(KIND_APPEARANCE[record.kind].label),
+ localize(appearanceOf(record).label),
localize(STATUS_LABEL[record.status]),
- ...(preview != null ? [preview] : []),
+ ...[presentation?.title, presentation?.caption, presentation?.preview].filter(
+ (label): label is string => label != null,
+ ),
];
},
- [localize, model, previewOf],
+ [localize, model, presentFor],
);
const rows = useMemo(
() => flattenRows(model, { collapsed, query: deferredQuery, window: view, scale, labelsFor }),
@@ -193,7 +248,11 @@ export default function Viewer({
useEffect(() => {
const previous = previousModel.current;
previousModel.current = model;
- setSelectedId((id) => (id != null && model.nodes.get(id)?.shown !== true ? null : id));
+ /** An agent is opened from its response's header, which lists it whether or not the mode does. */
+ setSelectedId((id) => {
+ const node = id != null ? model.nodes.get(id) : undefined;
+ return node != null && (node.shown || node.record.role === 'agent') ? id : null;
+ });
setView((current) =>
current != null ? rebaseWindow(current, previous, model, scale) : current,
);
@@ -350,7 +409,12 @@ export default function Viewer({
<>
<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} />
+ <Summary
+ summary={model.summary}
+ unrecordedCalls={activity.unrecordedCalls}
+ showCost={showCost}
+ currency={currency}
+ />
{recordsQuery.hasNextPage === true && (
<p className="text-xs text-text-secondary">
{localize('com_ui_trace_partial', { 0: String(records.length) })}
@@ -460,7 +524,12 @@ export default function Viewer({
view={view}
selectedId={selectedId}
treeRef={treeRef}
- previewFor={previewOf}
+ presentFor={presentFor}
+ askedFor={askedFor}
+ toolTitleFor={toolTitleFor}
+ agentOf={agentOf}
+ unrecordedCalls={activity.unrecordedCalls}
+ mcpIconMap={mcpIconMap}
onSelect={setSelectedId}
onToggle={toggle}
/>
@@ -505,6 +574,8 @@ export default function Viewer({
{selectedNode && (
<Inspector
node={selectedNode}
+ presentation={presentFor(selectedNode)}
+ mcpIconMap={mcpIconMap}
turnStart={selectedTurnStart}
sourceId={recordSources.get(selectedNode.record.id)}
conversationId={conversationId}
diff --git a/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
index ea2a8e72d9..e780f47ab5 100644
--- a/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
+++ b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
@@ -1,11 +1,19 @@
import React from 'react';
import { Provider } from 'jotai';
+import { MemoryRouter } from 'react-router-dom';
import userEvent from '@testing-library/user-event';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ContentTypes, QueryKeys, dataService } from 'librechat-data-provider';
import { act, render, screen, waitFor, within, fireEvent } from '@testing-library/react';
-import type { TMessage, TTracePage, TTraceRecord, TStartupConfig } from 'librechat-data-provider';
+import type {
+ TMessage,
+ TAgentsMap,
+ TTracePage,
+ TTraceRecord,
+ TStartupConfig,
+} from 'librechat-data-provider';
import { keepNewestTracePage } from '~/data-provider/Traces/queries';
+import { AgentsMapContext } from '~/Providers/AgentsMapContext';
import Viewer from '../Viewer';
jest.mock('librechat-data-provider', () => {
@@ -141,14 +149,16 @@ describe('Trace Viewer', () => {
expect(screen.getByRole('status')).toHaveTextContent('com_ui_trace_loading');
expect(await recordRow('llm')).toHaveAttribute('aria-level', '3');
expect(
- screen.getByRole('treeitem', { name: recordName('web_search.*com_ui_trace_status_error') }),
+ screen.getByRole('treeitem', {
+ name: recordName('com_ui_tool_name_web_search.*com_ui_trace_status_error'),
+ }),
).toBeInTheDocument();
const turn = screen.getByRole('treeitem', { name: /^com_ui_trace_turn/ });
expect(turn).toHaveAttribute('aria-level', '1');
- expect(turn).toHaveAccessibleName(/com_ui_trace_steps_count_one 1/);
+ expect(turn).toHaveAccessibleName(/com_ui_trace_model_calls_count_one 1/);
expect(turn).toHaveAccessibleName(/com_ui_trace_tool_calls_count_one 1/);
expect(stepRow(1)).toHaveAttribute('aria-level', '2');
- expect(stepRow(1)).toHaveAccessibleName(/web_search/);
+ expect(stepRow(1)).toHaveAccessibleName(/com_ui_tool_name_web_search/);
expect(
screen.queryByRole('treeitem', { name: recordName('AgentGraph') }),
).not.toBeInTheDocument();
@@ -297,7 +307,9 @@ describe('Trace Viewer', () => {
expect(await recordRow('llm: Let me look that up\\.')).toBeInTheDocument();
expect(
- screen.getByRole('treeitem', { name: recordName('web_search: query: weather') }),
+ screen.getByRole('treeitem', {
+ name: recordName('com_ui_tool_name_web_search: query: weather'),
+ }),
).toBeInTheDocument();
expect(dataService.getMessagesByConvoId).not.toHaveBeenCalled();
});
@@ -403,7 +415,7 @@ describe('Trace Viewer', () => {
it('shows the error message for a failed record', async () => {
renderViewer();
- await userEvent.click(await recordRow('web_search'));
+ await userEvent.click(await recordRow('com_ui_tool_name_web_search'));
expect(
within(screen.getByTestId('trace-inspector')).getByText('Error: search backend unavailable'),
@@ -444,7 +456,9 @@ describe('Trace Viewer', () => {
expect(screen.queryByRole('treeitem', { name: recordName('llm') })).not.toBeInTheDocument(),
);
expect(stepRow(1)).toBeInTheDocument();
- expect(screen.getByRole('treeitem', { name: recordName('web_search') })).toBeInTheDocument();
+ expect(
+ screen.getByRole('treeitem', { name: recordName('com_ui_tool_name_web_search') }),
+ ).toBeInTheDocument();
await userEvent.clear(screen.getByLabelText('com_ui_trace_search'));
await userEvent.type(screen.getByLabelText('com_ui_trace_search'), 'nothing matches');
@@ -706,11 +720,11 @@ describe('Trace Viewer', () => {
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 recordRow('web_search'));
+ await userEvent.click(await recordRow('com_ui_tool_name_web_search'));
act(() => keepNewestTracePage(client, 'convo-1'));
expect(await screen.findByRole('button', { name: 'com_ui_trace_load_older' })).toBeVisible();
- expect(inspectorHeading()).toHaveTextContent('web_search');
+ expect(inspectorHeading()).toHaveTextContent('com_ui_tool_name_web_search');
await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));
await userEvent.click(toggle('com_ui_trace_all_spans'));
@@ -860,4 +874,140 @@ describe('Trace Viewer', () => {
expect(screen.getByRole('button', { name: 'com_ui_trace_close' })).toHaveFocus();
});
+
+ describe('a run as the agents SDK records it', () => {
+ const scout = { id: 'agent_scout', name: 'Codebase Scout', description: 'Reads the repo.' };
+ const sdkRecords: TTraceRecord[] = [
+ record({ id: 'run', kind: 'agent', role: 'run', name: 'AgentGraph', endTime: at(5000) }),
+ record({
+ id: 'scout',
+ parentId: 'run',
+ role: 'agent',
+ agentId: 'agent_scout',
+ name: 'agent_scout',
+ endTime: at(5000),
+ }),
+ record({
+ id: 'llm-1',
+ parentId: 'scout',
+ kind: 'generation',
+ role: 'model',
+ name: 'llm',
+ startTime: at(100),
+ }),
+ record({
+ id: 'label-1',
+ parentId: 'scout',
+ kind: 'generation',
+ role: 'stepLabel',
+ name: 'StepLabel',
+ startTime: at(1050),
+ }),
+ record({
+ id: 'round-1',
+ parentId: 'scout',
+ role: 'tools',
+ name: 'tool-dispatch',
+ startTime: at(1100),
+ endTime: at(2000),
+ }),
+ record({
+ id: 'llm-2',
+ parentId: 'scout',
+ kind: 'generation',
+ role: 'model',
+ name: 'llm',
+ startTime: at(2100),
+ }),
+ ];
+ const messages = [
+ {
+ messageId: 'user-1',
+ conversationId: 'convo-1',
+ parentMessageId: null,
+ isCreatedByUser: true,
+ text: 'Where does the trace viewer\nread from?',
+ },
+ {
+ ...responseMessage,
+ content: [
+ { type: ContentTypes.TEXT, text: 'Let me look that up.' },
+ { type: ContentTypes.ACTIVITY_LABEL, activity_label: 'Finding the trace reader' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'web_search', args: { query: 'weather' }, output: 'Sunny.' },
+ },
+ { type: ContentTypes.TEXT, text: 'It reads from Langfuse.' },
+ ],
+ },
+ ] as unknown as TMessage[];
+
+ function renderSdkRun() {
+ jest
+ .spyOn(dataService, 'getConversationTraceRecords')
+ .mockResolvedValue({ records: sdkRecords, sourceId: 'tenant-project' });
+ const client = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ logger: { log: () => undefined, warn: () => undefined, error: () => undefined },
+ });
+ client.setQueryData([QueryKeys.messages, 'convo-1'], messages);
+ return render(
+ <MemoryRouter>
+ <Provider>
+ <QueryClientProvider client={client}>
+ <AgentsMapContext.Provider value={{ agent_scout: scout } as unknown as TAgentsMap}>
+ <Viewer conversationId="convo-1" onClose={jest.fn()} />
+ </AgentsMapContext.Provider>
+ </QueryClientProvider>
+ </Provider>
+ </MemoryRouter>,
+ );
+ }
+
+ it('reads as the chat does: the question, the model, the label it showed and the tools it ran', async () => {
+ renderSdkRun();
+
+ expect(await recordRow('com_ui_model: Let me look that up\\.')).toBeInTheDocument();
+ const turn = screen.getByRole('treeitem', { name: /^com_ui_trace_turn/ });
+ expect(turn).toHaveAccessibleName(/Where does the trace viewer read from\?/);
+ expect(turn).toHaveAccessibleName(/com_ui_trace_model_calls_count 2/);
+ expect(turn).toHaveAccessibleName(/com_ui_trace_tool_calls_count_one 1/);
+ expect(
+ screen.getByRole('treeitem', {
+ name: recordName('com_ui_trace_role_step_label: Finding the trace reader'),
+ }),
+ ).toBeInTheDocument();
+ expect(screen.queryByRole('treeitem', { name: /tool-dispatch|StepLabel/ })).toBeNull();
+ const summary = screen.getByLabelText('com_ui_trace_summary');
+ expect(within(summary).getByText('com_ui_trace_summary_tools').nextSibling).toHaveTextContent(
+ '1',
+ );
+
+ await userEvent.click(await recordRow('com_ui_tool_name_web_search: query: weather'));
+
+ const inspector = screen.getByTestId('trace-inspector');
+ expect(within(inspector).getByText(/"query": "weather"/)).toBeInTheDocument();
+ expect(within(inspector).getByText('Sunny.')).toBeInTheDocument();
+ expect(within(inspector).getByText('tool-dispatch')).toBeInTheDocument();
+ expect(dataService.getConversationTraceRecord).not.toHaveBeenCalled();
+ });
+
+ it('shows the agent by name with its id to copy and a chat one click away', async () => {
+ renderSdkRun();
+ await recordRow('com_ui_model: Let me look that up\\.');
+
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+ await userEvent.click(await recordRow('Codebase Scout'));
+
+ const inspector = screen.getByTestId('trace-inspector');
+ expect(within(inspector).getByText('Reads the repo.')).toBeInTheDocument();
+ expect(within(inspector).getByText('agent_scout', { selector: '.select-all' })).toBeVisible();
+ expect(
+ within(inspector).getByRole('link', { name: 'com_ui_trace_chat_with_agent' }),
+ ).toHaveAttribute('href', '/c/new?agent_id=agent_scout');
+ expect(
+ within(inspector).getByRole('button', { name: 'com_ui_trace_copy_agent_id' }),
+ ).toBeInTheDocument();
+ });
+ });
});
diff --git a/client/src/components/Chat/Trace/__tests__/model.test.ts b/client/src/components/Chat/Trace/__tests__/model.test.ts
index 24d875169d..822c33159f 100644
--- a/client/src/components/Chat/Trace/__tests__/model.test.ts
+++ b/client/src/components/Chat/Trace/__tests__/model.test.ts
@@ -234,6 +234,7 @@ describe('buildTraceModel', () => {
duration: 4000,
turns: 1,
generations: 2,
+ labels: 0,
toolCalls: 1,
errors: 1,
running: 0,
@@ -882,3 +883,87 @@ describe('lanes', () => {
expect(sequenceLane(record({ id: 'e', kind: 'event' }))).toBe(2);
});
});
+
+/** A response as the agents SDK exports it: wrappers around each model call, tool rounds the host ran, label calls. */
+const sdkRun: TTraceRecord[] = [
+ record({ id: 'run', kind: 'agent', role: 'run', name: 'AgentGraph', endTime: at(9000) }),
+ record({
+ id: 'scout',
+ parentId: 'run',
+ role: 'agent',
+ agentId: 'agent_scout',
+ name: 'agent_scout',
+ endTime: at(9000),
+ }),
+ record({ id: 'graph', parentId: 'scout', kind: 'agent', role: 'run', name: 'AgentGraph' }),
+ record({ id: 'node-1', parentId: 'graph', kind: 'agent', role: 'plumbing', name: 'agent' }),
+ record({
+ id: 'llm-1',
+ parentId: 'node-1',
+ kind: 'generation',
+ role: 'model',
+ name: 'llm',
+ startTime: at(100),
+ endTime: at(1000),
+ usage: { input: 100, output: 10, total: 110 },
+ }),
+ record({
+ id: 'label-1',
+ parentId: 'graph',
+ kind: 'generation',
+ role: 'stepLabel',
+ name: 'StepLabel',
+ startTime: at(1050),
+ endTime: at(1400),
+ usage: { input: 20, output: 5, total: 25 },
+ }),
+ record({
+ id: 'round-1',
+ parentId: 'graph',
+ role: 'tools',
+ name: 'tool-dispatch',
+ startTime: at(1100),
+ endTime: at(3000),
+ }),
+ record({ id: 'node-2', parentId: 'graph', kind: 'agent', role: 'plumbing', name: 'agent' }),
+ record({
+ id: 'llm-2',
+ parentId: 'node-2',
+ kind: 'generation',
+ role: 'model',
+ name: 'llm',
+ startTime: at(3100),
+ endTime: at(4000),
+ usage: { input: 200, output: 20, total: 220 },
+ }),
+];
+
+describe('roles', () => {
+ const model = buildTraceModel(sdkRun, 'simple');
+ const [turn] = model.turns;
+
+ it('counts a label call as spend, never as a model call or a step of the response', () => {
+ expect(turn.steps).toBe(2);
+ expect(turn.generations).toBe(2);
+ expect(turn.labels).toBe(1);
+ expect(model.summary).toMatchObject({ generations: 2, labels: 1, totalTokens: 355 });
+ });
+
+ it('lists a tool round the host ran and the label beside the model call that led to them', () => {
+ const first = model.steps.get(turn.stepKeys[0]);
+ expect(first?.generationId).toBe('llm-1');
+ expect(first?.rootIds).toEqual(['llm-1', 'label-1', 'round-1']);
+ expect(model.nodes.get('round-1')?.shown).toBe(true);
+ expect(model.nodes.get('node-1')?.shown).toBe(false);
+ expect(sequenceLane(sdkRun[6])).toBe(1);
+ expect(sequenceLane(sdkRun[5])).toBe(2);
+ });
+
+ it('stamps every record beneath a saved agent with that agent', () => {
+ expect(model.nodes.get('llm-2')?.agentId).toBe('agent_scout');
+ expect(model.nodes.get('round-1')?.agentId).toBe('agent_scout');
+ expect(model.nodes.get('run')?.agentId).toBeUndefined();
+ expect(model.steps.get(turn.stepKeys[1])?.agentId).toBe('agent_scout');
+ expect(turn.agents).toEqual([{ agentId: 'agent_scout', recordId: 'scout' }]);
+ });
+});
diff --git a/client/src/components/Chat/Trace/__tests__/present.test.ts b/client/src/components/Chat/Trace/__tests__/present.test.ts
new file mode 100644
index 0000000000..8c94ce43f7
--- /dev/null
+++ b/client/src/components/Chat/Trace/__tests__/present.test.ts
@@ -0,0 +1,178 @@
+import { ContentTypes } from 'librechat-data-provider';
+import type { Agent, TMessage, TTraceRecord } from 'librechat-data-provider';
+import type { PresentationSources } from '../present';
+import { buildPreviews, buildActivityIndex } from '../preview';
+import { presentRecord } from '../present';
+import { buildTraceModel } 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 generation = (id: string, role: TTraceRecord['role'], name: string, start: number) =>
+ record({ id, parentId: 'scout', kind: 'generation', role, name, startTime: at(start) });
+const round = (id: string, start: number) =>
+ record({ id, parentId: 'scout', role: 'tools', name: 'tool-dispatch', startTime: at(start) });
+
+const records: TTraceRecord[] = [
+ record({ id: 'run', kind: 'agent', role: 'run', name: 'AgentGraph' }),
+ record({
+ id: 'scout',
+ parentId: 'run',
+ role: 'agent',
+ agentId: 'agent_scout',
+ name: 'agent_scout',
+ }),
+ generation('llm-1', 'model', 'llm', 100),
+ generation('label-1', 'stepLabel', 'StepLabel', 1050),
+ round('paused', 1100),
+ round('round-1', 1500),
+ generation('llm-2', 'model', 'llm', 3000),
+ round('round-2', 4000),
+ generation('llm-3', 'model', 'llm', 5000),
+];
+
+const response = {
+ messageId: 'response-1',
+ conversationId: 'convo-1',
+ parentMessageId: 'user-1',
+ isCreatedByUser: false,
+ text: '',
+ content: [
+ { type: ContentTypes.TEXT, text: 'Looking.' },
+ { type: ContentTypes.ACTIVITY_LABEL, activity_label: 'Finding the trace reader' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'web_search', args: { query: 'langfuse' }, output: 'ten results' },
+ },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'search_code_mcp_github', args: { q: 'TraceReader' } },
+ },
+ { type: ContentTypes.TEXT, text: 'One more.' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'read_file', args: { path: 'a.ts' } } },
+ { type: ContentTypes.TEXT, text: 'Done.' },
+ ],
+} as unknown as TMessage;
+
+const scout = { id: 'agent_scout', name: 'Codebase Scout', model: 'claude-opus-5' } as Agent;
+
+function present(messages: TMessage[], agents: Record<string, Agent> = { agent_scout: scout }) {
+ const model = buildTraceModel(records, 'full');
+ const activity = buildActivityIndex(model, buildPreviews(messages));
+ const sources: PresentationSources = {
+ localize: (key, values) => (values ? `${key} ${Object.values(values).join(' ')}` : key),
+ activity,
+ previewOf: () => undefined,
+ agentOf: (agentId) => agents[agentId],
+ mcpServerNames: ['github'],
+ };
+ const of = (id: string) => {
+ const node = model.nodes.get(id);
+ if (node == null) {
+ throw new Error(`no record ${id}`);
+ }
+ return presentRecord(node, sources);
+ };
+ return { activity, of };
+}
+
+describe('buildActivityIndex', () => {
+ it("gives a round's calls to the tool round that ran them, not the one an approval paused", () => {
+ const { activity } = present([response]);
+
+ expect(activity.calls.get('paused')).toBeUndefined();
+ expect(activity.calls.get('round-1')?.map((call) => call.name)).toEqual([
+ 'web_search',
+ 'search_code_mcp_github',
+ ]);
+ expect(activity.calls.get('round-1')?.[0]).toMatchObject({
+ args: 'query: langfuse',
+ input: '{"query":"langfuse"}',
+ output: 'ten results',
+ });
+ expect(activity.calls.get('round-2')?.map((call) => call.name)).toEqual(['read_file']);
+ expect(activity.unrecordedCalls.get('response-1')).toBe(3);
+ });
+
+ it('pairs a label with the model call that wrote it only while the counts agree', () => {
+ expect(present([response]).activity.labels.get('label-1')).toBe('Finding the trace reader');
+
+ const twoLabels = {
+ ...response,
+ content: [
+ ...(response.content ?? []),
+ { type: ContentTypes.ACTIVITY_LABEL, activity_label: 'Another' },
+ ],
+ } as TMessage;
+ expect(present([twoLabels]).activity.labels.size).toBe(0);
+ });
+
+ it('attributes nothing when the message and the trace disagree on the rounds', () => {
+ const short = { ...response, content: response.content?.slice(0, 4) } as TMessage;
+ const { activity } = present([short]);
+
+ expect(activity.calls.size).toBe(0);
+ expect(activity.unrecordedCalls.size).toBe(0);
+ });
+});
+
+describe('presentRecord', () => {
+ it("reads a record in the chat's words and keeps the recorded name for the details", () => {
+ const { of } = present([response]);
+
+ expect(of('llm-1')).toMatchObject({ title: 'com_ui_model', technicalName: 'llm' });
+ expect(of('run')).toMatchObject({
+ title: 'com_ui_trace_role_run',
+ technicalName: 'AgentGraph',
+ });
+ expect(of('label-1')).toMatchObject({
+ title: 'com_ui_trace_role_step_label',
+ preview: 'Finding the trace reader',
+ });
+ expect(of('scout')).toMatchObject({
+ title: 'Codebase Scout',
+ caption: 'claude-opus-5',
+ agent: scout,
+ });
+ });
+
+ it('names a tool round by its tools, as the chat names them', () => {
+ const { of } = present([response]);
+
+ expect(of('round-1')).toMatchObject({
+ title: 'com_ui_trace_role_tools_count 2',
+ preview: 'com_ui_tool_name_web_search, search_code',
+ toolNames: ['web_search', 'search_code_mcp_github'],
+ });
+ expect(of('round-1').calls?.[1]).toMatchObject({ title: 'search_code', caption: 'github' });
+ expect(of('round-2')).toMatchObject({
+ title: 'com_ui_tool_name_read_file',
+ preview: 'path: a.ts',
+ });
+ expect(of('paused')).toEqual({
+ title: 'com_ui_trace_role_tools',
+ technicalName: 'tool-dispatch',
+ });
+ });
+
+ it('keeps the agent row when the agent can no longer be loaded', () => {
+ expect(present([response], {}).of('scout')).toMatchObject({
+ title: 'com_ui_agent',
+ agent: null,
+ });
+ });
+});
diff --git a/client/src/components/Chat/Trace/__tests__/preview.test.ts b/client/src/components/Chat/Trace/__tests__/preview.test.ts
index 8888bce163..d9a7355dcf 100644
--- a/client/src/components/Chat/Trace/__tests__/preview.test.ts
+++ b/client/src/components/Chat/Trace/__tests__/preview.test.ts
@@ -66,9 +66,17 @@ describe('buildStepPreviews', () => {
{
text: 'Let me check the weather for you.',
toolCalls: [
- { name: 'web_search', args: 'query: weather in Paris, limit: 3' },
- { name: 'web_search', args: 'query: weather in Lyon' },
- { name: 'read_file', args: 'path: notes.md' },
+ {
+ name: 'web_search',
+ args: 'query: weather in Paris, limit: 3',
+ input: '{"query":"weather in Paris","limit":3}',
+ },
+ {
+ name: 'web_search',
+ args: 'query: weather in Lyon',
+ input: '{"query":"weather in Lyon"}',
+ },
+ { name: 'read_file', args: 'path: notes.md', input: '{"path":"notes.md"}' },
],
},
{ text: 'Paris is sunny, Lyon is not.', toolCalls: [] },
@@ -95,11 +103,11 @@ describe('buildStepPreviews', () => {
{
text: '',
toolCalls: [
- { name: 'ls', args: '' },
- { name: 'cat', args: 'path: a' },
+ { name: 'ls', args: '', input: '{}' },
+ { name: 'cat', args: 'path: a', input: '{"path":"a"}' },
],
},
- { text: '', toolCalls: [{ name: 'cat', args: 'path: b' }] },
+ { text: '', toolCalls: [{ name: 'cat', args: 'path: b', input: '{"path":"b"}' }] },
{ text: 'Both read.', toolCalls: [] },
]);
});
@@ -114,8 +122,8 @@ describe('buildStepPreviews', () => {
} as Partial<TMessage>);
expect(buildStepPreviews(rounds)).toEqual([
- { text: '', toolCalls: [{ name: 'ls', args: '' }] },
- { text: '', toolCalls: [{ name: 'cat', args: 'path: a' }] },
+ { text: '', toolCalls: [{ name: 'ls', args: '', input: '{}' }] },
+ { text: '', toolCalls: [{ name: 'cat', args: 'path: a', input: '{"path":"a"}' }] },
]);
});
@@ -132,7 +140,7 @@ describe('buildStepPreviews', () => {
expect(buildStepPreviews(compacted)).toEqual([
{ text: 'Before.', toolCalls: [] },
{ text: '', toolCalls: [] },
- { text: '', toolCalls: [{ name: 'ls', args: '' }] },
+ { text: '', toolCalls: [{ name: 'ls', args: '', input: '{}' }] },
{ text: 'After.', toolCalls: [] },
]);
});
@@ -376,7 +384,7 @@ describe('buildPreviewIndex', () => {
);
expect(handoff).toEqual([
- { text: 'Agent A.', toolCalls: [{ name: 'ls', args: '' }] },
+ { text: 'Agent A.', toolCalls: [{ name: 'ls', args: '', input: '{}' }] },
{ text: 'Agent B.', toolCalls: [] },
]);
});
diff --git a/client/src/components/Chat/Trace/kinds.ts b/client/src/components/Chat/Trace/kinds.ts
index 3f1e047f9b..45deb32ac8 100644
--- a/client/src/components/Chat/Trace/kinds.ts
+++ b/client/src/components/Chat/Trace/kinds.ts
@@ -1,5 +1,5 @@
-import { Bot, Zap, Wrench, Sparkles, Workflow } from 'lucide-react';
-import type { TTraceRecordKind, TTraceStatus } from 'librechat-data-provider';
+import { Bot, Tag, Zap, Wrench, Sparkles, Workflow } from 'lucide-react';
+import type { TTraceRecord, TTraceRecordKind, TTraceStatus } from 'librechat-data-provider';
import type { LucideIcon } from 'lucide-react';
import type { TranslationKeys } from '~/hooks';
@@ -51,6 +51,29 @@ export const KIND_APPEARANCE: Record<TTraceRecordKind, KindAppearance> = {
},
};
+const LABEL_APPEARANCE: KindAppearance = {
+ icon: Tag,
+ label: 'com_ui_trace_kind_label',
+ bar: 'bg-series-4',
+ tint: 'bg-series-4/30',
+ fill: 'fill-series-4',
+};
+
+/** A record's role says more than its kind: a tool round is recorded as a plain span, a label as a model call. */
+const ROLE_APPEARANCE: Partial<Record<NonNullable<TTraceRecord['role']>, KindAppearance>> = {
+ tools: KIND_APPEARANCE.tool,
+ agent: KIND_APPEARANCE.agent,
+ stepLabel: LABEL_APPEARANCE,
+ reasoningLabel: LABEL_APPEARANCE,
+ phaseLabel: LABEL_APPEARANCE,
+};
+
+export function appearanceOf(record: Pick<TTraceRecord, 'kind' | 'role'>): KindAppearance {
+ return (
+ (record.role != null ? ROLE_APPEARANCE[record.role] : undefined) ?? KIND_APPEARANCE[record.kind]
+ );
+}
+
export const STATUS_LABEL: Record<TTraceStatus, TranslationKeys> = {
ok: 'com_ui_trace_status_ok',
running: 'com_ui_trace_status_running',
diff --git a/client/src/components/Chat/Trace/model.ts b/client/src/components/Chat/Trace/model.ts
index c291567b9f..568725a836 100644
--- a/client/src/components/Chat/Trace/model.ts
+++ b/client/src/components/Chat/Trace/model.ts
@@ -29,6 +29,8 @@ export type TraceNode = {
stepKey: string | null;
/** Order among shown records: the record's position on the sequence scale. */
sequence: number;
+ /** The saved agent the record ran under: its nearest `agent` ancestor's. */
+ agentId?: string;
};
export type TraceStep = {
@@ -38,6 +40,7 @@ export type TraceStep = {
index: number;
origin: 'run' | 'title';
generationId: string | null;
+ agentId?: string;
rootIds: string[];
start: number;
end: number;
@@ -61,7 +64,11 @@ export type TraceTurn = {
recordCount: number;
errorCount: number;
generations: number;
+ /** Model calls that wrote an activity label; they are spend, not work of the response. */
+ labels: number;
toolCalls: number;
+ /** Saved agents that ran in the response, each with the record that stands for it. */
+ agents: Array<{ agentId: string; recordId: string }>;
sequence: TraceSpan;
};
@@ -69,6 +76,7 @@ export type TraceSummary = {
duration: number;
turns: number;
generations: number;
+ labels: number;
toolCalls: number;
errors: number;
running: number;
@@ -117,6 +125,7 @@ const EMPTY_SUMMARY: TraceSummary = {
duration: 0,
turns: 0,
generations: 0,
+ labels: 0,
toolCalls: 0,
errors: 0,
running: 0,
@@ -151,11 +160,32 @@ const byStart = (nodes: Map<string, TraceNode>) => (a: string, b: string) => {
);
};
+const LABEL_ROLES: ReadonlySet<TTraceRecord['role']> = new Set([
+ 'stepLabel',
+ 'reasoningLabel',
+ 'phaseLabel',
+]);
+
+/** A model call that wrote one of the activity labels the chat shows while a response runs. */
+export function isLabelRecord(record: TTraceRecord): boolean {
+ return LABEL_ROLES.has(record.role);
+}
+
+/** A model call of the response itself: it starts a step, and the chat's message describes it. */
+export function isModelCall(record: TTraceRecord): boolean {
+ return record.kind === 'generation' && !isLabelRecord(record);
+}
+
+/** A tool, or the round of tool calls a host ran without recording each one. */
+export function isToolWork(record: TTraceRecord): boolean {
+ return record.kind === 'tool' || record.role === 'tools';
+}
+
/** The records the simple mode lists: what the model did, anything that failed, and the title run. */
function isSimpleRecord(record: TTraceRecord): boolean {
return (
record.kind === 'generation' ||
- record.kind === 'tool' ||
+ isToolWork(record) ||
record.status === 'error' ||
record.origin === 'title'
);
@@ -163,7 +193,7 @@ function isSimpleRecord(record: TTraceRecord): boolean {
/** The records others hang from: what the model called. A failed wrapper stays visible but holds nothing. */
function isStepAnchor(record: TTraceRecord): boolean {
- return record.kind === 'generation' || record.kind === 'tool';
+ return record.kind === 'generation' || isToolWork(record);
}
function toNode(record: TTraceRecord): TraceNode | null {
@@ -395,11 +425,15 @@ function groupSteps(
const latestByLane = new Map<string, { rootIds: string[]; lane: string }>();
let leading: string[] = [];
for (const id of roots) {
- const kind = nodes.get(id)?.record.kind;
+ const record = nodes.get(id)?.record;
const lane = laneOf(id);
const current = groups[groups.length - 1];
- /** A tool whose lane has no model call loaded yet (an older page holds it) leads its own step. */
- if (kind === 'generation' || (kind === 'tool' && !latestByLane.has(lane))) {
+ /** A tool whose lane has no model call loaded yet (an older page holds it) leads its own step.
+ * A label's model call describes a step; it never starts one. */
+ if (
+ record != null &&
+ (isModelCall(record) || (isToolWork(record) && !latestByLane.has(lane)))
+ ) {
const group = { rootIds: [...leading, id], lane };
groups.push(group);
latestByLane.set(lane, group);
@@ -422,6 +456,7 @@ function groupSteps(
index: index + 1,
origin,
generationId,
+ agentId: nodes.get(generationId ?? rootIds[0])?.agentId,
rootIds,
start: Number.POSITIVE_INFINITY,
end: Number.NEGATIVE_INFINITY,
@@ -470,8 +505,36 @@ function groupSteps(
});
}
-const isGenerationId = (nodes: Map<string, TraceNode>) => (id: string) =>
- nodes.get(id)?.record.kind === 'generation';
+const isGenerationId = (nodes: Map<string, TraceNode>) => (id: string) => {
+ const record = nodes.get(id)?.record;
+ return record != null && isModelCall(record);
+};
+
+/** Stamps each record with its nearest `agent` ancestor's saved agent, caching every path walked. */
+function resolveAgents(nodes: Map<string, TraceNode>): void {
+ const resolved = new Map<string, string | undefined>();
+ for (const node of nodes.values()) {
+ const path: TraceNode[] = [];
+ let current: TraceNode | undefined = node;
+ let agentId: string | undefined;
+ while (current != null) {
+ if (resolved.has(current.record.id)) {
+ agentId = resolved.get(current.record.id);
+ break;
+ }
+ path.push(current);
+ if (current.record.agentId != null) {
+ agentId = current.record.agentId;
+ break;
+ }
+ current = current.parentId != null ? nodes.get(current.parentId) : undefined;
+ }
+ for (const visited of path) {
+ resolved.set(visited.record.id, agentId);
+ visited.agentId = agentId;
+ }
+ }
+}
/** Walks a shown subtree in ledger order, setting depth and the sequence position. */
function numberSubtree(nodes: Map<string, TraceNode>, rootIds: string[], next: number): number {
@@ -512,6 +575,7 @@ export function buildTraceModel(
}
resolveParents(nodes);
+ resolveAgents(nodes);
const turnsWithWork = turnsWithSimpleRecords(nodes);
const ancestors = new Map<string, string | null>();
resolveViewTree(nodes, mode, turnsWithWork, ancestors);
@@ -548,7 +612,9 @@ export function buildTraceModel(
recordCount: 0,
errorCount: 0,
generations: 0,
+ labels: 0,
toolCalls: 0,
+ agents: [],
sequence: EMPTY_SPAN,
};
turnsByMessage.set(record.messageId, turn);
@@ -570,9 +636,17 @@ export function buildTraceModel(
turn.toolCalls++;
summary.toolCalls++;
}
+ if (record.agentId != null && !turn.agents.some((agent) => agent.agentId === record.agentId)) {
+ turn.agents.push({ agentId: record.agentId, recordId: id });
+ }
if (record.kind === 'generation') {
- turn.generations++;
- summary.generations++;
+ if (isLabelRecord(record)) {
+ turn.labels++;
+ summary.labels++;
+ } else {
+ turn.generations++;
+ summary.generations++;
+ }
const input = record.usage?.input ?? 0;
const output = record.usage?.output ?? 0;
const total = record.usage?.total ?? input + output;
@@ -850,10 +924,10 @@ export function assignLanes(model: TraceModel, laneCount: number): Map<string, n
/** On the sequence scale nothing overlaps, so lanes separate kinds: model calls, tools, the rest. */
export function sequenceLane(record: TTraceRecord): number {
- if (record.kind === 'generation') {
+ if (isModelCall(record)) {
return 0;
}
- return record.kind === 'tool' ? 1 : 2;
+ return isToolWork(record) ? 1 : 2;
}
/** Clamps a zoom window inside the trace and keeps it at least `minSpan` wide. */
diff --git a/client/src/components/Chat/Trace/present.ts b/client/src/components/Chat/Trace/present.ts
new file mode 100644
index 0000000000..2849c7bdb3
--- /dev/null
+++ b/client/src/components/Chat/Trace/present.ts
@@ -0,0 +1,114 @@
+import type { Agent, TTraceRecord, TTraceRecordRole } from 'librechat-data-provider';
+import type { ActivityIndex, ToolCallPreview } from './preview';
+import type { TranslationKeys } from '~/hooks';
+import type { TraceNode } from './model';
+import { parseToolName } from '~/utils/toolLabels';
+
+type Localize = (key: TranslationKeys, values?: Record<string, string | number>) => string;
+
+/** How a row reads to someone who has never seen a trace: the record in the chat's own words. */
+export type RecordPresentation = {
+ title: string;
+ /** Where the work ran, beside the title: an MCP server, or the saved agent's model. */
+ caption?: string;
+ /** What the record produced or was given, taken from the chat's own message. */
+ preview?: string;
+ /** Set when `title` replaced the backend's name, which the technical details still show. */
+ technicalName?: string;
+ /** The saved agent the row stands for; `null` when the record names one this user cannot load. */
+ agent?: Agent | null;
+ /** The tools a row stands for, for their icons: a recorded tool, or an unrecorded round's calls. */
+ toolNames?: string[];
+ calls?: ToolCallView[];
+};
+
+/** A call of an unrecorded tool round, named the way its chat tool card names it. */
+export type ToolCallView = ToolCallPreview & Pick<RecordPresentation, 'title' | 'caption'>;
+
+export type PresentationSources = {
+ localize: Localize;
+ activity: ActivityIndex;
+ previewOf: (node: TraceNode) => string | undefined;
+ agentOf: (agentId: string) => Agent | undefined;
+ mcpServerNames?: readonly string[];
+};
+
+const ROLE_TITLES: Record<
+ Exclude<TTraceRecordRole, 'agent' | 'tools' | 'plumbing'>,
+ TranslationKeys
+> = {
+ run: 'com_ui_trace_role_run',
+ model: 'com_ui_model',
+ stepLabel: 'com_ui_trace_role_step_label',
+ reasoningLabel: 'com_ui_trace_role_reasoning_label',
+ phaseLabel: 'com_ui_trace_role_phase_label',
+};
+
+/** A tool's name as the chat's tool cards give it: a built-in's friendly name, or an MCP tool beside its server. */
+export function presentTool(
+ name: string,
+ { localize, mcpServerNames }: Pick<PresentationSources, 'localize' | 'mcpServerNames'>,
+): Pick<RecordPresentation, 'title' | 'caption'> {
+ const parsed = parseToolName(name, mcpServerNames);
+ if (parsed.friendlyKey != null) {
+ return { title: localize(parsed.friendlyKey) };
+ }
+ return { title: parsed.toolName, caption: parsed.mcpServer || undefined };
+}
+
+function presentToolRound(record: TTraceRecord, sources: PresentationSources): RecordPresentation {
+ const { localize, activity } = sources;
+ const calls = activity.calls.get(record.id);
+ const technicalName = record.name;
+ if (calls == null || calls.length === 0) {
+ return { title: localize('com_ui_trace_role_tools'), technicalName };
+ }
+ const views = calls.map((call) => ({ ...call, ...presentTool(call.name, sources) }));
+ const toolNames = calls.map((call) => call.name);
+ if (views.length === 1) {
+ const [{ title, caption, args }] = views;
+ return { title, caption, preview: args, technicalName, toolNames, calls: views };
+ }
+ const titles = [...new Set(views.map((view) => view.title))];
+ return {
+ title: localize('com_ui_trace_role_tools_count', { count: calls.length }),
+ preview: titles.join(', '),
+ technicalName,
+ toolNames,
+ calls: views,
+ };
+}
+
+export function presentRecord(node: TraceNode, sources: PresentationSources): RecordPresentation {
+ const { record } = node;
+ const { localize, activity, previewOf, agentOf } = sources;
+ if (record.role === 'agent' && record.agentId != null) {
+ const agent = agentOf(record.agentId) ?? null;
+ return {
+ title: agent?.name || localize('com_ui_agent'),
+ caption: agent?.model ?? undefined,
+ technicalName: record.name,
+ agent,
+ };
+ }
+ if (record.role === 'tools') {
+ return presentToolRound(record, sources);
+ }
+ /** A wrapper only frames a model call; every span as recorded is where it shows, under its own name. */
+ if (record.role != null && record.role !== 'agent' && record.role !== 'plumbing') {
+ const named = record.role === 'model' && record.origin === 'title';
+ return {
+ title: localize(named ? 'com_ui_trace_role_title' : ROLE_TITLES[record.role]),
+ preview: activity.labels.get(record.id) ?? previewOf(node),
+ technicalName: record.name,
+ };
+ }
+ if (record.kind === 'tool') {
+ return {
+ ...presentTool(record.name, sources),
+ preview: previewOf(node),
+ toolNames: [record.name],
+ };
+ }
+ return { title: record.name, preview: previewOf(node) };
+}
diff --git a/client/src/components/Chat/Trace/preview.ts b/client/src/components/Chat/Trace/preview.ts
index 85a2dc82bb..d67612f7e3 100644
--- a/client/src/components/Chat/Trace/preview.ts
+++ b/client/src/components/Chat/Trace/preview.ts
@@ -1,12 +1,15 @@
import { ContentTypes } from 'librechat-data-provider';
import type { TMessage, TMessageContentParts } from 'librechat-data-provider';
import type { TraceModel } from './model';
+import { getActivityLabelPart, getActivityLabelText, isPhaseActivityLabel } from '~/utils';
+import { isModelCall, isToolWork } from './model';
import { hasParallelLanes } from '~/utils/lanes';
const PREVIEW_LENGTH = 160;
const ELLIPSIS = '…';
-type ToolCallPreview = { name: string; args: string };
+/** `args` is the one-line preview; `input` and `output` are what the chat's own tool card holds. */
+export type ToolCallPreview = { name: string; args: string; input?: string; output?: string };
/** What one model call of a response produced: the text it wrote and the tools it called. */
export type StepPreview = { text: string; toolCalls: ToolCallPreview[] };
@@ -21,8 +24,12 @@ export type MessagePreview = {
finalOnly: boolean;
/** Agents ran in parallel lanes, whose output cannot be told apart by order. */
parallel: boolean;
+ /** The activity labels the chat showed, in the order they were written, by the kind of label. */
+ labels: Record<LabelRole, string[]>;
};
+type LabelRole = 'stepLabel' | 'phaseLabel';
+
function compact(text: string): string {
const collapsed = text.replace(/\s+/g, ' ').trim();
return collapsed.length > PREVIEW_LENGTH
@@ -58,6 +65,13 @@ function argsPreview(args: string | object | undefined): string {
return compact(pairs.join(', '));
}
+function contentOf(value: string | object | null | undefined): string | undefined {
+ if (value == null || value === '') {
+ return undefined;
+ }
+ return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
type ToolCallPart = Extract<TMessageContentParts, { type: ContentTypes.TOOL_CALL }>['tool_call'];
/** A tool call's name and arguments, whichever of the persisted call shapes carries them. */
@@ -66,10 +80,16 @@ function callOf(call: ToolCallPart | undefined): ToolCallPreview | null {
return null;
}
if ('function' in call && call.function != null) {
- return { name: call.function.name, args: argsPreview(call.function.arguments) };
+ const { name, arguments: input, output } = call.function;
+ return { name, args: argsPreview(input), input: contentOf(input), output: contentOf(output) };
}
if ('name' in call && typeof call.name === 'string') {
- return { name: call.name, args: argsPreview(call.args) };
+ return {
+ name: call.name,
+ args: argsPreview(call.args),
+ input: contentOf(call.args),
+ output: 'output' in call ? contentOf(call.output) : undefined,
+ };
}
return null;
}
@@ -95,6 +115,7 @@ export function buildMessagePreview(message: TMessage | undefined): MessagePrevi
let lastRunStep: string | undefined;
let roundAgent: string | undefined;
const parallel = hasParallelLanes(parts);
+ const labels: MessagePreview['labels'] = { stepLabel: [], phaseLabel: [] };
let sealed = false;
const begin = () => {
current = { text: '', toolCalls: [] };
@@ -115,6 +136,14 @@ export function buildMessagePreview(message: TMessage | undefined): MessagePrevi
if (part == null) {
continue;
}
+ if (part.type === ContentTypes.ACTIVITY_LABEL) {
+ const label = getActivityLabelPart(part);
+ const text = getActivityLabelText(label);
+ if (text) {
+ labels[isPhaseActivityLabel(label) ? 'phaseLabel' : 'stepLabel'].push(text);
+ }
+ continue;
+ }
if (part.type === ContentTypes.TOOL_CALL) {
const runStep = runStepOf(part.tool_call);
const handedOff = handoff(part);
@@ -161,7 +190,12 @@ export function buildMessagePreview(message: TMessage | undefined): MessagePrevi
parts.some((part) => part?.type === ContentTypes.ERROR);
/** A failed turn's row stores the failure as its text; the model never wrote it. */
if (steps.length === 0 && message?.text && !endedEarly) {
- return { steps: [{ text: compact(message.text), toolCalls: [] }], finalOnly: true, parallel };
+ return {
+ steps: [{ text: compact(message.text), toolCalls: [] }],
+ finalOnly: true,
+ parallel,
+ labels,
+ };
}
const finalOnly =
!endedEarly &&
@@ -169,7 +203,7 @@ export function buildMessagePreview(message: TMessage | undefined): MessagePrevi
steps.length === 1 &&
steps[0].toolCalls.length === 0 &&
steps[0].text !== '';
- return { steps, finalOnly, parallel };
+ return { steps, finalOnly, parallel, labels };
}
export function buildStepPreviews(message: TMessage | undefined): StepPreview[] {
@@ -246,7 +280,7 @@ export function buildPreviewIndex(
const ordinals = new Map<string, number>();
for (const node of roots) {
const { record } = node;
- if (record.kind === 'generation') {
+ if (isModelCall(record)) {
if (round.text) {
index.set(record.id, round.text);
}
@@ -280,3 +314,97 @@ export function buildPreviews(
}
return previews;
}
+
+/** What the chat's messages say about records the trace only names: tool rounds and activity labels. */
+export type ActivityIndex = {
+ /** The calls of a tool round the host ran without recording each one, by the round's record id. */
+ calls: Map<string, ToolCallPreview[]>;
+ /** The text a label's model call wrote, by its record id. */
+ labels: Map<string, string>;
+ /** Tool calls the trace holds no record of, by response: what a turn's own count misses. */
+ unrecordedCalls: Map<string, number>;
+};
+
+const hasToolRecord = (model: TraceModel) => (id: string) => {
+ const record = model.nodes.get(id)?.record;
+ return record != null && isToolWork(record);
+};
+
+/**
+ * Attributes the message's tool calls and activity labels to trace records. A
+ * round's calls go to its one tool-round record that holds no recorded tools (a
+ * round re-entered after an approval pause has several, and only the last one
+ * ran them). Labels pair with their model calls in the order both were written,
+ * and only when the counts agree, under the rule the previews follow.
+ */
+export function buildActivityIndex(
+ model: TraceModel,
+ previewsByMessage: ReadonlyMap<string, MessagePreview>,
+ partialMessageId?: string,
+): ActivityIndex {
+ const calls: ActivityIndex['calls'] = new Map();
+ const labels: ActivityIndex['labels'] = new Map();
+ const unrecordedCalls: ActivityIndex['unrecordedCalls'] = new Map();
+ const stepsByTurn = new Map(model.turns.map((turn) => [turn.messageId, turn.steps]));
+ const aligned = (messageId: string): MessagePreview | undefined => {
+ const message = previewsByMessage.get(messageId);
+ return message == null || message.parallel || messageId === partialMessageId
+ ? undefined
+ : message;
+ };
+
+ for (const step of model.steps.values()) {
+ const message = aligned(step.messageId);
+ if (
+ message == null ||
+ message.finalOnly ||
+ step.origin === 'title' ||
+ message.steps.length !== stepsByTurn.get(step.messageId)
+ ) {
+ continue;
+ }
+ const round = message.steps[step.index - 1];
+ let target: string | undefined;
+ for (const id of step.rootIds) {
+ const node = model.nodes.get(id);
+ if (node?.record.role === 'tools' && !node.childIds.some(hasToolRecord(model))) {
+ target = id;
+ }
+ }
+ if (target == null || round == null || round.toolCalls.length === 0) {
+ continue;
+ }
+ calls.set(target, round.toolCalls);
+ unrecordedCalls.set(
+ step.messageId,
+ (unrecordedCalls.get(step.messageId) ?? 0) + round.toolCalls.length,
+ );
+ }
+
+ const labelRecords = new Map<string, Record<LabelRole, Array<{ id: string; start: number }>>>();
+ for (const node of model.nodes.values()) {
+ const { role, messageId, id } = node.record;
+ if (role !== 'stepLabel' && role !== 'phaseLabel') {
+ continue;
+ }
+ const byRole = labelRecords.get(messageId) ?? { stepLabel: [], phaseLabel: [] };
+ byRole[role].push({ id, start: node.start });
+ labelRecords.set(messageId, byRole);
+ }
+ for (const [messageId, byRole] of labelRecords) {
+ const message = aligned(messageId);
+ if (message == null) {
+ continue;
+ }
+ for (const role of ['stepLabel', 'phaseLabel'] as const) {
+ const records = byRole[role];
+ const texts = message.labels[role];
+ if (records.length !== texts.length) {
+ continue;
+ }
+ records.sort((a, b) => a.start - b.start || a.id.localeCompare(b.id));
+ records.forEach((record, index) => labels.set(record.id, texts[index]));
+ }
+ }
+ return { calls, labels, unrecordedCalls };
+}
diff --git a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
index 72a66c62bc..310c773cb0 100644
--- a/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
+++ b/client/src/components/Chat/__tests__/ChatView.subagent.spec.tsx
@@ -68,6 +68,9 @@ jest.mock('../Presentation', () => ({ children }: { children: React.ReactNode })
));
jest.mock('../Input/ChatForm', () => () => <div data-testid="chat-form" />);
jest.mock('../Landing', () => () => <div data-testid="landing" />);
+jest.mock('../Trace', () => ({
+ TraceSurface: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
jest.mock('../Footer', () => ({
__esModule: true,
default: () => <div data-testid="footer" />,
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index d9b68ad1e6..037faac25d 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -2665,9 +2665,13 @@
"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_agent_details": "{{0}}, agent details",
+ "com_ui_trace_agent_unavailable": "This agent is no longer available to you.",
"com_ui_trace_all_spans": "All spans",
"com_ui_trace_all_spans_description": "Show every recorded span, not only model calls and tools",
+ "com_ui_trace_asked": "“{{0}}”",
"com_ui_trace_bar_description": "{{0}}, starts {{1}} in, {{2}}",
+ "com_ui_trace_chat_with_agent": "Chat with this agent",
"com_ui_trace_clear_selection": "Clear selection",
"com_ui_trace_close": "Close trace",
"com_ui_trace_close_details": "Close details",
@@ -2680,6 +2684,7 @@
"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_copy_agent_id": "Copy agent ID",
"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",
@@ -2692,17 +2697,21 @@
"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_from_conversation": "Shown from this conversation's own tool calls.",
"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_label": "Activity label",
"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_model_calls_count": "{{count}} model calls",
+ "com_ui_trace_model_calls_count_one": "{{count}} model call",
"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",
@@ -2711,8 +2720,16 @@
"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_recorded_as": "Recorded as",
"com_ui_trace_records": "Trace records",
"com_ui_trace_refresh": "Refresh trace",
+ "com_ui_trace_role_phase_label": "Phase label",
+ "com_ui_trace_role_reasoning_label": "Reasoning label",
+ "com_ui_trace_role_run": "Agent run",
+ "com_ui_trace_role_step_label": "Step label",
+ "com_ui_trace_role_title": "Named the conversation",
+ "com_ui_trace_role_tools": "Tool calls",
+ "com_ui_trace_role_tools_count": "Used {{count}} tools",
"com_ui_trace_scale_duration": "Duration",
"com_ui_trace_scale_duration_description": "Scale the overview and bars by recorded time instead of one block per record",
"com_ui_trace_search": "Search records",
@@ -2724,13 +2741,12 @@
"com_ui_trace_status_running": "In progress",
"com_ui_trace_status_warning": "Warning",
"com_ui_trace_step": "Step {{0}}",
- "com_ui_trace_steps_count": "{{count}} steps",
- "com_ui_trace_steps_count_one": "{{count}} step",
"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_labels": "Labels",
"com_ui_trace_summary_tokens": "Tokens",
"com_ui_trace_summary_tools": "Tool calls",
"com_ui_trace_summary_turns": "Responses",
@@ -2739,6 +2755,8 @@
"com_ui_trace_title_step": "Title",
"com_ui_trace_tool_calls_count": "{{count}} tool calls",
"com_ui_trace_tool_calls_count_one": "{{count}} tool call",
+ "com_ui_trace_tool_returned": "What came back",
+ "com_ui_trace_tool_sent": "What the agent sent",
"com_ui_trace_tool_times": "{{0}}×{{1}}",
"com_ui_trace_tools_more": "+{{0}} more",
"com_ui_trace_trace_id": "Trace ID",
diff --git a/packages/api/src/langfuse/reader.spec.ts b/packages/api/src/langfuse/reader.spec.ts
index 18006fc054..073dba7cfa 100644
--- a/packages/api/src/langfuse/reader.spec.ts
+++ b/packages/api/src/langfuse/reader.spec.ts
@@ -1021,6 +1021,7 @@ describe('createLangfuseTraceReader', () => {
messageId: 'response-1',
parentId: null,
kind: 'agent',
+ role: 'run',
name: 'AgentGraph',
startTime: '2026-09-12T11:30:00.000Z',
endTime: '2026-09-12T11:30:05.000Z',
@@ -1032,6 +1033,7 @@ describe('createLangfuseTraceReader', () => {
messageId: 'response-1',
parentId: 'obs-root',
kind: 'generation',
+ role: 'model',
name: 'llm',
model: 'claude-haiku-4-5',
startTime: '2026-09-12T11:30:00.000Z',
@@ -1064,6 +1066,7 @@ describe('createLangfuseTraceReader', () => {
messageId: 'response-1',
parentId: 'obs-root',
kind: 'span',
+ role: 'tools',
name: 'tool-dispatch',
startTime: '2026-09-12T11:30:00.000Z',
endTime: '2026-09-12T11:30:05.000Z',
diff --git a/packages/api/src/langfuse/reader.ts b/packages/api/src/langfuse/reader.ts
index 422781d8fe..ae8fb058f4 100644
--- a/packages/api/src/langfuse/reader.ts
+++ b/packages/api/src/langfuse/reader.ts
@@ -21,6 +21,7 @@ import { TraceReadError } from '~/traces/types';
import { mergeHeaders } from '~/utils/headers';
import { redirectPolicyFor } from './utils';
import { traceIdForMessage } from './trace';
+import { resolveTraceRole } from './roles';
const OBSERVATIONS_PATH = '/api/public/v2/observations';
const MAX_PAGE_SIZE = 1000;
@@ -184,12 +185,14 @@ function toRecord(
const model = (observation.model ?? observation.providedModelName)?.trim();
const usage = toUsage(observation.usageDetails);
const cost = toCost(observation);
+ const kind = KIND_BY_TYPE[type] ?? 'span';
return {
id: observation.id,
traceId: observation.traceId,
messageId,
parentId: observation.parentObservationId || null,
- kind: KIND_BY_TYPE[type] ?? 'span',
+ kind,
+ ...resolveTraceRole(kind, name),
name: clamp(name, NAME_MAX_LENGTH),
startTime: new Date(observation.startTime).toISOString(),
status,
diff --git a/packages/api/src/langfuse/roles.spec.ts b/packages/api/src/langfuse/roles.spec.ts
new file mode 100644
index 0000000000..183dcb1e70
--- /dev/null
+++ b/packages/api/src/langfuse/roles.spec.ts
@@ -0,0 +1,37 @@
+import { resolveTraceRole } from './roles';
+
+describe('resolveTraceRole', () => {
+ it('names the run, its saved agent and the wrappers around a model call', () => {
+ expect(resolveTraceRole('agent', 'AgentGraph')).toEqual({ role: 'run' });
+ expect(resolveTraceRole('agent', 'MultiAgentGraph')).toEqual({ role: 'run' });
+ expect(resolveTraceRole('span', 'agent_ZwXQuP527oibHg8S2qNV3')).toEqual({
+ role: 'agent',
+ agentId: 'agent_ZwXQuP527oibHg8S2qNV3',
+ });
+ expect(resolveTraceRole('agent', 'agent')).toEqual({ role: 'plumbing' });
+ expect(resolveTraceRole('span', 'AgentModelCall')).toEqual({ role: 'plumbing' });
+ expect(resolveTraceRole('span', 'prompt')).toEqual({ role: 'plumbing' });
+ expect(resolveTraceRole('span', 'tool-dispatch')).toEqual({ role: 'tools' });
+ });
+
+ it('tells the model calls that wrote activity labels from the ones that answered', () => {
+ expect(resolveTraceRole('generation', 'StepLabel')).toEqual({ role: 'stepLabel' });
+ expect(resolveTraceRole('generation', 'ReasoningLabel')).toEqual({ role: 'reasoningLabel' });
+ expect(resolveTraceRole('generation', 'MultiStepLabelGeneration')).toEqual({
+ role: 'phaseLabel',
+ });
+ expect(resolveTraceRole('span', 'MultiStepLabel')).toEqual({ role: 'plumbing' });
+ expect(resolveTraceRole('generation', 'llm')).toEqual({ role: 'model' });
+ expect(resolveTraceRole('generation', 'ChatOpenAI')).toEqual({});
+ expect(resolveTraceRole('span', 'llm')).toEqual({});
+ });
+
+ it('gives no role to a name a deployment or a tool chose', () => {
+ expect(resolveTraceRole('tool', 'tool-dispatch')).toEqual({});
+ expect(resolveTraceRole('tool', 'agent_lookup')).toEqual({});
+ expect(resolveTraceRole('generation', 'agent_ZwXQuP527oibHg8S2qNV3')).toEqual({});
+ expect(resolveTraceRole('generation', 'AgentGraph')).toEqual({});
+ expect(resolveTraceRole('span', 'StepLabel')).toEqual({});
+ expect(resolveTraceRole('span', 'My Research Agent')).toEqual({});
+ });
+});
diff --git a/packages/api/src/langfuse/roles.ts b/packages/api/src/langfuse/roles.ts
new file mode 100644
index 0000000000..6a61a1aaa1
--- /dev/null
+++ b/packages/api/src/langfuse/roles.ts
@@ -0,0 +1,59 @@
+import {
+ ACTIVITY_LABEL_RUN_NAME,
+ ACTIVITY_PHASE_RUN_NAME,
+ STANDARD_GRAPH_RUN_NAME,
+ REASONING_LABEL_RUN_NAME,
+ AGENT_MODEL_CALL_RUN_NAME,
+ MULTI_AGENT_GRAPH_RUN_NAME,
+ ACTIVITY_PHASE_LABEL_RUN_NAME,
+} from '@librechat/agents';
+import type { TTraceRecord, TTraceRecordRole } from 'librechat-data-provider';
+
+/** Span names the agents SDK assigns while shaping a trace for export, which it does not export. */
+const AGENT_NODE_NAME = 'agent';
+const PROMPT_NAME = 'prompt';
+const MODEL_CALL_NAME = 'llm';
+const TOOL_DISPATCH_NAME = 'tool-dispatch';
+/** The SDK names an agent's workflow node with the saved agent's bare id. */
+const SAVED_AGENT_ID = /^agent_[A-Za-z0-9_-]+$/;
+
+const ROLE_BY_NAME: Record<string, TTraceRecordRole> = {
+ [STANDARD_GRAPH_RUN_NAME]: 'run',
+ [MULTI_AGENT_GRAPH_RUN_NAME]: 'run',
+ [AGENT_NODE_NAME]: 'plumbing',
+ [AGENT_MODEL_CALL_RUN_NAME]: 'plumbing',
+ [PROMPT_NAME]: 'plumbing',
+ [ACTIVITY_PHASE_RUN_NAME]: 'plumbing',
+ [MODEL_CALL_NAME]: 'model',
+ [TOOL_DISPATCH_NAME]: 'tools',
+ [ACTIVITY_LABEL_RUN_NAME]: 'stepLabel',
+ [REASONING_LABEL_RUN_NAME]: 'reasoningLabel',
+ [ACTIVITY_PHASE_LABEL_RUN_NAME]: 'phaseLabel',
+};
+
+/** A tool or a model call may carry any name a deployment gave it, so only the SDK's own spans have a role. */
+const NAMED_BY_SDK: ReadonlySet<TTraceRecord['kind']> = new Set(['agent', 'span', 'generation']);
+const MODEL_CALL_ROLES: ReadonlySet<TTraceRecordRole> = new Set([
+ 'model',
+ 'stepLabel',
+ 'reasoningLabel',
+ 'phaseLabel',
+]);
+
+/** What a record did in the run, read from the names the agents SDK gives the spans it exports. */
+export function resolveTraceRole(
+ kind: TTraceRecord['kind'],
+ name: string,
+): Pick<TTraceRecord, 'role' | 'agentId'> {
+ if (!NAMED_BY_SDK.has(kind)) {
+ return {};
+ }
+ if (kind !== 'generation' && SAVED_AGENT_ID.test(name)) {
+ return { role: 'agent', agentId: name };
+ }
+ const role = ROLE_BY_NAME[name];
+ if (role == null || (kind === 'generation') !== MODEL_CALL_ROLES.has(role)) {
+ return {};
+ }
+ return { role };
+}
diff --git a/packages/data-provider/src/types/traces.ts b/packages/data-provider/src/types/traces.ts
index 8210e69b37..1dec9cce57 100644
--- a/packages/data-provider/src/types/traces.ts
+++ b/packages/data-provider/src/types/traces.ts
@@ -6,6 +6,24 @@
export type TTraceRecordKind = 'agent' | 'generation' | 'tool' | 'span' | 'event';
+/**
+ * What a record did in the run, in the application's own terms, so a client never reads a tracing
+ * backend's span names. Absent on a record the backend did not describe: it is listed by `kind`.
+ * `run` is a whole agent run, `agent` the named agent inside it, `plumbing` a wrapper that only
+ * frames a model call, `model` a model call of the response, `tools` one round of tool calls, and
+ * the label roles are the model calls that wrote the activity labels the chat shows while a
+ * response runs.
+ */
+export type TTraceRecordRole =
+ | 'run'
+ | 'agent'
+ | 'plumbing'
+ | 'model'
+ | 'tools'
+ | 'stepLabel'
+ | 'reasoningLabel'
+ | 'phaseLabel';
+
/** `running` marks a record with no end time yet; it has a start but no duration. */
export type TTraceStatus = 'ok' | 'warning' | 'error' | 'running';
@@ -26,6 +44,9 @@ export type TTraceRecord = {
/** `null` for a root; may name a record that is not loaded (or does not exist). */
parentId: string | null;
kind: TTraceRecordKind;
+ role?: TTraceRecordRole;
+ /** The saved agent a `role: 'agent'` record ran; absent for an agent that was never saved. */
+ agentId?: string;
name: string;
model?: string;
/** ISO-8601 timestamps. */