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 Steps, Sequence Scale and Previews (#16009)

Danny Avilac153c4057fcd
diff --git a/client/src/components/Chat/Trace/Ledger.tsx b/client/src/components/Chat/Trace/Ledger.tsx
index 2631c73b86..e979cc082a 100644
--- a/client/src/components/Chat/Trace/Ledger.tsx
+++ b/client/src/components/Chat/Trace/Ledger.tsx
@@ -1,18 +1,29 @@
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 type {
+ TraceRow,
+ TraceNode,
+ TraceStep,
+ TraceTurn,
+ TraceSpan,
+ TraceModel,
+ TraceScale,
+ TraceWindow,
+} from './model';
+import { spanOf, stepSpan, turnSpan, turnKey, boundsOf } 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;
+/** Tool names a step header lists before summarizing the rest as a count. */
+const STEP_TOOL_NAMES = 3;
/** 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';
@@ -21,17 +32,25 @@ const GRID =
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}%`,
+const barStyle = (span: TraceSpan, domain: Domain): CSSProperties => ({
+ left: `${((span.start - domain.start) / domain.span) * 100}%`,
+ width: `${((span.end - span.start) / domain.span) * 100}%`,
});
-function RecordBar({ node, domain }: { node: TraceNode; domain: Domain }) {
+function RecordBar({
+ node,
+ scale,
+ domain,
+}: {
+ node: TraceNode;
+ scale: TraceScale;
+ 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) {
+ if (scale === 'time' && node.end == null) {
return (
<span
className={cn('absolute top-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rotate-45', solid)}
@@ -40,13 +59,16 @@ function RecordBar({ node, domain }: { node: TraceNode; domain: Domain }) {
);
}
- const duration = node.end - node.start;
+ const span = spanOf(node, scale);
+ const duration = span.end - span.start;
const ttftShare =
- node.firstToken != null && duration > 0 ? (node.firstToken - node.start) / duration : 0;
+ scale === 'time' && 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)}
+ style={barStyle(span, domain)}
>
{ttftShare > 0 && (
<span
@@ -62,11 +84,11 @@ function RecordBar({ node, domain }: { node: TraceNode; domain: Domain }) {
);
}
-function TurnBar({ turn, domain }: { turn: TraceTurn; domain: Domain }) {
+function GroupBar({ span, domain }: { span: TraceSpan; 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)}
+ style={barStyle(span, domain)}
/>
);
}
@@ -80,33 +102,37 @@ function recordTokens(node: TraceNode): string {
return total > 0 ? formatTokens(total) : '';
}
-const toDomain = (start: number, end: number): Domain => ({
- start,
- span: Math.max(end - start, 1),
+const toDomain = (span: TraceSpan): Domain => ({
+ start: span.start,
+ span: Math.max(span.end - span.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
+ * The hierarchical record list: one row per turn, per step 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,
+ scale,
view,
selectedId,
treeRef,
+ previewFor,
onSelect,
onToggle,
}: {
rows: TraceRow[];
model: TraceModel;
+ scale: TraceScale;
view: TraceWindow | null;
selectedId: string | null;
treeRef: RefObject<HTMLDivElement>;
+ previewFor: (node: TraceNode) => string | undefined;
onSelect: (id: string) => void;
onToggle: (key: string) => void;
}) {
@@ -121,15 +147,18 @@ function Ledger({
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],
+ () => new Map(model.turns.map((turn) => [turn.messageId, toDomain(turnSpan(turn, scale))])),
+ [model, scale],
);
- const viewDomain = useMemo(() => (view ? toDomain(view.start, view.end) : null), [view]);
+ const viewDomain = useMemo(() => (view ? toDomain(view) : null), [view]);
+ const bounds = boundsOf(model, scale);
const domainFor = (messageId: string): Domain =>
- viewDomain ?? turnDomains.get(messageId) ?? toDomain(model.start, model.end);
+ viewDomain ?? turnDomains.get(messageId) ?? toDomain(bounds);
const activeIndex = activeKey != null ? (indexByKey.get(activeKey) ?? 0) : 0;
const activeRow = rows[activeIndex];
const rowId = (key: string) => `${idPrefix}-${key}`;
+ const position = (value: number) =>
+ scale === 'sequence' ? String(Math.round(value)) : format.duration(value - bounds.start);
/** Keeps a keyboard-moved row inside the viewport so its windowed element mounts. */
const scrollIntoView = (index: number) => {
@@ -163,11 +192,23 @@ function Ledger({
}
};
+ const parentKeyOf = (row: TraceRow): string | undefined => {
+ if (row.type === 'turn') {
+ return undefined;
+ }
+ if (row.type === 'step') {
+ return turnKey(row.step.messageId);
+ }
+ const { node } = row;
+ const stepParent = model.mode === 'simple' ? node.stepKey : null;
+ return node.viewParentId ?? stepParent ?? turnKey(node.record.messageId);
+ };
+
const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
if (!activeRow) {
return;
}
- const expandable = activeRow.type === 'turn' || activeRow.hasChildren;
+ const expandable = activeRow.type !== 'record' || activeRow.hasChildren;
const pageSize = Math.max(1, Math.floor((scrollRef.current?.clientHeight ?? 0) / ROW_HEIGHT));
const handlers: Record<string, () => void> = {
ArrowDown: () => moveTo(activeIndex + 1),
@@ -188,13 +229,10 @@ function Ledger({
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);
- }
+ const parentKey = parentKeyOf(activeRow);
+ const parentIndex = parentKey != null ? indexByKey.get(parentKey) : undefined;
+ if (parentIndex != null) {
+ moveTo(parentIndex);
}
},
Enter: () => activate(activeRow),
@@ -207,61 +245,142 @@ function Ledger({
}
};
- const renderRow = (row: TraceRow, index: number) => {
- const style: CSSProperties = { top: HEADER_HEIGHT + index * ROW_HEIGHT, height: ROW_HEIGHT };
+ const chevron = (expanded: boolean) => (
+ <ChevronRight
+ aria-hidden="true"
+ className={cn(
+ 'size-3.5 shrink-0 text-text-secondary transition-transform motion-reduce:transition-none',
+ expanded && 'rotate-90',
+ )}
+ />
+ );
+
+ const turnSummary = (turn: TraceTurn) =>
+ [
+ localize(turn.steps === 1 ? 'com_ui_trace_steps_count_one' : 'com_ui_trace_steps_count', {
+ count: turn.steps,
+ }),
+ localize(
+ turn.toolCalls === 1
+ ? 'com_ui_trace_tool_calls_count_one'
+ : 'com_ui_trace_tool_calls_count',
+ { count: turn.toolCalls },
+ ),
+ ].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,
+ );
+ if (names.length > STEP_TOOL_NAMES) {
+ tools.push(
+ localize('com_ui_trace_tools_more', { 0: String(names.length - STEP_TOOL_NAMES) }),
+ );
+ }
+ return [format.duration(step.end - step.start), ...tools].join(' · ');
+ };
+
+ const renderGroupRow = (
+ row: Extract<TraceRow, { type: 'turn' | 'step' }>,
+ index: number,
+ {
+ label,
+ description,
+ errorCount,
+ recordCount,
+ span,
+ messageId,
+ indent,
+ }: {
+ label: string;
+ description: string;
+ errorCount: number;
+ recordCount: number;
+ span: TraceSpan;
+ messageId: string;
+ indent: number;
+ },
+ ) => {
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),
- };
+ return (
+ <div
+ key={row.key}
+ id={rowId(row.key)}
+ role="treeitem"
+ aria-posinset={row.position}
+ aria-setsize={row.setSize}
+ aria-level={row.level}
+ aria-expanded={row.expanded}
+ aria-selected={false}
+ aria-label={`${label}, ${description}, ${localize('com_ui_trace_turn_records', { 0: String(recordCount) })}`}
+ style={{ top: HEADER_HEIGHT + index * ROW_HEIGHT, height: ROW_HEIGHT }}
+ onClick={() => activate(row)}
+ className={cn(
+ GRID,
+ 'absolute inset-x-0 cursor-pointer items-center gap-2 px-2 text-xs text-text-primary hover:bg-surface-hover',
+ row.type === 'turn'
+ ? 'border-t border-border-light bg-surface-primary-alt font-semibold'
+ : 'font-medium',
+ active && ACTIVE_RING,
+ )}
+ >
+ <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>
+ {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(
+ row.type === 'turn' ? row.turn.end - row.turn.start : row.step.end - row.step.start,
+ )}
+ </span>
+ <span className="hidden md:block" />
+ <span className="relative h-full overflow-hidden">
+ <GroupBar span={span} domain={domainFor(messageId)} />
+ </span>
+ </div>
+ );
+ };
+ const renderRow = (row: TraceRow, index: number) => {
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>
- );
+ return renderGroupRow(row, index, {
+ label: localize('com_ui_trace_turn', { 0: format.clock(turn.start) }),
+ description: turnSummary(turn),
+ errorCount: turn.errorCount,
+ recordCount: turn.recordCount,
+ span: turnSpan(turn, scale),
+ messageId: turn.messageId,
+ indent: 0,
+ });
+ }
+ if (row.type === 'step') {
+ const { step } = row;
+ return renderGroupRow(row, index, {
+ label:
+ step.origin === 'title'
+ ? localize('com_ui_trace_title_step')
+ : localize('com_ui_trace_step', { 0: String(step.index) }),
+ description: stepDescription(step),
+ errorCount: step.errorCount,
+ recordCount: step.recordCount,
+ span: stepSpan(step, scale),
+ messageId: step.messageId,
+ indent: INDENT_PX,
+ });
}
const { node } = row;
const { record } = node;
- const turnStart = turnDomains.get(record.messageId)?.start ?? model.start;
+ const active = activeRow?.key === row.key;
+ const turnStart = model.turns.find((turn) => turn.messageId === record.messageId)?.start;
const appearance = KIND_APPEARANCE[record.kind];
const Icon = appearance.icon;
const running = record.status === 'running';
@@ -270,19 +389,26 @@ 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;
return (
<div
key={row.key}
- {...common}
- aria-level={node.depth + 2}
+ id={rowId(row.key)}
+ role="treeitem"
+ aria-posinset={row.position}
+ aria-setsize={row.setSize}
+ aria-level={row.level}
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),
+ 0: `${name}, ${localize(appearance.label)}`,
+ 1: format.duration(node.start - (turnStart ?? model.start)),
2: statusText,
})}
+ style={{ top: HEADER_HEIGHT + index * ROW_HEIGHT, height: ROW_HEIGHT }}
+ onClick={() => activate(row)}
className={cn(
GRID,
'absolute inset-x-0 cursor-pointer items-center gap-2 px-2 text-sm text-text-primary hover:bg-surface-hover',
@@ -292,7 +418,7 @@ function Ledger({
>
<span
className="flex min-w-0 items-center gap-1.5"
- style={{ paddingLeft: node.depth * INDENT_PX }}
+ style={{ paddingLeft: (row.level - 2) * INDENT_PX }}
>
<span
aria-hidden="true"
@@ -305,17 +431,18 @@ function Ledger({
}}
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',
- )}
- />
- )}
+ {row.hasChildren && chevron(row.expanded)}
</span>
<Icon aria-hidden="true" className="size-3.5 shrink-0 text-text-secondary" />
- <span className="min-w-[3ch] truncate">{record.name}</span>
+ <span className="min-w-[3ch] max-w-[60%] truncate">{record.name}</span>
+ {preview != null && (
+ <span
+ className="min-w-[4ch] flex-1 truncate text-xs text-text-secondary"
+ title={preview}
+ >
+ {preview}
+ </span>
+ )}
{record.model != null && (
<span className="hidden min-w-0 shrink-[4] truncate text-xs text-text-secondary sm:inline">
{record.model}
@@ -335,7 +462,7 @@ function Ledger({
{recordTokens(node)}
</span>
<span className="relative h-full overflow-hidden">
- <RecordBar node={node} domain={domainFor(record.messageId)} />
+ <RecordBar node={node} scale={scale} domain={domainFor(record.messageId)} />
</span>
</div>
);
@@ -377,8 +504,8 @@ function Ledger({
<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>{position(viewDomain.start)}</span>
+ <span>{position(viewDomain.start + viewDomain.span)}</span>
</span>
) : (
<span>{localize('com_ui_trace_column_timeline')}</span>
diff --git a/client/src/components/Chat/Trace/Timeline.tsx b/client/src/components/Chat/Trace/Timeline.tsx
index 23724377cb..0e616b24ab 100644
--- a/client/src/components/Chat/Trace/Timeline.tsx
+++ b/client/src/components/Chat/Trace/Timeline.tsx
@@ -1,7 +1,18 @@
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 type { TraceModel, TraceScale, TraceWindow } from './model';
+import {
+ spanOf,
+ boundsOf,
+ turnSpan,
+ ZOOM_STEP,
+ zoomWindow,
+ panWindow,
+ assignLanes,
+ clampWindow,
+ minimumSpan,
+ sequenceLane,
+} from './model';
import { KIND_APPEARANCE } from './kinds';
import { useTraceFormat } from './format';
import { useLocalize } from '~/hooks';
@@ -19,15 +30,19 @@ 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.
+ * The pinned overview of the whole trace. It always draws every shown record
+ * at full scale; the focused interval is an overlay the ledger follows. On the
+ * sequence scale every record is one equal block, so a quick tool call beside a
+ * long model call stays visible.
*/
function Timeline({
model,
+ scale,
view,
onViewChange,
}: {
model: TraceModel;
+ scale: TraceScale;
view: TraceWindow | null;
onViewChange: (view: TraceWindow | null) => void;
}) {
@@ -38,13 +53,20 @@ function Timeline({
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 bounds = useMemo(() => boundsOf(model, scale), [model, scale]);
+ const span = Math.max(bounds.end - bounds.start, 1);
+ const minSpan = minimumSpan(bounds, scale);
+ const lanes = useMemo(
+ () => (scale === 'time' ? assignLanes(model, LANE_COUNT) : null),
+ [model, scale],
+ );
+ const records = useMemo(() => [...model.nodes.values()].filter((node) => node.shown), [model]);
const toFraction = useCallback(
- (time: number) => (time - model.start) / span,
- [model.start, span],
+ (position: number) => (position - bounds.start) / span,
+ [bounds.start, span],
);
+ const tick = (fraction: number) =>
+ scale === 'sequence' ? String(Math.round(span * fraction)) : format.duration(span * fraction);
const fractionAt = (clientX: number): number => {
const rect = surfaceRef.current?.getBoundingClientRect();
@@ -67,13 +89,13 @@ function Timeline({
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 anchor = bounds.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));
+ onViewChange(zoomWindow(bounds, view, factor, anchor, minSpan));
};
surface.addEventListener('wheel', handleWheel, { passive: false });
return () => surface.removeEventListener('wheel', handleWheel);
- }, [model, span, view, onViewChange]);
+ }, [bounds, span, minSpan, view, onViewChange]);
const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
if (event.button !== 0) {
@@ -111,9 +133,9 @@ function Timeline({
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),
+ { start: bounds.start + from * span, end: bounds.start + to * span },
+ bounds,
+ minSpan,
),
);
};
@@ -121,13 +143,13 @@ function Timeline({
const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
if (event.key === '+' || event.key === '=') {
event.preventDefault();
- onViewChange(zoomWindow(model, view, ZOOM_STEP));
+ onViewChange(zoomWindow(bounds, view, ZOOM_STEP, undefined, minSpan));
} else if (event.key === '-' || event.key === '_') {
event.preventDefault();
- onViewChange(zoomWindow(model, view, 1 / ZOOM_STEP));
+ onViewChange(zoomWindow(bounds, view, 1 / ZOOM_STEP, undefined, minSpan));
} else if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
event.preventDefault();
- onViewChange(panWindow(model, view, event.key === 'ArrowLeft' ? -1 : 1));
+ onViewChange(panWindow(bounds, view, event.key === 'ArrowLeft' ? -1 : 1, minSpan));
} else if (event.key === 'Escape' && view != null) {
event.preventDefault();
event.stopPropagation();
@@ -147,6 +169,7 @@ function Timeline({
aria-label={localize('com_ui_trace_overview')}
aria-describedby={hintId}
data-testid="trace-overview"
+ data-scale={scale}
onKeyDown={handleKeyDown}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
@@ -165,7 +188,7 @@ function Timeline({
{model.turns.map((turn) => (
<rect
key={turn.key}
- x={percent(toFraction(turn.start))}
+ x={percent(toFraction(turnSpan(turn, scale).start))}
y={0}
width={1}
height="100%"
@@ -174,11 +197,11 @@ function Timeline({
))}
{records.map((node) => {
const { record } = node;
- const lane = lanes.get(record.id) ?? 0;
+ 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;
- if (node.end == null) {
+ if (scale === 'time' && node.end == null) {
return (
<rect
key={record.id}
@@ -190,12 +213,13 @@ function Timeline({
/>
);
}
+ const recordSpan = spanOf(node, scale);
return (
<rect
key={record.id}
- x={percent(toFraction(node.start))}
+ x={percent(toFraction(recordSpan.start))}
y={y}
- width={`${Math.max(((node.end - node.start) / span) * 100, 0.15)}%`}
+ width={`${Math.max(((recordSpan.end - recordSpan.start) / span) * 100, 0.15)}%`}
height={LANE_HEIGHT}
rx={1}
className={fill}
@@ -231,8 +255,8 @@ function Timeline({
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>
+ {TICKS.map((fraction) => (
+ <span key={fraction}>{tick(fraction)}</span>
))}
</div>
<p id={hintId} className="sr-only">
diff --git a/client/src/components/Chat/Trace/Viewer.tsx b/client/src/components/Chat/Trace/Viewer.tsx
index cd7cfc64b0..5a10159cf8 100644
--- a/client/src/components/Chat/Trace/Viewer.tsx
+++ b/client/src/components/Chat/Trace/Viewer.tsx
@@ -1,10 +1,13 @@
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 { useAtom } from 'jotai';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { QueryKeys, dataService, resolveTraceViewerConfig } from 'librechat-data-provider';
import { Button, Spinner, EmptyState, FilterInput, buttonVariants } from '@librechat/client';
import {
X,
+ Clock,
+ Layers,
ZoomIn,
ZoomOut,
RefreshCw,
@@ -14,10 +17,15 @@ import {
TriangleAlert,
ChartNoAxesGantt,
} from 'lucide-react';
-import type { TTraceRecord, TTraceErrorCode, TTraceErrorResponse } from 'librechat-data-provider';
+import type {
+ TMessage,
+ TTraceRecord,
+ TTraceErrorCode,
+ TTraceErrorResponse,
+} from 'librechat-data-provider';
import type { KeyboardEvent } from 'react';
+import type { TraceNode, TraceWindow } from './model';
import type { TranslationKeys } from '~/hooks';
-import type { TraceWindow } from './model';
import {
keepNewestTracePage,
useGetStartupConfig,
@@ -25,13 +33,17 @@ import {
useConversationTraceRecordsQuery,
} from '~/data-provider';
import {
+ boundsOf,
ZOOM_STEP,
- fitWindow,
zoomWindow,
flattenRows,
+ minimumSpan,
+ rebaseWindow,
buildTraceModel,
collapsibleKeys,
} from './model';
+import { buildPreviews, buildPreviewIndex } from './preview';
+import { traceModeAtom, traceScaleAtom } from './store';
import { KIND_APPEARANCE, STATUS_LABEL } from './kinds';
import { useTraceFormat } from './format';
import { useLocalize } from '~/hooks';
@@ -50,6 +62,8 @@ const ERROR_MESSAGES: Partial<Record<TTraceErrorCode, TranslationKeys>> = {
unsupported: 'com_ui_trace_error_unsupported',
};
+const PRESSED = 'bg-surface-active-alt';
+
function errorCodeOf(error: unknown): TTraceErrorCode | undefined {
return axios.isAxiosError<TTraceErrorResponse>(error)
? error.response?.data?.errorCode
@@ -90,19 +104,20 @@ export default function Viewer({
conversationId,
startupConfig?.langfuseConnectionAccess === true,
);
+ /** The chat's own messages, already loaded underneath the trace; they are only read, never fetched here. */
+ const { data: messages } = useQuery<TMessage[]>(
+ [QueryKeys.messages, conversationId],
+ () => dataService.getMessagesByConvoId(conversationId),
+ { enabled: false },
+ );
+ const [mode, setMode] = useAtom(traceModeAtom);
+ const [scale, setScale] = useAtom(traceScaleAtom);
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');
@@ -139,16 +154,67 @@ export default function Viewer({
pages.every((page) => page.sourceId === langfuseSession.destinationId)
? langfuseSession.url
: undefined;
- const model = useMemo(() => buildTraceModel(records), [records]);
+ const model = useMemo(() => buildTraceModel(records, mode), [records, mode]);
+ const bounds = useMemo(() => boundsOf(model, scale), [model, scale]);
+ const minSpan = minimumSpan(bounds, scale);
+ const previews = useMemo(() => buildPreviews(messages), [messages]);
+ /** Pages split a response at the oldest loaded turn, whose earlier steps are still unloaded;
+ * its rounds cannot be numbered against the message until they are. */
+ const partialMessageId =
+ recordsQuery.hasNextPage === true ? model.turns[0]?.messageId : undefined;
+ const previewIndex = useMemo(
+ () => buildPreviewIndex(model, previews, partialMessageId),
+ [model, previews, partialMessageId],
+ );
+ const previewOf = useCallback(
+ (node: TraceNode) => previewIndex.get(node.record.id),
+ [previewIndex],
+ );
+ const labelsFor = useCallback(
+ (record: TTraceRecord) => {
+ const node = model.nodes.get(record.id);
+ const preview = node != null ? previewOf(node) : undefined;
+ return [
+ localize(KIND_APPEARANCE[record.kind].label),
+ localize(STATUS_LABEL[record.status]),
+ ...(preview != null ? [preview] : []),
+ ];
+ },
+ [localize, model, previewOf],
+ );
const rows = useMemo(
- () => flattenRows(model, { collapsed, query: deferredQuery, window: view, labelsFor }),
- [model, collapsed, deferredQuery, view, labelsFor],
+ () => flattenRows(model, { collapsed, query: deferredQuery, window: view, scale, labelsFor }),
+ [model, collapsed, deferredQuery, view, scale, 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. */
+ /** A refresh or a settled run trims the cache to its newest page, an older page renumbers the
+ * sequence, and a mode change hides records. A selection or interval on records no longer
+ * listed would leave an inspector on nothing, or hide every row, so both follow the records. */
+ const previousModel = useRef(model);
+ useEffect(() => {
+ const previous = previousModel.current;
+ previousModel.current = model;
+ setSelectedId((id) => (id != null && model.nodes.get(id)?.shown !== true ? null : id));
+ setView((current) =>
+ current != null ? rebaseWindow(current, previous, model, scale) : current,
+ );
+ }, [model, scale]);
+ /** Positions mean something else on the other scale or with other records shown. */
+ useEffect(() => {
+ setView(null);
+ }, [scale, mode]);
+ /** Older responses arrive folded to their summary; the newest one opens, since it is what the user just ran. */
+ const seenTurns = useRef(new Set<string>());
useEffect(() => {
- setSelectedId((id) => (id != null && !model.nodes.has(id) ? null : id));
- setView((current) => (current != null ? fitWindow(current, model) : current));
+ const newest = model.turns[model.turns.length - 1]?.key;
+ const fold = model.turns
+ .filter((turn) => !seenTurns.current.has(turn.key) && turn.key !== newest)
+ .map((turn) => turn.key);
+ for (const turn of model.turns) {
+ seenTurns.current.add(turn.key);
+ }
+ if (fold.length > 0) {
+ setCollapsed((current) => new Set([...current, ...fold]));
+ }
}, [model]);
const selectedNode = selectedId != null ? model.nodes.get(selectedId) : undefined;
const selectedTurnStart =
@@ -218,6 +284,22 @@ export default function Viewer({
</Button>
);
+ const selectionText = () => {
+ if (view == null) {
+ return null;
+ }
+ if (scale === 'sequence') {
+ return localize('com_ui_trace_selection_records', {
+ 0: String(Math.floor(view.start) + 1),
+ 1: String(Math.ceil(view.end)),
+ });
+ }
+ return localize('com_ui_trace_selection', {
+ 0: format.duration(view.start - model.start),
+ 1: format.duration(view.end - model.start),
+ });
+ };
+
const renderBody = () => {
if (recordsQuery.isLoading) {
return (
@@ -275,7 +357,7 @@ export default function Viewer({
</p>
)}
</div>
- <Timeline model={model} view={view} onViewChange={setView} />
+ <Timeline model={model} scale={scale} view={view} onViewChange={setView} />
<div className="flex flex-wrap items-center gap-2">
<FilterInput
inputId={searchId}
@@ -309,13 +391,34 @@ export default function Viewer({
<ChevronsDownUp className="size-4" aria-hidden="true" />
<span className="hidden sm:inline">{localize('com_ui_trace_collapse_all')}</span>
</Button>
+ <Button
+ size="sm"
+ variant="outline"
+ aria-label={localize('com_ui_trace_scale_duration')}
+ aria-pressed={scale === 'time'}
+ title={localize('com_ui_trace_scale_duration_description')}
+ className={cn(scale === 'time' && PRESSED)}
+ onClick={() => setScale(scale === 'time' ? 'sequence' : 'time')}
+ >
+ <Clock className="size-4" aria-hidden="true" />
+ <span className="hidden sm:inline">{localize('com_ui_trace_scale_duration')}</span>
+ </Button>
+ <Button
+ size="sm"
+ variant="outline"
+ aria-label={localize('com_ui_trace_all_spans')}
+ aria-pressed={mode === 'full'}
+ title={localize('com_ui_trace_all_spans_description')}
+ className={cn(mode === 'full' && PRESSED)}
+ onClick={() => setMode(mode === 'full' ? 'simple' : 'full')}
+ >
+ <Layers className="size-4" aria-hidden="true" />
+ <span className="hidden sm:inline">{localize('com_ui_trace_all_spans')}</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),
- })}
+ {selectionText()}
</span>
)}
<Button
@@ -323,7 +426,7 @@ export default function Viewer({
variant="ghost"
aria-label={localize('com_ui_zoom_out')}
disabled={view == null}
- onClick={() => setView(zoomWindow(model, view, 1 / ZOOM_STEP))}
+ onClick={() => setView(zoomWindow(bounds, view, 1 / ZOOM_STEP, undefined, minSpan))}
>
<ZoomOut className="size-4" aria-hidden="true" />
</Button>
@@ -331,7 +434,7 @@ export default function Viewer({
size="icon-sm"
variant="ghost"
aria-label={localize('com_ui_zoom_in')}
- onClick={() => setView(zoomWindow(model, view, ZOOM_STEP))}
+ onClick={() => setView(zoomWindow(bounds, view, ZOOM_STEP, undefined, minSpan))}
>
<ZoomIn className="size-4" aria-hidden="true" />
</Button>
@@ -353,9 +456,11 @@ export default function Viewer({
<Ledger
rows={rows}
model={model}
+ scale={scale}
view={view}
selectedId={selectedId}
treeRef={treeRef}
+ previewFor={previewOf}
onSelect={setSelectedId}
onToggle={toggle}
/>
diff --git a/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
index 2c1f6ea72e..ea2a8e72d9 100644
--- a/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
+++ b/client/src/components/Chat/Trace/__tests__/Viewer.test.tsx
@@ -1,9 +1,10 @@
import React from 'react';
+import { Provider } from 'jotai';
import userEvent from '@testing-library/user-event';
-import { dataService } from 'librechat-data-provider';
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 { TTracePage, TTraceRecord, TStartupConfig } from 'librechat-data-provider';
+import type { TMessage, TTracePage, TTraceRecord, TStartupConfig } from 'librechat-data-provider';
import { keepNewestTracePage } from '~/data-provider/Traces/queries';
import Viewer from '../Viewer';
@@ -24,7 +25,7 @@ jest.mock('~/data-provider/Endpoints/queries', () => ({
}));
jest.mock('~/hooks', () => ({
- useLocalize: () => (key: string, options?: Record<string, string>) =>
+ useLocalize: () => (key: string, options?: Record<string, string | number>) =>
options ? `${key} ${Object.values(options).join(' ')}` : key,
}));
@@ -71,6 +72,19 @@ const records: TTraceRecord[] = [
}),
];
+/** The chat's copy of the response: what the model wrote and asked for, which the ledger previews. */
+const responseMessage = {
+ messageId: 'response-1',
+ conversationId: 'convo-1',
+ parentMessageId: 'user-1',
+ isCreatedByUser: false,
+ text: '',
+ content: [
+ { type: ContentTypes.TEXT, text: 'Let me look that up.' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'web_search', args: { query: 'weather' } } },
+ ],
+} as unknown as TMessage;
+
function axiosError(status: number, errorCode: string) {
return Object.assign(new Error(errorCode), {
isAxiosError: true,
@@ -84,17 +98,26 @@ function renderViewer(onClose = jest.fn()) {
logger: { log: () => undefined, warn: () => undefined, error: () => undefined },
});
const utils = render(
- <QueryClientProvider client={client}>
- <Viewer conversationId="convo-1" onClose={onClose} />
- </QueryClientProvider>,
+ <Provider>
+ <QueryClientProvider client={client}>
+ <Viewer conversationId="convo-1" onClose={onClose} />
+ </QueryClientProvider>
+ </Provider>,
);
return { ...utils, onClose, client };
}
const treeItem = (name: RegExp) => screen.findByRole('treeitem', { name });
+/** A record row's accessible name; step and turn rows are named by their own labels. */
+const recordName = (name: string) => new RegExp(`^com_ui_trace_bar_description ${name}`);
+const recordRow = (name: string) => treeItem(recordName(name));
+const stepRow = (index: number) =>
+ screen.getByRole('treeitem', { name: new RegExp(`^com_ui_trace_step ${index},`) });
+const toggle = (name: string) => screen.getByRole('button', { name });
describe('Trace Viewer', () => {
beforeEach(() => {
+ window.localStorage.clear();
mockStartupConfig = { interface: { traceViewer: { enabled: true } } };
jest
.spyOn(dataService, 'getConversationTraceRecords')
@@ -109,21 +132,26 @@ describe('Trace Viewer', () => {
url: 'https://langfuse.test/project/p/sessions/convo-1',
destinationId: 'tenant-project',
});
+ jest.spyOn(dataService, 'getMessagesByConvoId').mockResolvedValue([]);
});
- it('shows a loading state, then the summary, overview and record tree', async () => {
+ it('shows a loading state, then the summary, overview and the response grouped into steps', 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(await recordRow('llm')).toHaveAttribute('aria-level', '3');
expect(
- screen.getByRole('treeitem', { name: /web_search.*com_ui_trace_status_error/ }),
+ screen.getByRole('treeitem', { name: recordName('web_search.*com_ui_trace_status_error') }),
).toBeInTheDocument();
- expect(screen.getByRole('treeitem', { name: /^com_ui_trace_turn/ })).toHaveAttribute(
- 'aria-level',
- '1',
- );
+ 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_tool_calls_count_one 1/);
+ expect(stepRow(1)).toHaveAttribute('aria-level', '2');
+ expect(stepRow(1)).toHaveAccessibleName(/web_search/);
+ expect(
+ screen.queryByRole('treeitem', { name: recordName('AgentGraph') }),
+ ).not.toBeInTheDocument();
const summary = screen.getByLabelText('com_ui_trace_summary');
expect(
@@ -133,18 +161,168 @@ describe('Trace Viewer', () => {
'1',
);
expect(within(summary).queryByText('com_ui_trace_summary_cost')).not.toBeInTheDocument();
- expect(screen.getByTestId('trace-overview')).toBeInTheDocument();
+ expect(screen.getByTestId('trace-overview')).toHaveAttribute('data-scale', 'sequence');
expect(dataService.getConversationTraceRecords).toHaveBeenCalledWith(
{ conversationId: 'convo-1', cursor: undefined },
expect.any(AbortSignal),
);
});
+ it('shows every recorded span when asked, and lists the model calls and tools otherwise', async () => {
+ renderViewer();
+ await recordRow('llm');
+
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+
+ expect(toggle('com_ui_trace_all_spans')).toHaveAttribute('aria-pressed', 'true');
+ expect(await recordRow('AgentGraph')).toHaveAttribute('aria-level', '2');
+ expect(screen.getByRole('treeitem', { name: recordName('llm') })).toHaveAttribute(
+ 'aria-level',
+ '3',
+ );
+ expect(screen.queryByRole('treeitem', { name: /^com_ui_trace_step/ })).not.toBeInTheDocument();
+
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+
+ await waitFor(() =>
+ expect(
+ screen.queryByRole('treeitem', { name: recordName('AgentGraph') }),
+ ).not.toBeInTheDocument(),
+ );
+ expect(stepRow(1)).toBeInTheDocument();
+ });
+
+ it('clears a selection the simple mode no longer lists', async () => {
+ renderViewer();
+ await recordRow('llm');
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+ await userEvent.click(await recordRow('AgentGraph'));
+ expect(screen.getByTestId('trace-inspector')).toBeInTheDocument();
+
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+
+ await waitFor(() => expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument());
+ });
+
+ it('keeps a focused record range on the same records when an older page renumbers them', async () => {
+ const newest = ['a', 'b', 'c'].map((suffix, index) =>
+ record({
+ id: `later-${suffix}`,
+ messageId: 'response-2',
+ traceId: 'trace-2',
+ name: `later-${suffix}`,
+ kind: 'generation',
+ startTime: at(10_000 + index * 1000),
+ endTime: at(10_500 + index * 1000),
+ }),
+ );
+ jest
+ .spyOn(dataService, 'getConversationTraceRecords')
+ .mockImplementation(async ({ cursor }) =>
+ cursor == null ? { records: newest, nextCursor: 'older' } : { records },
+ );
+ renderViewer();
+ await recordRow('later-b');
+ const overview = screen.getByTestId('trace-overview');
+ fireEvent.keyDown(overview, { key: '+' });
+ fireEvent.keyDown(overview, { key: '+' });
+ await waitFor(() =>
+ expect(
+ screen.queryByRole('treeitem', { name: recordName('later-a') }),
+ ).not.toBeInTheDocument(),
+ );
+ expect(screen.getByText('com_ui_trace_selection_records 2 2')).toBeInTheDocument();
+
+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));
+
+ expect(await screen.findByText('com_ui_trace_selection_records 4 4')).toBeInTheDocument();
+ expect(screen.getByRole('treeitem', { name: recordName('later-b') })).toBeInTheDocument();
+ expect(screen.queryByRole('treeitem', { name: recordName('llm') })).not.toBeInTheDocument();
+ expect(screen.queryByRole('treeitem', { name: recordName('later-a') })).not.toBeInTheDocument();
+ });
+
+ it('withholds previews for a response split across pages until its earlier steps load', async () => {
+ const generation = (id: string, offset: number) =>
+ record({
+ id,
+ messageId: 'response-2',
+ traceId: 'trace-2',
+ name: id,
+ kind: 'generation',
+ startTime: at(offset),
+ endTime: at(offset + 500),
+ });
+ jest
+ .spyOn(dataService, 'getConversationTraceRecords')
+ .mockImplementation(async ({ cursor }) =>
+ cursor == null
+ ? { records: [generation('later-2', 12_000)], nextCursor: 'older' }
+ : { records: [generation('later-1', 10_000), ...records] },
+ );
+ const { client } = renderViewer();
+ act(() =>
+ client.setQueryData(
+ [QueryKeys.messages, 'convo-1'],
+ [
+ {
+ ...responseMessage,
+ messageId: 'response-2',
+ content: [
+ { type: ContentTypes.TEXT, text: 'First round.' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'noop', args: {}, stepId: 's1' } },
+ { type: ContentTypes.TEXT, text: 'Second round.' },
+ ],
+ },
+ ],
+ ),
+ );
+ await recordRow('later-2,');
+ expect(
+ screen.queryByRole('treeitem', { name: /later-2: First round/ }),
+ ).not.toBeInTheDocument();
+
+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));
+
+ expect(await recordRow('later-2: Second round\\.')).toBeInTheDocument();
+ expect(
+ screen.getByRole('treeitem', { name: recordName('later-1: First round\\.') }),
+ ).toBeInTheDocument();
+ });
+
+ it('previews what a step wrote and what a tool was asked, from the chat message', async () => {
+ const { client } = renderViewer();
+ await recordRow('llm');
+
+ act(() => client.setQueryData([QueryKeys.messages, 'convo-1'], [responseMessage]));
+
+ expect(await recordRow('llm: Let me look that up\\.')).toBeInTheDocument();
+ expect(
+ screen.getByRole('treeitem', { name: recordName('web_search: query: weather') }),
+ ).toBeInTheDocument();
+ expect(dataService.getMessagesByConvoId).not.toHaveBeenCalled();
+ });
+
+ it('scales the overview by recorded time on request', async () => {
+ renderViewer();
+ await recordRow('llm');
+ const overview = screen.getByTestId('trace-overview');
+
+ fireEvent.keyDown(overview, { key: '+' });
+ expect(screen.getByText(/^com_ui_trace_selection_records/)).toBeInTheDocument();
+
+ await userEvent.click(toggle('com_ui_trace_scale_duration'));
+
+ expect(overview).toHaveAttribute('data-scale', 'time');
+ expect(screen.queryByTestId('trace-overview-selection')).not.toBeInTheDocument();
+ fireEvent.keyDown(overview, { key: '+' });
+ expect(screen.getByText(/^com_ui_trace_selection /)).toBeInTheDocument();
+ });
+
it('shows cost only when the deployment shows context cost', async () => {
mockStartupConfig = { interface: { traceViewer: { enabled: true }, contextCost: true } };
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
expect(screen.getByText('com_ui_trace_summary_cost')).toBeInTheDocument();
});
@@ -157,7 +335,7 @@ describe('Trace Viewer', () => {
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();
+ expect(await recordRow('llm')).toBeInTheDocument();
});
it('falls back to a generic message for an unknown failure', async () => {
@@ -179,14 +357,14 @@ describe('Trace Viewer', () => {
const emptyState = title.parentElement as HTMLElement;
await userEvent.click(within(emptyState).getByRole('button', { name: 'com_ui_trace_refresh' }));
- expect(await treeItem(/AgentGraph/)).toBeInTheDocument();
+ expect(await recordRow('llm')).toBeInTheDocument();
expect(list).toHaveBeenCalledTimes(2);
});
it('inspects a record without requesting content the deployment withholds', async () => {
renderViewer();
- await userEvent.click(await treeItem(/llm/));
+ await userEvent.click(await recordRow('llm'));
const inspector = screen.getByTestId('trace-inspector');
expect(within(inspector).getByRole('heading', { name: 'llm' })).toBeInTheDocument();
@@ -194,7 +372,10 @@ describe('Trace Viewer', () => {
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(screen.getByRole('treeitem', { name: recordName('llm') })).toHaveAttribute(
+ 'aria-selected',
+ 'true',
+ );
expect(dataService.getConversationTraceRecord).not.toHaveBeenCalled();
});
@@ -202,7 +383,7 @@ describe('Trace Viewer', () => {
mockStartupConfig = { interface: { traceViewer: { enabled: true, showInputOutput: true } } };
renderViewer();
- await userEvent.click(await treeItem(/llm/));
+ await userEvent.click(await recordRow('llm'));
const inspector = screen.getByTestId('trace-inspector');
expect(await within(inspector).findByText(/"content": "hi"/)).toBeInTheDocument();
@@ -222,7 +403,7 @@ describe('Trace Viewer', () => {
it('shows the error message for a failed record', async () => {
renderViewer();
- await userEvent.click(await treeItem(/web_search/));
+ await userEvent.click(await recordRow('web_search'));
expect(
within(screen.getByTestId('trace-inspector')).getByText('Error: search backend unavailable'),
@@ -243,7 +424,7 @@ describe('Trace Viewer', () => {
});
renderViewer();
- const row = await treeItem(/broken_tool/);
+ const row = await recordRow('broken_tool');
expect(row).not.toHaveAccessibleName(/com_ui_trace_status_running/);
expect(row).toHaveAccessibleName(/com_ui_trace_status_error/);
@@ -255,15 +436,15 @@ describe('Trace Viewer', () => {
it('filters the tree by search and keeps the match context', async () => {
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
await userEvent.type(screen.getByLabelText('com_ui_trace_search'), 'web');
await waitFor(() =>
- expect(screen.queryByRole('treeitem', { name: /llm/ })).not.toBeInTheDocument(),
+ expect(screen.queryByRole('treeitem', { name: recordName('llm') })).not.toBeInTheDocument(),
);
- expect(screen.getByRole('treeitem', { name: /AgentGraph/ })).toBeInTheDocument();
- expect(screen.getByRole('treeitem', { name: /web_search/ })).toBeInTheDocument();
+ expect(stepRow(1)).toBeInTheDocument();
+ expect(screen.getByRole('treeitem', { name: recordName('web_search') })).toBeInTheDocument();
await userEvent.clear(screen.getByLabelText('com_ui_trace_search'));
await userEvent.type(screen.getByLabelText('com_ui_trace_search'), 'nothing matches');
@@ -272,28 +453,26 @@ describe('Trace Viewer', () => {
it('folds and unfolds rows from the keyboard', async () => {
renderViewer();
- const root = await treeItem(/AgentGraph/);
+ await recordRow('llm');
const tree = screen.getByRole('tree');
- await userEvent.click(root);
- expect(root).toHaveAttribute('aria-expanded', 'true');
- fireEvent.keyDown(tree, { key: 'ArrowLeft' });
-
+ await userEvent.click(stepRow(1));
await waitFor(() =>
- expect(screen.queryByRole('treeitem', { name: /llm/ })).not.toBeInTheDocument(),
- );
- expect(screen.getByRole('treeitem', { name: /AgentGraph/ })).toHaveAttribute(
- 'aria-expanded',
- 'false',
+ expect(screen.queryByRole('treeitem', { name: recordName('llm') })).not.toBeInTheDocument(),
);
+ expect(stepRow(1)).toHaveAttribute('aria-expanded', 'false');
fireEvent.keyDown(tree, { key: 'ArrowRight' });
- expect(await treeItem(/llm/)).toBeInTheDocument();
+ expect(await recordRow('llm')).toBeInTheDocument();
+ expect(stepRow(1)).toHaveAttribute('aria-expanded', 'true');
fireEvent.keyDown(tree, { key: 'ArrowDown' });
expect(tree).toHaveAttribute(
'aria-activedescendant',
- screen.getByRole('treeitem', { name: /llm/ }).id,
+ screen.getByRole('treeitem', { name: recordName('llm') }).id,
);
+ fireEvent.keyDown(tree, { key: 'ArrowLeft' });
+ expect(tree).toHaveAttribute('aria-activedescendant', stepRow(1).id);
+ fireEvent.keyDown(tree, { key: 'ArrowDown' });
fireEvent.keyDown(tree, { key: 'Enter' });
expect(screen.getByTestId('trace-inspector')).toBeInTheDocument();
});
@@ -309,16 +488,17 @@ describe('Trace Viewer', () => {
}),
...Array.from({ length: 150 }, (_, index) =>
record({
- id: `step-${index}`,
+ id: `call-${index}`,
parentId: 'root',
- name: `step-${index}`,
+ kind: 'tool',
+ name: `call-${index}`,
startTime: at(index),
}),
),
];
jest.spyOn(dataService, 'getConversationTraceRecords').mockResolvedValue({ records: many });
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('call-0,');
const tree = screen.getByRole('tree');
fireEvent.focus(tree);
@@ -330,25 +510,26 @@ describe('Trace Viewer', () => {
tree.scrollTop = 140 * 32;
fireEvent.scroll(tree);
- expect(await treeItem(/step-140/)).toBeInTheDocument();
+ expect(await recordRow('call-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 recordRow('llm');
await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_collapse_all' }));
- expect(screen.queryByRole('treeitem', { name: /AgentGraph/ })).not.toBeInTheDocument();
+ expect(screen.queryByRole('treeitem', { name: recordName('llm') })).not.toBeInTheDocument();
+ expect(screen.queryByRole('treeitem', { name: /^com_ui_trace_step/ })).not.toBeInTheDocument();
await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_expand_all' }));
- expect(screen.getByRole('treeitem', { name: /llm/ })).toBeInTheDocument();
+ expect(screen.getByRole('treeitem', { name: recordName('llm') })).toBeInTheDocument();
});
it('focuses an interval from the overview keyboard and clears it', async () => {
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
const overview = screen.getByTestId('trace-overview');
fireEvent.keyDown(overview, { key: '+' });
@@ -373,15 +554,22 @@ describe('Trace Viewer', () => {
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(list).toHaveBeenLastCalledWith(
- { conversationId: 'convo-1', cursor: 'older' },
- expect.any(AbortSignal),
+ await waitFor(() =>
+ expect(
+ screen.queryByRole('button', { name: 'com_ui_trace_load_older' }),
+ ).not.toBeInTheDocument(),
);
- expect(
- screen.queryByRole('button', { name: 'com_ui_trace_load_older' }),
- ).not.toBeInTheDocument();
+ expect(screen.getByRole('treeitem', { name: recordName('llm') })).toHaveAttribute(
+ 'aria-level',
+ '3',
+ );
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+ expect(await recordRow('AgentGraph')).toHaveAttribute('aria-level', '2');
});
it('reports a failed refresh while every page is already loaded, with a retry', async () => {
@@ -391,12 +579,12 @@ describe('Trace Viewer', () => {
.mockRejectedValueOnce(axiosError(504, 'timeout'))
.mockResolvedValue({ records });
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
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();
+ expect(screen.getByRole('treeitem', { name: recordName('llm') })).toBeInTheDocument();
await userEvent.click(screen.getByRole('button', { name: 'com_ui_retry' }));
await waitFor(() => expect(screen.queryByRole('alert')).not.toBeInTheDocument());
@@ -427,14 +615,47 @@ describe('Trace Viewer', () => {
);
});
+ it('opens the newest response and folds older ones to their summary as they load', async () => {
+ const newest = [
+ record({
+ id: 'later',
+ messageId: 'response-2',
+ traceId: 'trace-2',
+ name: 'later-llm',
+ kind: 'generation',
+ startTime: at(10_000),
+ endTime: at(12_000),
+ }),
+ ];
+ jest
+ .spyOn(dataService, 'getConversationTraceRecords')
+ .mockImplementation(async ({ cursor }) =>
+ cursor == null ? { records: newest, nextCursor: 'older' } : { records },
+ );
+ renderViewer();
+ await recordRow('later-llm');
+
+ await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_load_older' }));
+
+ const turns = await screen.findAllByRole('treeitem', { name: /^com_ui_trace_turn/ });
+ expect(turns).toHaveLength(2);
+ expect(turns[0]).toHaveAttribute('aria-expanded', 'false');
+ expect(turns[1]).toHaveAttribute('aria-expanded', 'true');
+ expect(screen.queryByRole('treeitem', { name: recordName('llm,') })).not.toBeInTheDocument();
+
+ await userEvent.click(turns[0]);
+
+ expect(await recordRow('llm,')).toBeInTheDocument();
+ });
+
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',
+ name: 'later-llm',
+ kind: 'generation',
startTime: at(10_000),
endTime: at(12_000),
}),
@@ -446,20 +667,29 @@ describe('Trace Viewer', () => {
);
renderViewer();
await userEvent.click(await screen.findByRole('button', { name: 'com_ui_trace_load_older' }));
- await userEvent.click(await treeItem(/llm/));
+ await userEvent.click(
+ (await screen.findAllByRole('treeitem', { name: /^com_ui_trace_turn/ }))[0],
+ );
+ await userEvent.click(await recordRow('llm,'));
+ /** Two zooms narrow the sequence to the one middle record, leaving the newest page out. */
+ fireEvent.keyDown(screen.getByTestId('trace-overview'), { key: '+' });
fireEvent.keyDown(screen.getByTestId('trace-overview'), { key: '+' });
- expect(screen.queryByRole('treeitem', { name: /LaterGraph/ })).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole('treeitem', { name: recordName('later-llm') }),
+ ).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(await recordRow('later-llm')).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();
+ await waitFor(() =>
+ expect(screen.getAllByRole('treeitem', { name: /^com_ui_trace_turn/ })).toHaveLength(2),
+ );
expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();
});
@@ -476,21 +706,22 @@ 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 treeItem(/web_search/));
+ await userEvent.click(await recordRow('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/));
+ await userEvent.click(toggle('com_ui_trace_all_spans'));
+ await userEvent.click(await recordRow('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(await recordRow('AgentGraph')).toBeInTheDocument();
expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();
});
@@ -535,7 +766,7 @@ describe('Trace Viewer', () => {
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 userEvent.click(await recordRow('llm'));
await waitFor(() => expect(dataService.getConversationTraceRecord).toHaveBeenCalledTimes(1));
await userEvent.click(screen.getByRole('button', { name: 'com_ui_trace_refresh' }));
@@ -545,7 +776,7 @@ describe('Trace Viewer', () => {
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/));
+ await userEvent.click(await recordRow('llm'));
const search = screen.getByLabelText('com_ui_trace_search');
await userEvent.type(search, 'no-such-record');
expect(screen.queryByRole('tree')).not.toBeInTheDocument();
@@ -561,7 +792,7 @@ describe('Trace Viewer', () => {
it('closes the inspector on Escape before closing the trace', async () => {
const { onClose } = renderViewer();
- await userEvent.click(await treeItem(/llm/));
+ await userEvent.click(await recordRow('llm'));
await userEvent.keyboard('{Escape}');
expect(screen.queryByTestId('trace-inspector')).not.toBeInTheDocument();
@@ -573,7 +804,7 @@ describe('Trace Viewer', () => {
it('links to Langfuse only for users who manage the connection', async () => {
const first = renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
expect(
screen.queryByRole('link', { name: /com_ui_trace_open_langfuse/ }),
).not.toBeInTheDocument();
@@ -601,7 +832,7 @@ describe('Trace Viewer', () => {
.mockResolvedValue({ records, sourceId: 'central-project' });
renderViewer();
- await treeItem(/AgentGraph/);
+ await recordRow('llm');
await waitFor(() => expect(dataService.getLangfuseSessionLink).toHaveBeenCalled());
expect(
screen.queryByRole('link', { name: /com_ui_trace_open_langfuse/ }),
diff --git a/client/src/components/Chat/Trace/__tests__/model.test.ts b/client/src/components/Chat/Trace/__tests__/model.test.ts
index 6dd2df9315..24d875169d 100644
--- a/client/src/components/Chat/Trace/__tests__/model.test.ts
+++ b/client/src/components/Chat/Trace/__tests__/model.test.ts
@@ -1,12 +1,19 @@
import type { TTraceRecord } from 'librechat-data-provider';
+import type { TraceFilter } from '../model';
import {
+ spanOf,
+ stepKey,
turnKey,
+ boundsOf,
panWindow,
fitWindow,
zoomWindow,
assignLanes,
clampWindow,
flattenRows,
+ minimumSpan,
+ rebaseWindow,
+ sequenceLane,
buildTraceModel,
collapsibleKeys,
} from '../model';
@@ -28,28 +35,101 @@ function record(overrides: Partial<TTraceRecord> & Pick<TTraceRecord, 'id'>): TT
};
}
-const noFilter = { collapsed: new Set<string>(), query: '', window: null };
+const noFilter: TraceFilter = {
+ collapsed: new Set<string>(),
+ query: '',
+ window: null,
+ scale: 'time',
+};
const rowKeys = (rows: ReturnType<typeof flattenRows>) => rows.map((row) => row.key);
+const step = (anchorId: string, messageId = 'response-1') => stepKey(messageId, 'run', anchorId);
+
+/** An agent turn as the SDK exports it: an agent span holding model calls, tools, and chain spans. */
+const agentTurn: TTraceRecord[] = [
+ record({ id: 'root', kind: 'agent', name: 'AgentGraph', startTime: at(0), endTime: at(10_000) }),
+ record({ id: 'chain', parentId: 'root', name: 'chain', startTime: at(0), endTime: at(9000) }),
+ record({
+ id: 'llm-1',
+ parentId: 'chain',
+ kind: 'generation',
+ name: 'llm',
+ model: 'gpt-5',
+ startTime: at(100),
+ endTime: at(2000),
+ }),
+ record({ id: 'dispatch', parentId: 'chain', name: 'tool-dispatch', startTime: at(2100) }),
+ record({
+ id: 'search-1',
+ parentId: 'dispatch',
+ kind: 'tool',
+ name: 'web_search',
+ startTime: at(2200),
+ endTime: at(3000),
+ }),
+ record({
+ id: 'fetch',
+ parentId: 'search-1',
+ name: 'fetch',
+ startTime: at(2300),
+ endTime: at(2900),
+ }),
+ record({
+ id: 'search-2',
+ parentId: 'dispatch',
+ kind: 'tool',
+ name: 'web_search',
+ startTime: at(3100),
+ endTime: at(3500),
+ }),
+ record({ id: 'checkpoint', parentId: 'chain', name: 'checkpoint', startTime: at(3600) }),
+ record({
+ id: 'llm-2',
+ parentId: 'chain',
+ kind: 'generation',
+ name: 'llm',
+ model: 'gpt-5',
+ startTime: at(4000),
+ endTime: at(9000),
+ }),
+ record({
+ id: 'title-llm',
+ traceId: 'trace-title',
+ kind: 'generation',
+ name: 'llm',
+ origin: 'title',
+ startTime: at(9500),
+ endTime: at(10_000),
+ }),
+];
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) }),
- ]);
+ 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) }),
+ ],
+ 'full',
+ );
expect(model.turns.map((turn) => turn.messageId)).toEqual(['response-1', 'response-2']);
expect(model.nodes.get('root')?.childIds).toEqual(['llm', 'tool']);
@@ -65,13 +145,16 @@ describe('buildTraceModel', () => {
});
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 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) }),
+ ],
+ 'full',
+ );
const keys = rowKeys(flattenRows(model, noFilter));
expect(new Set(keys)).toEqual(
@@ -188,33 +271,454 @@ describe('buildTraceModel', () => {
});
});
+describe('simple mode', () => {
+ const model = buildTraceModel(agentTurn);
+
+ it('lists only model calls and tools, each hung from its nearest listed ancestor', () => {
+ const shown = [...model.nodes.values()].filter((node) => node.shown).map((n) => n.record.id);
+ expect(shown.sort()).toEqual(['llm-1', 'llm-2', 'search-1', 'search-2', 'title-llm']);
+ expect(model.nodes.get('search-1')?.viewParentId).toBeNull();
+ expect(model.nodes.get('fetch')?.shown).toBe(false);
+ expect(model.nodes.get('llm-1')?.depth).toBe(0);
+ });
+
+ it('starts a step at each model call and gives it the tools that ran after it', () => {
+ const turn = model.turns[0];
+ expect(turn.steps).toBe(2);
+ expect(turn.stepKeys).toEqual([
+ step('llm-1'),
+ step('llm-2'),
+ stepKey('response-1', 'title', 'title-llm'),
+ ]);
+ expect(model.steps.get(step('llm-1'))).toMatchObject({
+ index: 1,
+ origin: 'run',
+ generationId: 'llm-1',
+ rootIds: ['llm-1', 'search-1', 'search-2'],
+ start: BASE + 100,
+ end: BASE + 3500,
+ recordCount: 3,
+ toolCalls: 2,
+ });
+ expect([...(model.steps.get(step('llm-1'))?.toolNames ?? [])]).toEqual([['web_search', 2]]);
+ expect(model.steps.get(step('llm-2'))).toMatchObject({
+ generationId: 'llm-2',
+ rootIds: ['llm-2'],
+ });
+ expect(model.steps.get(stepKey('response-1', 'title', 'title-llm'))).toMatchObject({
+ origin: 'title',
+ rootIds: ['title-llm'],
+ });
+ });
+
+ it('keeps a failed span visible so an error is never hidden by the roll-up', () => {
+ const failed = buildTraceModel([
+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(3000) }),
+ record({
+ id: 'llm',
+ parentId: 'root',
+ kind: 'generation',
+ startTime: at(0),
+ endTime: at(1000),
+ }),
+ record({
+ id: 'dispatch',
+ parentId: 'root',
+ name: 'tool-dispatch',
+ status: 'error',
+ statusMessage: 'Host tool execution failed',
+ startTime: at(1500),
+ endTime: at(1600),
+ }),
+ ]);
+
+ expect(rowKeys(flattenRows(failed, noFilter))).toEqual([
+ turnKey('response-1'),
+ step('llm'),
+ 'llm',
+ 'dispatch',
+ ]);
+ expect(failed.steps.get(step('llm'))?.errorCount).toBe(1);
+ });
+
+ it('gives tools that ran before any model call their own step, and a turn with no model call one step', () => {
+ const leading = buildTraceModel([
+ record({ id: 'early', kind: 'tool', startTime: at(0), endTime: at(100) }),
+ record({ id: 'llm', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ record({ id: 'late', kind: 'tool', startTime: at(400), endTime: at(500) }),
+ record({ id: 'llm-2', kind: 'generation', startTime: at(600), endTime: at(700) }),
+ ]);
+ const toolsOnly = buildTraceModel([record({ id: 'only', kind: 'tool' })]);
+
+ expect(leading.steps.get(step('early'))?.rootIds).toEqual(['early']);
+ expect(leading.steps.get(step('llm'))?.rootIds).toEqual(['llm', 'late']);
+ expect([...(leading.steps.get(step('llm'))?.toolNames.keys() ?? [])]).toEqual(['late']);
+ expect(leading.steps.get(step('llm-2'))?.rootIds).toEqual(['llm-2']);
+ expect(leading.turns[0].steps).toBe(3);
+ expect(toolsOnly.turns[0].steps).toBe(1);
+ expect(toolsOnly.steps.get(step('only'))).toMatchObject({
+ generationId: null,
+ rootIds: ['only'],
+ });
+ });
+
+ it('keeps a failed wrapper visible without folding the model calls beneath it into one step', () => {
+ const failed = buildTraceModel([
+ record({ id: 'root', kind: 'agent', status: 'error', startTime: at(0), endTime: at(3000) }),
+ record({
+ id: 'llm-1',
+ parentId: 'root',
+ kind: 'generation',
+ startTime: at(100),
+ endTime: at(1000),
+ }),
+ record({
+ id: 'llm-2',
+ parentId: 'root',
+ kind: 'generation',
+ startTime: at(1500),
+ endTime: at(2500),
+ }),
+ ]);
+
+ expect(failed.turns[0].steps).toBe(2);
+ expect(failed.nodes.get('llm-1')?.viewParentId).toBeNull();
+ expect(rowKeys(flattenRows(failed, noFilter))).toEqual([
+ turnKey('response-1'),
+ step('llm-1'),
+ 'root',
+ 'llm-1',
+ step('llm-2'),
+ 'llm-2',
+ ]);
+ });
+
+ it('carries a sequence window across a page that renumbers the records', () => {
+ const previous = buildTraceModel([
+ record({ id: 'a', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({ id: 'b', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ ]);
+ const withOlder = buildTraceModel([
+ record({ id: 'z', kind: 'generation', startTime: at(-500), endTime: at(-400) }),
+ record({ id: 'a', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({ id: 'b', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ ]);
+ const without = buildTraceModel([
+ record({ id: 'b', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ ]);
+
+ expect(rebaseWindow({ start: 0, end: 1 }, previous, withOlder, 'sequence')).toEqual({
+ start: 1,
+ end: 2,
+ });
+ expect(rebaseWindow({ start: 0, end: 1 }, previous, without, 'sequence')).toBeNull();
+ const inTime = { start: BASE, end: BASE + 50 };
+ expect(rebaseWindow(inTime, previous, previous, 'time')).toBe(inTime);
+ });
+
+ it('orders a model call before the tool it asked for when both start in the same millisecond', () => {
+ const tied = buildTraceModel([
+ record({ id: 'a-tool', kind: 'tool', name: 'web_search', startTime: at(0), endTime: at(50) }),
+ record({ id: 'b-llm', kind: 'generation', startTime: at(0), endTime: at(10) }),
+ ]);
+
+ expect(tied.turns[0].steps).toBe(1);
+ expect(tied.steps.get(step('b-llm'))?.rootIds).toEqual(['b-llm', 'a-tool']);
+ expect(tied.nodes.get('b-llm')?.sequence).toBe(0);
+ });
+
+ it('shows a title run recorded as a plain span as its own Title step', () => {
+ const titled = buildTraceModel([
+ record({ id: 'llm', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({
+ id: 'title-chain',
+ traceId: 'trace-title',
+ name: 'chain',
+ origin: 'title',
+ startTime: at(200),
+ endTime: at(300),
+ }),
+ ]);
+
+ expect(titled.nodes.get('title-chain')?.shown).toBe(true);
+ expect(titled.turns[0].steps).toBe(1);
+ expect(rowKeys(flattenRows(titled, noFilter))).toEqual([
+ turnKey('response-1'),
+ step('llm'),
+ 'llm',
+ stepKey('response-1', 'title', 'title-chain'),
+ 'title-chain',
+ ]);
+ });
+
+ it.each(['simple', 'full'] as const)(
+ 'bounds ancestry work for deeply nested failed wrappers in %s mode',
+ (mode) => {
+ const count = 3000;
+ let kindReads = 0;
+ const records = Array.from({ length: count }, (_, index) => {
+ const entry = record({
+ id: `failed-${index}`,
+ parentId: index > 0 ? `failed-${index - 1}` : null,
+ status: 'error',
+ });
+ Object.defineProperty(entry, 'kind', {
+ get: () => {
+ kindReads++;
+ return 'span';
+ },
+ });
+ return entry;
+ }).reverse();
+ const nested = buildTraceModel(records, mode);
+ expect(nested.count).toBe(count);
+ expect(nested.turns[0].steps).toBe(1);
+ expect([...nested.steps.values()][0].recordCount).toBe(count);
+ expect(kindReads).toBeLessThan(count * 60);
+ },
+ );
+
+ it('keeps parallel tools in their own lanes across wrapper pagination', () => {
+ const records = [
+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(10_000) }),
+ record({ id: 'lane-a', parentId: 'root', startTime: at(0), endTime: at(5000) }),
+ record({ id: 'lane-b', parentId: 'root', startTime: at(0), endTime: at(5000) }),
+ record({
+ id: 'llm-a',
+ parentId: 'lane-a',
+ kind: 'generation',
+ startTime: at(100),
+ endTime: at(1000),
+ }),
+ record({
+ id: 'llm-b',
+ parentId: 'lane-b',
+ kind: 'generation',
+ startTime: at(200),
+ endTime: at(1200),
+ }),
+ record({
+ id: 'tool-a',
+ parentId: 'lane-a',
+ kind: 'tool',
+ startTime: at(1100),
+ endTime: at(2000),
+ }),
+ record({
+ id: 'tool-b',
+ parentId: 'lane-b',
+ kind: 'tool',
+ startTime: at(1300),
+ endTime: at(2100),
+ }),
+ ];
+ for (const mode of ['simple', 'full'] as const) {
+ for (const page of [records.slice(3), records.slice(1), records]) {
+ const lanes = buildTraceModel(page, mode);
+ expect(lanes.steps.get(step('llm-a'))?.rootIds).toEqual(['llm-a', 'tool-a']);
+ expect(lanes.steps.get(step('llm-b'))?.rootIds).toEqual(['llm-b', 'tool-b']);
+ }
+ }
+ });
+
+ it('keeps unrelated unloaded parents separate until their connecting wrapper arrives', () => {
+ const partial = [
+ record({ id: 'llm', parentId: 'chain', kind: 'generation', startTime: at(100) }),
+ record({ id: 'tool', parentId: 'dispatch', kind: 'tool', startTime: at(200) }),
+ ];
+ const before = buildTraceModel(partial);
+ expect(before.steps.get(step('llm'))?.rootIds).toEqual(['llm']);
+ expect(before.steps.get(step('tool'))?.rootIds).toEqual(['tool']);
+ const after = buildTraceModel([
+ record({ id: 'root', kind: 'agent' }),
+ record({ id: 'chain', parentId: 'root' }),
+ record({ id: 'dispatch', parentId: 'chain' }),
+ ...partial,
+ ]);
+ expect(after.steps.get(step('llm'))?.rootIds).toEqual(['llm', 'tool']);
+ expect(after.turns[0].steps).toBe(1);
+ });
+
+ it('keeps a tool whose lane has no loaded model call in a step of its own lane', () => {
+ const paged = buildTraceModel([
+ record({ id: 'root', kind: 'agent', startTime: at(0), endTime: at(10_000) }),
+ record({ id: 'lane-a', parentId: 'root', startTime: at(0), endTime: at(5000) }),
+ record({ id: 'lane-b', parentId: 'root', startTime: at(0), endTime: at(5000) }),
+ record({
+ id: 'llm-a',
+ parentId: 'lane-a',
+ kind: 'generation',
+ startTime: at(100),
+ endTime: at(1000),
+ }),
+ record({
+ id: 'tool-b',
+ parentId: 'lane-b',
+ kind: 'tool',
+ startTime: at(1300),
+ endTime: at(2100),
+ }),
+ ]);
+
+ expect(paged.steps.get(step('llm-a'))?.rootIds).toEqual(['llm-a']);
+ expect(paged.steps.get(step('tool-b'))?.rootIds).toEqual(['tool-b']);
+ });
+
+ it('lists the wrappers of a turn that has no model call, tool or failure yet', () => {
+ const starting = buildTraceModel([
+ record({
+ id: 'root',
+ kind: 'agent',
+ status: 'running',
+ startTime: at(0),
+ endTime: undefined,
+ }),
+ record({
+ id: 'chain',
+ parentId: 'root',
+ status: 'running',
+ startTime: at(0),
+ endTime: undefined,
+ }),
+ ]);
+
+ expect(starting.nodes.get('root')?.shown).toBe(true);
+ expect(starting.nodes.get('chain')?.shown).toBe(false);
+ expect(rowKeys(flattenRows(starting, noFilter))).toEqual([
+ turnKey('response-1'),
+ step('root'),
+ 'root',
+ ]);
+ });
+
+ it('keeps a step key stable when an older page adds an earlier model call', () => {
+ const newest = buildTraceModel([
+ record({ id: 'llm-2', kind: 'generation', startTime: at(4000), endTime: at(5000) }),
+ ]);
+ const complete = buildTraceModel([
+ record({ id: 'llm-1', kind: 'generation', startTime: at(0), endTime: at(1000) }),
+ record({ id: 'llm-2', kind: 'generation', startTime: at(4000), endTime: at(5000) }),
+ ]);
+
+ expect(newest.turns[0].stepKeys).toEqual([step('llm-2')]);
+ expect(newest.steps.get(step('llm-2'))?.index).toBe(1);
+ expect(complete.turns[0].stepKeys).toEqual([step('llm-1'), step('llm-2')]);
+ expect(complete.steps.get(step('llm-2'))?.index).toBe(2);
+ });
+
+ it('numbers shown records in ledger order for the sequence scale', () => {
+ const order = ['llm-1', 'search-1', 'search-2', 'llm-2', 'title-llm'];
+ expect(order.map((id) => model.nodes.get(id)?.sequence)).toEqual([0, 1, 2, 3, 4]);
+ expect(model.count).toBe(5);
+ expect(model.steps.get(step('llm-1'))?.sequence).toEqual({ start: 0, end: 3 });
+ expect(model.turns[0].sequence).toEqual({ start: 0, end: 5 });
+ expect(spanOf(model.nodes.get('search-2') as never, 'sequence')).toEqual({ start: 2, end: 3 });
+ expect(boundsOf(model, 'sequence')).toEqual({ start: 0, end: 5 });
+ expect(boundsOf(model, 'time')).toEqual({ start: BASE, end: BASE + 10_000 });
+ });
+
+ it('lays rows out as turn, steps, then records', () => {
+ const rows = flattenRows(model, noFilter);
+ expect(rows.map((row) => [row.key, row.level])).toEqual([
+ [turnKey('response-1'), 1],
+ [step('llm-1'), 2],
+ ['llm-1', 3],
+ ['search-1', 3],
+ ['search-2', 3],
+ [step('llm-2'), 2],
+ ['llm-2', 3],
+ [stepKey('response-1', 'title', 'title-llm'), 2],
+ ['title-llm', 3],
+ ]);
+ expect(rows[1]).toMatchObject({ type: 'step', position: 1, setSize: 3 });
+ expect(rows[2]).toMatchObject({ type: 'record', position: 1, setSize: 3 });
+ });
+
+ it('folds a step and a turn, and offers steps as collapsible keys', () => {
+ expect(
+ rowKeys(flattenRows(model, { ...noFilter, collapsed: new Set([step('llm-1')]) })),
+ ).toEqual([
+ turnKey('response-1'),
+ step('llm-1'),
+ step('llm-2'),
+ 'llm-2',
+ stepKey('response-1', 'title', 'title-llm'),
+ 'title-llm',
+ ]);
+ expect(
+ rowKeys(flattenRows(model, { ...noFilter, collapsed: new Set([turnKey('response-1')]) })),
+ ).toEqual([turnKey('response-1')]);
+ expect(new Set(collapsibleKeys(model))).toEqual(
+ new Set([
+ turnKey('response-1'),
+ step('llm-1'),
+ step('llm-2'),
+ stepKey('response-1', 'title', 'title-llm'),
+ ]),
+ );
+ });
+
+ it('focuses the ledger on a record range on the sequence scale', () => {
+ const rows = flattenRows(model, {
+ ...noFilter,
+ scale: 'sequence',
+ window: { start: 1, end: 3 },
+ });
+
+ expect(rowKeys(rows)).toEqual([turnKey('response-1'), step('llm-1'), 'search-1', 'search-2']);
+ });
+
+ it('shows every span again in full mode', () => {
+ const full = buildTraceModel(agentTurn, 'full');
+ expect(rowKeys(flattenRows(full, noFilter))).toEqual([
+ turnKey('response-1'),
+ 'root',
+ 'chain',
+ 'llm-1',
+ 'dispatch',
+ 'search-1',
+ 'fetch',
+ 'search-2',
+ 'checkpoint',
+ 'llm-2',
+ 'title-llm',
+ ]);
+ expect(full.nodes.get('fetch')?.depth).toBe(4);
+ expect(full.turns[0].steps).toBe(2);
+ expect(full.count).toBe(10);
+ });
+});
+
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),
- }),
- ]);
+ 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),
+ }),
+ ],
+ 'full',
+ );
it('places each row among its visible siblings rather than the whole list', () => {
const placements = flattenRows(model, noFilter).map(({ key, position, setSize }) => [
@@ -249,9 +753,9 @@ describe('flattenRows', () => {
it('keeps search matches and their ancestors, even inside collapsed parents', () => {
const rows = flattenRows(model, {
+ ...noFilter,
collapsed: new Set(['root', 'tool']),
query: 'FETCH',
- window: null,
});
expect(rowKeys(rows)).toEqual([turnKey('response-1'), 'root', 'tool', 'nested']);
@@ -299,7 +803,7 @@ describe('flattenRows', () => {
});
});
-describe('time windows', () => {
+describe('windows', () => {
const bounds = { start: BASE, end: BASE + 10_000 };
it('clamps a window inside the trace and clears it when it covers everything', () => {
@@ -334,16 +838,26 @@ describe('time windows', () => {
end: BASE + 1900,
});
});
+
+ it('never zooms below one record on the sequence scale', () => {
+ const records = { start: 0, end: 8 };
+ expect(minimumSpan(records, 'sequence')).toBe(1);
+ expect(minimumSpan(bounds, 'time')).toBe(10);
+ expect(zoomWindow(records, { start: 3, end: 4 }, 0.5, 3.5, 1)).toEqual({ start: 3, end: 4 });
+ });
});
-describe('assignLanes', () => {
+describe('lanes', () => {
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 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) }),
+ ],
+ 'full',
+ );
const lanes = assignLanes(model, 2);
expect(lanes.get('a')).toBe(0);
@@ -351,4 +865,20 @@ describe('assignLanes', () => {
expect(lanes.get('c')).toBe(0);
expect(lanes.get('d')).toBe(1);
});
+
+ it('packs only the records the mode shows', () => {
+ const model = buildTraceModel([
+ record({ id: 'span', startTime: at(0), endTime: at(1000) }),
+ record({ id: 'llm', kind: 'generation', startTime: at(500), endTime: at(1500) }),
+ ]);
+
+ expect(assignLanes(model, 2).get('llm')).toBe(0);
+ expect(assignLanes(model, 2).has('span')).toBe(false);
+ });
+
+ it('separates kinds on the sequence scale', () => {
+ expect(sequenceLane(record({ id: 'g', kind: 'generation' }))).toBe(0);
+ expect(sequenceLane(record({ id: 't', kind: 'tool' }))).toBe(1);
+ expect(sequenceLane(record({ id: 'e', kind: 'event' }))).toBe(2);
+ });
});
diff --git a/client/src/components/Chat/Trace/__tests__/preview.test.ts b/client/src/components/Chat/Trace/__tests__/preview.test.ts
new file mode 100644
index 0000000000..8888bce163
--- /dev/null
+++ b/client/src/components/Chat/Trace/__tests__/preview.test.ts
@@ -0,0 +1,481 @@
+import { ContentTypes } from 'librechat-data-provider';
+import type { TMessage, TTraceRecord } from 'librechat-data-provider';
+import {
+ buildPreviews,
+ buildStepPreviews,
+ buildPreviewIndex,
+ buildMessagePreview,
+} from '../preview';
+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,
+ };
+}
+
+function message(overrides: Partial<TMessage>): TMessage {
+ return {
+ messageId: 'response-1',
+ conversationId: 'convo-1',
+ parentMessageId: 'user-1',
+ isCreatedByUser: false,
+ text: '',
+ ...overrides,
+ } as TMessage;
+}
+
+const response = message({
+ content: [
+ { type: ContentTypes.THINK, think: 'Need the weather first.' },
+ { type: ContentTypes.TEXT, text: 'Let me check the weather\nfor you.' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'web_search', args: { query: 'weather in Paris', limit: 3 } },
+ },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'web_search', args: '{"query":"weather in Lyon"}' },
+ },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-3',
+ type: 'function',
+ function: { name: 'read_file', arguments: '{"path":"notes.md"}' },
+ },
+ },
+ { type: ContentTypes.TEXT, text: { value: 'Paris is sunny, Lyon is not.' } },
+ ],
+} as Partial<TMessage>);
+
+describe('buildStepPreviews', () => {
+ it('splits a response into what each model call wrote and called', () => {
+ expect(buildStepPreviews(response)).toEqual([
+ {
+ 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' },
+ ],
+ },
+ { text: 'Paris is sunny, Lyon is not.', toolCalls: [] },
+ ]);
+ });
+
+ it('separates consecutive tool-only rounds by run step and keeps parallel calls together', () => {
+ const rounds = message({
+ content: [
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'ls', args: {}, stepId: 'step-a' } },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'cat', args: { path: 'a' }, stepId: 'step-a' },
+ },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { name: 'cat', args: { path: 'b' }, stepId: 'step-b' },
+ },
+ { type: ContentTypes.TEXT, text: 'Both read.' },
+ ],
+ } as Partial<TMessage>);
+
+ expect(buildStepPreviews(rounds)).toEqual([
+ {
+ text: '',
+ toolCalls: [
+ { name: 'ls', args: '' },
+ { name: 'cat', args: 'path: a' },
+ ],
+ },
+ { text: '', toolCalls: [{ name: 'cat', args: 'path: b' }] },
+ { text: 'Both read.', toolCalls: [] },
+ ]);
+ });
+
+ it('starts the next round at reasoning that follows a tool call', () => {
+ const rounds = message({
+ content: [
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'ls', args: {} } },
+ { type: ContentTypes.THINK, think: 'One more file.' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'cat', args: { path: 'a' } } },
+ ],
+ } as Partial<TMessage>);
+
+ expect(buildStepPreviews(rounds)).toEqual([
+ { text: '', toolCalls: [{ name: 'ls', args: '' }] },
+ { text: '', toolCalls: [{ name: 'cat', args: 'path: a' }] },
+ ]);
+ });
+
+ it('reserves a round for a compaction summary, which is a model call of its own', () => {
+ const compacted = message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Before.' },
+ { type: ContentTypes.SUMMARY, content: [{ type: ContentTypes.TEXT, text: 'Summary.' }] },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'ls', args: {} } },
+ { type: ContentTypes.TEXT, text: 'After.' },
+ ],
+ } as Partial<TMessage>);
+
+ expect(buildStepPreviews(compacted)).toEqual([
+ { text: 'Before.', toolCalls: [] },
+ { text: '', toolCalls: [] },
+ { text: '', toolCalls: [{ name: 'ls', args: '' }] },
+ { text: 'After.', toolCalls: [] },
+ ]);
+ });
+
+ it('skips the holes a streaming message leaves in its content', () => {
+ const sparse = new Array<TMessage['content'] extends (infer P)[] | undefined ? P : never>(3);
+ sparse[0] = { type: ContentTypes.TEXT, text: 'Streaming' };
+ sparse[2] = { type: ContentTypes.TEXT, text: 'still.' };
+
+ expect(buildStepPreviews(message({ content: sparse } as Partial<TMessage>))).toEqual([
+ { text: 'Streaming still.', toolCalls: [] },
+ ]);
+ });
+
+ it('falls back to the message text and bounds long previews', () => {
+ const long = 'word '.repeat(100);
+ expect(buildStepPreviews(message({ text: long }))).toEqual([
+ { text: `${long.slice(0, 160).trimEnd()}…`, toolCalls: [] },
+ ]);
+ expect(buildStepPreviews(undefined)).toEqual([]);
+ });
+});
+
+describe('buildPreviewIndex', () => {
+ const model = buildTraceModel([
+ record({ id: 'llm-1', kind: 'generation', name: 'llm', startTime: at(0), endTime: at(1000) }),
+ record({
+ id: 'search-paris',
+ kind: 'tool',
+ name: 'web_search',
+ startTime: at(1100),
+ endTime: at(1500),
+ }),
+ record({
+ id: 'search-lyon',
+ kind: 'tool',
+ name: 'web_search',
+ startTime: at(1600),
+ endTime: at(2000),
+ }),
+ record({ id: 'read', kind: 'tool', name: 'read_file', startTime: at(2100), endTime: at(2200) }),
+ record({
+ id: 'llm-2',
+ kind: 'generation',
+ name: 'llm',
+ startTime: at(3000),
+ endTime: at(4000),
+ }),
+ record({
+ id: 'title',
+ traceId: 'trace-title',
+ kind: 'generation',
+ name: 'llm',
+ origin: 'title',
+ startTime: at(4100),
+ endTime: at(4200),
+ }),
+ ]);
+ const previews = buildPreviews([
+ message({ messageId: 'user-1', isCreatedByUser: true, text: 'Weather?' }),
+ response,
+ ]);
+ const preview = (id: string) => buildPreviewIndex(model, previews).get(id);
+
+ it('pairs each step with the text it wrote and each tool with the arguments it was given', () => {
+ expect(preview('llm-1')).toBe('Let me check the weather for you.');
+ expect(preview('search-paris')).toBe('query: weather in Paris, limit: 3');
+ expect(preview('search-lyon')).toBe('query: weather in Lyon');
+ expect(preview('read')).toBe('path: notes.md');
+ expect(preview('llm-2')).toBe('Paris is sunny, Lyon is not.');
+ });
+
+ it('shows nothing for a title run, a record without a message, or a step the message lacks', () => {
+ expect(preview('title')).toBeUndefined();
+ expect(buildPreviewIndex(model, new Map()).get('llm-1')).toBeUndefined();
+ const extra = buildTraceModel([
+ record({ id: 'a', kind: 'generation', startTime: at(0), endTime: at(1) }),
+ record({ id: 'b', kind: 'generation', startTime: at(2), endTime: at(3) }),
+ record({ id: 'c', kind: 'generation', startTime: at(4), endTime: at(5) }),
+ ]);
+ expect(buildPreviewIndex(extra, previews).get('c')).toBeUndefined();
+ });
+
+ it('leaves what ran inside a tool, such as a subagent model call, without a preview', () => {
+ const nested = buildTraceModel([
+ record({ id: 'llm', kind: 'generation', name: 'llm', startTime: at(0), endTime: at(100) }),
+ record({
+ id: 'agent',
+ kind: 'tool',
+ name: 'run_agent',
+ startTime: at(200),
+ endTime: at(900),
+ }),
+ record({
+ id: 'inner-llm',
+ parentId: 'agent',
+ kind: 'generation',
+ name: 'llm',
+ startTime: at(300),
+ endTime: at(500),
+ }),
+ record({
+ id: 'inner-tool',
+ parentId: 'agent',
+ kind: 'tool',
+ name: 'run_agent',
+ startTime: at(600),
+ endTime: at(800),
+ }),
+ ]);
+ const delegating = buildPreviews([
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Delegating.' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'run_agent', args: { task: 'x' } } },
+ ],
+ } as Partial<TMessage>),
+ ]);
+ const nestedPreview = (id: string) => buildPreviewIndex(nested, delegating).get(id);
+
+ expect(nestedPreview('llm')).toBe('Delegating.');
+ expect(nestedPreview('agent')).toBe('task: x');
+ expect(nestedPreview('inner-llm')).toBeUndefined();
+ expect(nestedPreview('inner-tool')).toBeUndefined();
+ expect(nested.turns[0].steps).toBe(1);
+ });
+
+ it('attaches a message that kept only its final text to the last model call', () => {
+ const two = buildTraceModel([
+ record({ id: 'first', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({ id: 'last', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ ]);
+ const flat = buildPreviews([message({ text: 'The final answer.' })]);
+ const filtered = buildPreviews([
+ message({ content: [{ type: ContentTypes.TEXT, text: 'Only the answer survived.' }] }),
+ ]);
+
+ expect(buildPreviewIndex(two, flat).get('first')).toBeUndefined();
+ expect(buildPreviewIndex(two, flat).get('last')).toBe('The final answer.');
+ expect(buildPreviewIndex(two, filtered).get('first')).toBeUndefined();
+ expect(buildPreviewIndex(two, filtered).get('last')).toBe('Only the answer survived.');
+ });
+
+ it('gives no preview to same-name calls that started in the same millisecond', () => {
+ const twins = buildTraceModel([
+ record({ id: 'llm', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({ id: 'one', kind: 'tool', name: 'web_search', startTime: at(200), endTime: at(300) }),
+ record({ id: 'two', kind: 'tool', name: 'web_search', startTime: at(200), endTime: at(400) }),
+ ]);
+ const parallel = buildPreviews([
+ message({
+ content: [
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'web_search', args: { q: 'a' } } },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'web_search', args: { q: 'b' } } },
+ ],
+ } as Partial<TMessage>),
+ ]);
+
+ expect(buildPreviewIndex(twins, parallel).get('one')).toBeUndefined();
+ expect(buildPreviewIndex(twins, parallel).get('two')).toBeUndefined();
+ });
+
+ it("never treats a failed turn's error text as model output", () => {
+ const one = buildTraceModel([
+ record({ id: 'llm', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ ]);
+ const failed = buildPreviews([message({ text: 'Generation failed', error: true })]);
+
+ expect(buildStepPreviews(message({ text: 'Generation failed', error: true }))).toEqual([]);
+ expect(buildPreviewIndex(one, failed).get('llm')).toBeUndefined();
+ });
+
+ it('splits a handoff to another agent into its own round and withholds parallel lanes', () => {
+ const two = buildTraceModel([
+ record({ id: 'first', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({ id: 'last', kind: 'generation', startTime: at(200), endTime: at(300) }),
+ ]);
+ const handoff = buildPreviews([
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Agent A says.', agentId: 'agent-a' },
+ { type: ContentTypes.TEXT, text: 'Agent B says.', agentId: 'agent-b' },
+ ],
+ } as Partial<TMessage>),
+ ]);
+ const parallel = buildPreviews([
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Lane one.', agentId: 'agent-a', groupId: 1 },
+ { type: ContentTypes.TEXT, text: 'Lane two.', agentId: 'agent-b', groupId: 1 },
+ ],
+ } as Partial<TMessage>),
+ ]);
+
+ expect(buildPreviewIndex(two, handoff).get('first')).toBe('Agent A says.');
+ expect(buildPreviewIndex(two, handoff).get('last')).toBe('Agent B says.');
+ expect(buildPreviewIndex(two, parallel).size).toBe(0);
+ });
+
+ it('never marks the surviving text of a failed or unfinished run as final', () => {
+ const two = buildTraceModel([
+ record({ id: 'first', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ record({
+ id: 'last',
+ kind: 'generation',
+ status: 'error',
+ startTime: at(200),
+ endTime: at(300),
+ }),
+ ]);
+ const failed = buildPreviews([
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Started well.' },
+ { type: ContentTypes.ERROR, text: 'Generation failed' },
+ ],
+ } as Partial<TMessage>),
+ ]);
+ const unfinished = buildPreviews([
+ message({ unfinished: true, content: [{ type: ContentTypes.TEXT, text: 'Started well.' }] }),
+ ]);
+
+ expect(buildPreviewIndex(two, failed).size).toBe(0);
+ expect(failed.get('response-1')?.finalOnly).toBe(false);
+ expect(buildPreviewIndex(two, failed).get('last')).toBeUndefined();
+ expect(buildPreviewIndex(two, unfinished).size).toBe(0);
+ expect(unfinished.get('response-1')?.finalOnly).toBe(false);
+ expect(buildPreviewIndex(two, unfinished).get('last')).toBeUndefined();
+ });
+
+ it('recognizes a handoff whose new agent starts by reasoning', () => {
+ const handoff = buildStepPreviews(
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Agent A.', agentId: 'agent-a' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'ls', args: {} }, agentId: 'agent-a' },
+ { type: ContentTypes.THINK, think: 'Taking over.', agentId: 'agent-b' },
+ { type: ContentTypes.TEXT, text: 'Agent B.', agentId: 'agent-b' },
+ ],
+ } as Partial<TMessage>),
+ );
+
+ expect(handoff).toEqual([
+ { text: 'Agent A.', toolCalls: [{ name: 'ls', args: '' }] },
+ { text: 'Agent B.', toolCalls: [] },
+ ]);
+ });
+
+ it('withholds previews for the turn a page boundary splits', () => {
+ const one = buildTraceModel([
+ record({ id: 'llm', kind: 'generation', startTime: at(0), endTime: at(100) }),
+ ]);
+ const answer = buildPreviews([message({ text: 'Answer.' })]);
+
+ expect(buildPreviewIndex(one, answer).get('llm')).toBe('Answer.');
+ expect(buildPreviewIndex(one, answer, 'response-1').get('llm')).toBeUndefined();
+ });
+
+ it('keeps text and tool previews for a single attributed lane', () => {
+ const single = message({
+ content: response.content?.map((part) => ({ ...part, agentId: 'agent-a', groupId: 1 })),
+ });
+ const index = buildPreviewIndex(model, buildPreviews([single]));
+ expect(index.get('llm-1')).toBe('Let me check the weather for you.');
+ expect(index.get('search-paris')).toBe('query: weather in Paris, limit: 3');
+ expect(index.get('llm-2')).toBe('Paris is sunny, Lyon is not.');
+ });
+
+ it.each([false, true])('aligns output across consecutive steers (reasoning: %s)', (reasoning) => {
+ const steered = message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Before.' },
+ { type: ContentTypes.STEER, steer: 'Change direction.' },
+ { type: ContentTypes.STEER, steer: 'And be brief.' },
+ ...(reasoning ? [{ type: ContentTypes.THINK, think: 'New direction.' }] : []),
+ { type: ContentTypes.TEXT, text: 'After.' },
+ ],
+ } as Partial<TMessage>);
+ const two = buildTraceModel([
+ record({ id: 'first', kind: 'generation', startTime: at(0) }),
+ record({ id: 'last', kind: 'generation', startTime: at(200) }),
+ ]);
+ expect(buildStepPreviews(steered)).toEqual([
+ { text: 'Before.', toolCalls: [] },
+ { text: 'After.', toolCalls: [] },
+ ]);
+ expect([...buildPreviewIndex(two, buildPreviews([steered]))]).toEqual([
+ ['first', 'Before.'],
+ ['last', 'After.'],
+ ]);
+ });
+
+ it('withholds filtered mixed output until every round can be aligned', () => {
+ const records = [
+ record({ id: 'a', kind: 'generation', startTime: at(0) }),
+ record({ id: 'b', kind: 'generation', startTime: at(100) }),
+ record({ id: 'tool-b', kind: 'tool', name: 'search', startTime: at(200) }),
+ record({ id: 'c', kind: 'generation', startTime: at(300) }),
+ ];
+ const filtered = message({
+ content: [
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'search', args: { q: 'B' } } },
+ { type: ContentTypes.TEXT, text: 'Final C.' },
+ ],
+ } as Partial<TMessage>);
+ for (const mode of ['simple', 'full'] as const) {
+ expect(
+ buildPreviewIndex(buildTraceModel(records, mode), buildPreviews([filtered])).size,
+ ).toBe(0);
+ const restored = message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Round A.', agentId: 'agent-a' },
+ { type: ContentTypes.THINK, think: 'Round B.', agentId: 'agent-b' },
+ ...(filtered.content ?? []),
+ ],
+ } as Partial<TMessage>);
+ expect([
+ ...buildPreviewIndex(buildTraceModel(records, mode), buildPreviews([restored])),
+ ]).toEqual([
+ ['a', 'Round A.'],
+ ['tool-b', 'q: B'],
+ ['c', 'Final C.'],
+ ]);
+ }
+ });
+
+ it('does not final-align unfinished flat text or text followed by a steer', () => {
+ expect(
+ buildMessagePreview(message({ text: 'Still working.', unfinished: true })).finalOnly,
+ ).toBe(false);
+ expect(
+ buildMessagePreview(
+ message({
+ content: [
+ { type: ContentTypes.TEXT, text: 'Before.' },
+ { type: ContentTypes.STEER, steer: 'Continue.' },
+ ],
+ } as Partial<TMessage>),
+ ).finalOnly,
+ ).toBe(false);
+ });
+
+ it('does not preview messages the user wrote', () => {
+ expect(previews.has('user-1')).toBe(false);
+ });
+});
diff --git a/client/src/components/Chat/Trace/model.ts b/client/src/components/Chat/Trace/model.ts
index 900684948e..c291567b9f 100644
--- a/client/src/components/Chat/Trace/model.ts
+++ b/client/src/components/Chat/Trace/model.ts
@@ -1,5 +1,15 @@
import type { TTraceRecord } from 'librechat-data-provider';
+/** `simple` lists the model calls and tools grouped into steps; `full` lists every span as recorded. */
+export type TraceMode = 'simple' | 'full';
+
+/** `sequence` gives every record one equal block in ledger order; `time` scales by recorded time. */
+export type TraceScale = 'sequence' | 'time';
+
+export type TraceSpan = { start: number; end: number };
+
+export type TraceWindow = TraceSpan;
+
export type TraceNode = {
record: TTraceRecord;
start: number;
@@ -7,9 +17,36 @@ export type TraceNode = {
end?: number;
/** First streamed token, clamped inside the record's own span. */
firstToken?: number;
+ /** Depth in the ledger tree of the active mode: 0 for a root under its turn or step. */
depth: number;
parentId: string | null;
childIds: string[];
+ /** The parent the active mode shows: the nearest shown ancestor. */
+ viewParentId: string | null;
+ viewChildIds: string[];
+ /** Whether the active mode lists the record. */
+ shown: boolean;
+ stepKey: string | null;
+ /** Order among shown records: the record's position on the sequence scale. */
+ sequence: number;
+};
+
+export type TraceStep = {
+ key: string;
+ messageId: string;
+ /** 1-based among the turn's response-run steps; the title run numbers its own. */
+ index: number;
+ origin: 'run' | 'title';
+ generationId: string | null;
+ rootIds: string[];
+ start: number;
+ end: number;
+ recordCount: number;
+ errorCount: number;
+ toolCalls: number;
+ /** Tool call counts by tool name, in first-call order. */
+ toolNames: Map<string, number>;
+ sequence: TraceSpan;
};
export type TraceTurn = {
@@ -18,8 +55,14 @@ export type TraceTurn = {
start: number;
end: number;
rootIds: string[];
+ stepKeys: string[];
+ /** Response-run steps only; a title run's steps are not counted as work of the response. */
+ steps: number;
recordCount: number;
errorCount: number;
+ generations: number;
+ toolCalls: number;
+ sequence: TraceSpan;
};
export type TraceSummary = {
@@ -36,27 +79,37 @@ export type TraceSummary = {
};
export type TraceModel = {
+ mode: TraceMode;
nodes: Map<string, TraceNode>;
+ steps: Map<string, TraceStep>;
turns: TraceTurn[];
start: number;
end: number;
+ /** Shown records: the extent of the sequence scale. */
+ count: 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 };
+type RowPlacement = {
+ key: string;
+ expanded: boolean;
+ position: number;
+ setSize: number;
+ level: number;
+};
export type TraceRow =
| (RowPlacement & { type: 'turn'; turn: TraceTurn })
+ | (RowPlacement & { type: 'step'; step: TraceStep })
| (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. */
+ scale: TraceScale;
+ /** The labels a row shows for its record (kind, status, preview), which search also matches. */
labelsFor?: (record: TTraceRecord) => readonly string[];
};
@@ -72,14 +125,47 @@ const EMPTY_SUMMARY: TraceSummary = {
totalTokens: 0,
};
+const EMPTY_SPAN: TraceSpan = { start: 0, end: 0 };
+
export const turnKey = (messageId: string): string => `turn:${messageId}`;
+/** Keyed by the step's own record, so a fold survives an older page renumbering the steps. */
+export const stepKey = (messageId: string, origin: TraceStep['origin'], anchorId: string): string =>
+ `step:${messageId}:${origin}:${anchorId}`;
+
+/** Ties at one millisecond are broken causally: the model call that asked comes before the tool that ran. */
+const KIND_ORDER: Record<TTraceRecord['kind'], number> = {
+ agent: 0,
+ span: 0,
+ generation: 1,
+ tool: 2,
+ event: 3,
+};
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);
+ return (
+ (left?.start ?? 0) - (right?.start ?? 0) ||
+ KIND_ORDER[left?.record.kind ?? 'span'] - KIND_ORDER[right?.record.kind ?? 'span'] ||
+ a.localeCompare(b)
+ );
};
+/** 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' ||
+ record.status === 'error' ||
+ record.origin === 'title'
+ );
+}
+
+/** 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';
+}
+
function toNode(record: TTraceRecord): TraceNode | null {
const start = Date.parse(record.startTime);
if (!Number.isFinite(start)) {
@@ -92,7 +178,20 @@ function toNode(record: TTraceRecord): TraceNode | null {
const firstToken = Number.isFinite(parsedToken)
? Math.min(Math.max(parsedToken, start), end ?? parsedToken)
: undefined;
- return { record, start, end, firstToken, depth: 0, parentId: null, childIds: [] };
+ return {
+ record,
+ start,
+ end,
+ firstToken,
+ depth: 0,
+ parentId: null,
+ childIds: [],
+ viewParentId: null,
+ viewChildIds: [],
+ shown: true,
+ stepKey: null,
+ sequence: 0,
+ };
}
/**
@@ -133,9 +232,275 @@ function resolveParents(nodes: Map<string, TraceNode>): void {
}
}
+/** Nearest model/tool ancestor, cached across both projections with iterative path compression. */
+function nearestStepAncestor(
+ nodes: Map<string, TraceNode>,
+ node: TraceNode,
+ ancestors: Map<string, string | null>,
+): string | null {
+ const path: string[] = [];
+ let current = node;
+ let result: string | null;
+ for (;;) {
+ const cached = ancestors.get(current.record.id);
+ if (cached !== undefined) {
+ result = cached;
+ break;
+ }
+ path.push(current.record.id);
+ const parent = current.parentId != null ? nodes.get(current.parentId) : undefined;
+ if (parent == null || isStepAnchor(parent.record)) {
+ result = parent?.record.id ?? null;
+ break;
+ }
+ current = parent;
+ }
+ for (const id of path) {
+ ancestors.set(id, result);
+ }
+ return result;
+}
+
+/**
+ * Whether the simple mode lists a record. A turn that has no model call, tool or
+ * failure yet (a run still starting, or cancelled early) lists its wrappers
+ * instead, so the ledger can show that something is running rather than nothing.
+ */
+function isListed(node: TraceNode, turnsWithWork: ReadonlySet<string>): boolean {
+ return (
+ isSimpleRecord(node.record) ||
+ (node.parentId == null && !turnsWithWork.has(node.record.messageId))
+ );
+}
+
+function turnsWithSimpleRecords(nodes: Map<string, TraceNode>): Set<string> {
+ const turns = new Set<string>();
+ for (const node of nodes.values()) {
+ if (isSimpleRecord(node.record)) {
+ turns.add(node.record.messageId);
+ }
+ }
+ return turns;
+}
+
+/** Hangs every shown record from its nearest shown ancestor; the full mode shows them all. */
+function resolveViewTree(
+ nodes: Map<string, TraceNode>,
+ mode: TraceMode,
+ turnsWithWork: ReadonlySet<string>,
+ ancestors: Map<string, string | null>,
+): void {
+ for (const node of nodes.values()) {
+ node.shown = mode === 'full' || isListed(node, turnsWithWork);
+ }
+ for (const [id, node] of nodes) {
+ if (!node.shown) {
+ continue;
+ }
+ node.viewParentId =
+ mode === 'full' ? node.parentId : nearestStepAncestor(nodes, node, ancestors);
+ if (node.viewParentId != null) {
+ nodes.get(node.viewParentId)?.viewChildIds.push(id);
+ }
+ }
+}
+
+/**
+ * The model calls and tools that hang directly from a turn once every other
+ * span is rolled up, whichever mode is active: steps are defined by these in
+ * both modes, so a turn's step count reads the same however it is listed.
+ */
+function stepRoots(
+ nodes: Map<string, TraceNode>,
+ turnsWithWork: ReadonlySet<string>,
+ ancestors: Map<string, string | null>,
+): Map<string, string[]> {
+ const roots = new Map<string, string[]>();
+ for (const [id, node] of nodes) {
+ if (!isListed(node, turnsWithWork)) {
+ continue;
+ }
+ const ancestor = nearestStepAncestor(nodes, node, ancestors);
+ if (ancestor != null) {
+ continue;
+ }
+ const turnRoots = roots.get(node.record.messageId) ?? [];
+ turnRoots.push(id);
+ roots.set(node.record.messageId, turnRoots);
+ }
+ return roots;
+}
+
+/**
+ * Groups a turn's roots into steps: each model call starts one and the tools
+ * that follow it belong to it, so a step reads as "the model decided, then
+ * these ran". Tools before the first model call (a turn whose earlier records
+ * sit on an unloaded page) form a step of their own, as they do in the chat's
+ * own record of the response. Failed spans before any step join the first one,
+ * and a turn with nothing else is one step. A title run's records form their own.
+ */
+function groupSteps(
+ turn: TraceTurn,
+ nodes: Map<string, TraceNode>,
+ steps: Map<string, TraceStep>,
+ rootIds: readonly string[],
+): void {
+ const compare = byStart(nodes);
+ const rootsByOrigin = new Map<TraceStep['origin'], string[]>();
+ for (const id of rootIds) {
+ const origin = nodes.get(id)?.record.origin ?? 'run';
+ const roots = rootsByOrigin.get(origin) ?? [];
+ roots.push(id);
+ rootsByOrigin.set(origin, roots);
+ }
+
+ /** A wrapper's branch immediately below its structural root, cached for nested failure rows. */
+ const branches = new Map<string, string>();
+ const branchOf = (id: string): string => {
+ const path: string[] = [];
+ let current = id;
+ let branch: string;
+ for (;;) {
+ const cached = branches.get(current);
+ if (cached != null) {
+ branch = cached;
+ break;
+ }
+ path.push(current);
+ const parent = nodes.get(current)?.parentId;
+ if (parent == null || nodes.get(parent)?.parentId == null) {
+ branch = current;
+ break;
+ }
+ current = parent;
+ }
+ for (const entry of path) {
+ branches.set(entry, branch);
+ }
+ return branch;
+ };
+ /** Unloaded parents remain distinct: merging them would guess at absent lane relationships. */
+ const laneOf = (id: string): string => {
+ const node = nodes.get(id);
+ if (node?.parentId != null) {
+ return branchOf(node.parentId);
+ }
+ const unloaded = node?.record.parentId;
+ return unloaded != null && !nodes.has(unloaded) ? unloaded : '';
+ };
+
+ for (const [origin, roots] of rootsByOrigin) {
+ roots.sort(compare);
+ const groups: Array<{ rootIds: string[]; lane: string }> = [];
+ 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 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))) {
+ const group = { rootIds: [...leading, id], lane };
+ groups.push(group);
+ latestByLane.set(lane, group);
+ leading = [];
+ } else if (current == null) {
+ leading.push(id);
+ } else {
+ (latestByLane.get(lane) ?? current).rootIds.push(id);
+ }
+ }
+ if (leading.length > 0) {
+ groups.push({ rootIds: leading, lane: laneOf(leading[0]) });
+ }
+ groups.forEach(({ rootIds }, index) => {
+ const generationId = rootIds.find(isGenerationId(nodes)) ?? null;
+ const key = stepKey(turn.messageId, origin, generationId ?? rootIds[0]);
+ const step: TraceStep = {
+ key,
+ messageId: turn.messageId,
+ index: index + 1,
+ origin,
+ generationId,
+ rootIds,
+ start: Number.POSITIVE_INFINITY,
+ end: Number.NEGATIVE_INFINITY,
+ recordCount: 0,
+ errorCount: 0,
+ toolCalls: 0,
+ toolNames: new Map(),
+ sequence: EMPTY_SPAN,
+ };
+ const stack = [...rootIds].reverse();
+ while (stack.length > 0) {
+ const node = nodes.get(stack.pop() ?? '');
+ if (!node || node.stepKey === key) {
+ continue;
+ }
+ node.stepKey = key;
+ step.recordCount++;
+ step.start = Math.min(step.start, node.start);
+ step.end = Math.max(step.end, node.end ?? node.start);
+ if (node.record.status === 'error') {
+ step.errorCount++;
+ }
+ if (node.record.kind === 'tool') {
+ step.toolCalls++;
+ step.toolNames.set(node.record.name, (step.toolNames.get(node.record.name) ?? 0) + 1);
+ }
+ for (let i = node.viewChildIds.length - 1; i >= 0; i--) {
+ stack.push(node.viewChildIds[i]);
+ }
+ }
+ steps.set(key, step);
+ turn.stepKeys.push(key);
+ });
+ if (origin === 'run') {
+ turn.steps = groups.length;
+ }
+ }
+
+ turn.stepKeys.sort((a, b) => {
+ const left = steps.get(a);
+ const right = steps.get(b);
+ return (
+ (left?.start ?? 0) - (right?.start ?? 0) ||
+ (left?.origin === 'title' ? 1 : 0) - (right?.origin === 'title' ? 1 : 0)
+ );
+ });
+}
+
+const isGenerationId = (nodes: Map<string, TraceNode>) => (id: string) =>
+ nodes.get(id)?.record.kind === 'generation';
+
+/** Walks a shown subtree in ledger order, setting depth and the sequence position. */
+function numberSubtree(nodes: Map<string, TraceNode>, rootIds: string[], next: number): number {
+ const compare = byStart(nodes);
+ let sequence = next;
+ const stack = rootIds.map((id) => ({ id, depth: 0 })).reverse();
+ 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.sequence = sequence++;
+ node.viewChildIds.sort(compare);
+ for (let i = node.viewChildIds.length - 1; i >= 0; i--) {
+ stack.push({ id: node.viewChildIds[i], depth: entry.depth + 1 });
+ }
+ }
+ return sequence;
+}
+
/** Projects a flat, possibly partial record list into turns of record trees. */
-export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
+export function buildTraceModel(
+ records: readonly TTraceRecord[],
+ mode: TraceMode = 'simple',
+): TraceModel {
const nodes = new Map<string, TraceNode>();
+ const steps = new Map<string, TraceStep>();
for (const record of records) {
const node = toNode(record);
if (node) {
@@ -143,10 +508,14 @@ export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
}
}
if (nodes.size === 0) {
- return { nodes, turns: [], start: 0, end: 0, summary: EMPTY_SUMMARY };
+ return { mode, nodes, steps, turns: [], start: 0, end: 0, count: 0, summary: EMPTY_SUMMARY };
}
resolveParents(nodes);
+ const turnsWithWork = turnsWithSimpleRecords(nodes);
+ const ancestors = new Map<string, string | null>();
+ resolveViewTree(nodes, mode, turnsWithWork, ancestors);
+ const rootsByTurn = stepRoots(nodes, turnsWithWork, ancestors);
const turnsByMessage = new Map<string, TraceTurn>();
const summary: TraceSummary = { ...EMPTY_SUMMARY };
@@ -166,17 +535,21 @@ export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
nodes.get(node.parentId)?.childIds.push(id);
}
- const key = turnKey(record.messageId);
let turn = turnsByMessage.get(record.messageId);
if (!turn) {
turn = {
- key,
+ key: turnKey(record.messageId),
messageId: record.messageId,
start: node.start,
end: nodeEnd,
rootIds: [],
+ stepKeys: [],
+ steps: 0,
recordCount: 0,
errorCount: 0,
+ generations: 0,
+ toolCalls: 0,
+ sequence: EMPTY_SPAN,
};
turnsByMessage.set(record.messageId, turn);
}
@@ -194,9 +567,11 @@ export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
summary.running++;
}
if (record.kind === 'tool') {
+ turn.toolCalls++;
summary.toolCalls++;
}
if (record.kind === 'generation') {
+ turn.generations++;
summary.generations++;
const input = record.usage?.input ?? 0;
const output = record.usage?.output ?? 0;
@@ -216,21 +591,37 @@ export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
const compare = byStart(nodes);
const turns = [...turnsByMessage.values()].sort((a, b) => a.start - b.start);
+ let sequence = 0;
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;
+ for (const id of turn.rootIds) {
+ const stack = [{ id, depth: 0 }];
+ while (stack.length > 0) {
+ const entry = stack.pop();
+ const node = entry ? nodes.get(entry.id) : undefined;
+ if (!entry || !node) {
+ continue;
+ }
+ node.childIds.sort(compare);
+ stack.push(...node.childIds.map((childId) => ({ id: childId, depth: entry.depth + 1 })));
}
- node.depth = entry.depth;
- node.childIds.sort(compare);
- for (const childId of node.childIds) {
- stack.push({ id: childId, depth: entry.depth + 1 });
+ }
+ groupSteps(turn, nodes, steps, rootsByTurn.get(turn.messageId) ?? []);
+ const turnSequenceStart = sequence;
+ if (mode === 'simple') {
+ for (const key of turn.stepKeys) {
+ const step = steps.get(key);
+ if (!step) {
+ continue;
+ }
+ const stepSequenceStart = sequence;
+ sequence = numberSubtree(nodes, step.rootIds, sequence);
+ step.sequence = { start: stepSequenceStart, end: sequence };
}
+ } else {
+ sequence = numberSubtree(nodes, turn.rootIds, sequence);
}
+ turn.sequence = { start: turnSequenceStart, end: sequence };
}
summary.turns = turns.length;
@@ -239,7 +630,30 @@ export function buildTraceModel(records: readonly TTraceRecord[]): TraceModel {
if (pricedRecords > 0 && unpricedRecords === 0) {
summary.cost = cost;
}
- return { nodes, turns, start, end, summary };
+ return { mode, nodes, steps, turns, start, end, count: sequence, summary };
+}
+
+/** A record's extent on the active scale; a running record is a start with no width. */
+export function spanOf(node: TraceNode, scale: TraceScale): TraceSpan {
+ if (scale === 'sequence') {
+ return { start: node.sequence, end: node.sequence + 1 };
+ }
+ return { start: node.start, end: node.end ?? node.start };
+}
+
+export function stepSpan(step: TraceStep, scale: TraceScale): TraceSpan {
+ return scale === 'sequence' ? step.sequence : { start: step.start, end: step.end };
+}
+
+export function turnSpan(turn: TraceTurn, scale: TraceScale): TraceSpan {
+ return scale === 'sequence' ? turn.sequence : { start: turn.start, end: turn.end };
+}
+
+/** The whole trace on the active scale: recorded time, or one unit per shown record. */
+export function boundsOf(model: TraceModel, scale: TraceScale): TraceSpan {
+ return scale === 'sequence'
+ ? { start: 0, end: model.count }
+ : { start: model.start, end: model.end };
}
function matchesQuery(
@@ -256,65 +670,78 @@ function matchesQuery(
);
}
-function overlapsWindow(node: TraceNode, window: TraceWindow | null): boolean {
- return window == null || (node.start <= window.end && (node.end ?? node.start) >= window.start);
+function overlapsWindow(node: TraceNode, window: TraceWindow | null, scale: TraceScale): boolean {
+ if (window == null) {
+ return true;
+ }
+ const span = spanOf(node, scale);
+ return scale === 'sequence'
+ ? span.start < window.end && span.end > window.start
+ : span.start <= window.end && span.end >= window.start;
}
-/** Records that match the filter, plus every ancestor so a match keeps its context. */
+/** Shown records that match the filter, plus every shown ancestor so a match keeps its context. */
function visibleIds(
model: TraceModel,
query: string,
window: TraceWindow | null,
+ scale: TraceScale,
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)) {
+ if (
+ !node.shown ||
+ !matchesQuery(node, query, labelsFor) ||
+ !overlapsWindow(node, window, scale)
+ ) {
continue;
}
let current: string | null = id;
while (current != null && !visible.has(current)) {
visible.add(current);
- current = model.nodes.get(current)?.parentId ?? null;
+ current = model.nodes.get(current)?.viewParentId ?? null;
}
}
return visible;
}
+type Group = { key: string; rootIds: string[] };
+
/**
* 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,
+ { collapsed, query, window, scale, labelsFor }: TraceFilter,
): TraceRow[] {
const normalizedQuery = query.trim().toLowerCase();
const filtering = normalizedQuery !== '' || window != null;
- const visible = filtering ? visibleIds(model, normalizedQuery, window, labelsFor) : null;
+ const visible = filtering ? visibleIds(model, normalizedQuery, window, scale, labelsFor) : null;
const rows: TraceRow[] = [];
-
+ const grouped = model.mode === 'simple';
+ const recordLevel = grouped ? 3 : 2;
+
+ const keptRoots = (rootIds: string[]) =>
+ visible ? rootIds.filter((id) => visible.has(id)) : rootIds;
+ const groupsOf = (turn: TraceTurn): Group[] => {
+ const groups = grouped
+ ? turn.stepKeys.map((key) => ({
+ key,
+ rootIds: keptRoots(model.steps.get(key)?.rootIds ?? []),
+ }))
+ : [{ key: turn.key, rootIds: keptRoots(turn.rootIds) }];
+ return visible ? groups.filter((group) => group.rootIds.length > 0) : groups;
+ };
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 }];
+ const groups = groupsOf(turn);
+ return visible && groups.length === 0 ? [] : [{ turn, groups }];
});
- 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 }))
+ const pushRecords = (rootIds: string[]) => {
+ const stack = rootIds
+ .map((id, index) => ({ id, position: index + 1, setSize: rootIds.length }))
.reverse();
while (stack.length > 0) {
const entry = stack.pop();
@@ -323,8 +750,8 @@ export function flattenRows(
continue;
}
const children = visible
- ? node.childIds.filter((childId) => visible.has(childId))
- : node.childIds;
+ ? node.viewChildIds.filter((childId) => visible.has(childId))
+ : node.viewChildIds;
const expanded = filtering || !collapsed.has(entry.id);
rows.push({
type: 'record',
@@ -334,6 +761,7 @@ export function flattenRows(
hasChildren: children.length > 0,
position: entry.position,
setSize: entry.setSize,
+ level: node.depth + recordLevel,
});
if (!expanded) {
continue;
@@ -342,15 +770,57 @@ export function flattenRows(
stack.push({ id: children[i], position: i + 1, setSize: children.length });
}
}
+ };
+
+ turns.forEach(({ turn, groups }, turnIndex) => {
+ const turnExpanded = filtering || !collapsed.has(turn.key);
+ rows.push({
+ type: 'turn',
+ key: turn.key,
+ turn,
+ expanded: turnExpanded,
+ position: turnIndex + 1,
+ setSize: turns.length,
+ level: 1,
+ });
+ if (!turnExpanded) {
+ return;
+ }
+ if (!grouped) {
+ pushRecords(groups[0]?.rootIds ?? []);
+ return;
+ }
+ groups.forEach((group, groupIndex) => {
+ const step = model.steps.get(group.key);
+ if (!step) {
+ return;
+ }
+ const expanded = filtering || !collapsed.has(step.key);
+ rows.push({
+ type: 'step',
+ key: step.key,
+ step,
+ expanded,
+ position: groupIndex + 1,
+ setSize: groups.length,
+ level: 2,
+ });
+ if (expanded) {
+ pushRecords(group.rootIds);
+ }
+ });
});
return rows;
}
-/** Ids a user can fold: every turn and every record with children. */
+/** Ids a user can fold: every turn, every step, and every shown record with shown children. */
export function collapsibleKeys(model: TraceModel): string[] {
const keys = model.turns.map((turn) => turn.key);
+ if (model.mode === 'simple') {
+ keys.push(...model.steps.keys());
+ }
for (const [id, node] of model.nodes) {
- if (node.childIds.length > 0) {
+ if (node.shown && node.viewChildIds.length > 0) {
keys.push(id);
}
}
@@ -358,13 +828,15 @@ export function collapsibleKeys(model: TraceModel): string[] {
}
/**
- * Packs records into a fixed number of overview lanes the way a network
+ * Packs shown 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);
+ const ordered = [...model.nodes.values()]
+ .filter((node) => node.shown)
+ .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) {
@@ -376,21 +848,32 @@ export function assignLanes(model: TraceModel, laneCount: number): Map<string, n
return lanes;
}
+/** 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') {
+ return 0;
+ }
+ return record.kind === 'tool' ? 1 : 2;
+}
+
/** Clamps a zoom window inside the trace and keeps it at least `minSpan` wide. */
export function clampWindow(
window: TraceWindow,
- bounds: TraceWindow,
+ bounds: TraceSpan,
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);
+ const requested = window.end - window.start;
+ const span = Math.min(Math.max(requested, minSpan), total);
if (span >= total) {
return null;
}
- const start = Math.min(Math.max(window.start, bounds.start), bounds.end - span);
+ /** A window narrower than allowed widens around its own centre rather than drifting right. */
+ const from = span > requested ? (window.start + window.end - span) / 2 : window.start;
+ const start = Math.min(Math.max(from, bounds.start), bounds.end - span);
return { start, end: start + span };
}
@@ -401,53 +884,97 @@ export function clampWindow(
*/
export function fitWindow(
window: TraceWindow,
- model: Pick<TraceModel, 'start' | 'end'>,
+ bounds: TraceSpan,
+ minSpan = minimumSpan(bounds),
): TraceWindow | null {
- const start = Math.max(window.start, model.start);
- const end = Math.min(window.end, model.end);
+ const start = Math.max(window.start, bounds.start);
+ const end = Math.min(window.end, bounds.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));
+ return clampWindow({ start, end }, bounds, minSpan);
}
export const ZOOM_STEP = 0.5;
const PAN_STEP = 0.1;
-/** Rescales `view` by `factor` around `anchor`, an absolute timestamp. */
+/** Rescales `view` by `factor` around `anchor`, a position on the active scale. */
export function zoomWindow(
- model: Pick<TraceModel, 'start' | 'end'>,
+ bounds: TraceSpan,
view: TraceWindow | null,
factor: number,
anchor?: number,
+ minSpan = minimumSpan(bounds),
): 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));
+ return clampWindow({ start, end }, bounds, minSpan);
}
export function panWindow(
- model: Pick<TraceModel, 'start' | 'end'>,
+ bounds: TraceSpan,
view: TraceWindow | null,
direction: -1 | 1,
+ minSpan = minimumSpan(bounds),
): 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 }, bounds, minSpan);
+}
+
+/**
+ * Carries a window across a model change. On the time scale it is fitted to the
+ * records still loaded. On the sequence scale positions renumber when records
+ * arrive or leave, so the window follows the records it covered and clears when
+ * either edge is gone.
+ */
+export function rebaseWindow(
+ view: TraceWindow,
+ previous: TraceModel,
+ next: TraceModel,
+ scale: TraceScale,
+): TraceWindow | null {
+ const bounds = boundsOf(next, scale);
+ const minSpan = minimumSpan(bounds, scale);
+ if (scale === 'time') {
+ return fitWindow(view, bounds, minSpan);
+ }
+ const firstIndex = Math.floor(view.start);
+ const lastIndex = Math.ceil(view.end) - 1;
+ const first = recordAt(previous, firstIndex);
+ const last = recordAt(previous, lastIndex);
+ const nextFirst = first != null ? next.nodes.get(first.record.id) : undefined;
+ const nextLast = last != null ? next.nodes.get(last.record.id) : undefined;
+ if (nextFirst?.shown !== true || nextLast?.shown !== true) {
+ return null;
+ }
return clampWindow(
- { start: view.start + shift, end: view.end + shift },
- { start: model.start, end: model.end },
- minimumSpan(model),
+ {
+ start: nextFirst.sequence + (view.start - firstIndex),
+ end: nextLast.sequence + (view.end - lastIndex),
+ },
+ bounds,
+ minSpan,
);
}
-export function minimumSpan(model: Pick<TraceModel, 'start' | 'end'>): number {
- return Math.max((model.end - model.start) / 1000, 1);
+function recordAt(model: TraceModel, sequence: number): TraceNode | undefined {
+ for (const node of model.nodes.values()) {
+ if (node.shown && node.sequence === sequence) {
+ return node;
+ }
+ }
+ return undefined;
+}
+
+/** The narrowest zoom: one record on the sequence scale, a thousandth of the trace on time. */
+export function minimumSpan(bounds: TraceSpan, scale: TraceScale = 'time'): number {
+ return scale === 'sequence' ? 1 : Math.max((bounds.end - bounds.start) / 1000, 1);
}
diff --git a/client/src/components/Chat/Trace/preview.ts b/client/src/components/Chat/Trace/preview.ts
new file mode 100644
index 0000000000..85a2dc82bb
--- /dev/null
+++ b/client/src/components/Chat/Trace/preview.ts
@@ -0,0 +1,282 @@
+import { ContentTypes } from 'librechat-data-provider';
+import type { TMessage, TMessageContentParts } from 'librechat-data-provider';
+import type { TraceModel } from './model';
+import { hasParallelLanes } from '~/utils/lanes';
+
+const PREVIEW_LENGTH = 160;
+const ELLIPSIS = '…';
+
+type ToolCallPreview = { name: string; args: 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[] };
+
+/**
+ * A response's previews by model call. `finalOnly` marks a message that kept
+ * only its final text (stored as flat text, or with intermediate output
+ * filtered out), which belongs to the last model call, not the first.
+ */
+export type MessagePreview = {
+ steps: StepPreview[];
+ finalOnly: boolean;
+ /** Agents ran in parallel lanes, whose output cannot be told apart by order. */
+ parallel: boolean;
+};
+
+function compact(text: string): string {
+ const collapsed = text.replace(/\s+/g, ' ').trim();
+ return collapsed.length > PREVIEW_LENGTH
+ ? `${collapsed.slice(0, PREVIEW_LENGTH).trimEnd()}${ELLIPSIS}`
+ : collapsed;
+}
+
+function textOf(value: string | { value?: string } | undefined): string {
+ if (typeof value === 'string') {
+ return value;
+ }
+ return value?.value ?? '';
+}
+
+function argsPreview(args: string | object | undefined): string {
+ if (args == null) {
+ return '';
+ }
+ let parsed: unknown = args;
+ if (typeof args === 'string') {
+ try {
+ parsed = JSON.parse(args);
+ } catch {
+ return compact(args);
+ }
+ }
+ if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+ return compact(typeof parsed === 'string' ? parsed : JSON.stringify(parsed));
+ }
+ const pairs = Object.entries(parsed).map(
+ ([key, value]) => `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`,
+ );
+ return compact(pairs.join(', '));
+}
+
+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. */
+function callOf(call: ToolCallPart | undefined): ToolCallPreview | null {
+ if (call == null) {
+ return null;
+ }
+ if ('function' in call && call.function != null) {
+ return { name: call.function.name, args: argsPreview(call.function.arguments) };
+ }
+ if ('name' in call && typeof call.name === 'string') {
+ return { name: call.name, args: argsPreview(call.args) };
+ }
+ return null;
+}
+
+/** The run step a persisted tool call belongs to; parallel calls of one round share it. */
+function runStepOf(call: ToolCallPart | undefined): string | undefined {
+ return call != null && 'stepId' in call && typeof call.stepId === 'string'
+ ? call.stepId
+ : undefined;
+}
+
+/**
+ * Splits a response's content into what each model call produced. A model call
+ * may reason, write text and request tools, in that order, so a new call begins
+ * where a tool call is followed by reasoning or text, or by a tool call from
+ * another run step (consecutive tool-only calls). Parallel calls share a step.
+ */
+export function buildMessagePreview(message: TMessage | undefined): MessagePreview {
+ const parts: TMessageContentParts[] = message?.content ?? [];
+ const steps: StepPreview[] = [];
+ let current: StepPreview | null = null;
+ let afterToolCall = false;
+ let lastRunStep: string | undefined;
+ let roundAgent: string | undefined;
+ const parallel = hasParallelLanes(parts);
+ let sealed = false;
+ const begin = () => {
+ current = { text: '', toolCalls: [] };
+ steps.push(current);
+ afterToolCall = false;
+ sealed = false;
+ return current;
+ };
+ /** A handoff: output from another agent is that agent's own model call. */
+ const handoff = (part: TMessageContentParts): boolean => {
+ const agentId = part.agentId;
+ const changed = agentId != null && roundAgent != null && agentId !== roundAgent;
+ roundAgent = agentId ?? roundAgent;
+ return changed && current != null;
+ };
+ for (const part of parts) {
+ /** A streaming message writes parts at provider indexes, so the array can hold holes. */
+ if (part == null) {
+ continue;
+ }
+ if (part.type === ContentTypes.TOOL_CALL) {
+ const runStep = runStepOf(part.tool_call);
+ const handedOff = handoff(part);
+ const nextRound =
+ handedOff ||
+ (afterToolCall && runStep != null && lastRunStep != null && runStep !== lastRunStep);
+ const step = current == null || sealed || nextRound ? begin() : current;
+ const call = callOf(part.tool_call);
+ if (call != null) {
+ step.toolCalls.push(call);
+ }
+ afterToolCall = true;
+ lastRunStep = runStep ?? lastRunStep;
+ continue;
+ }
+ if (part.type === ContentTypes.THINK) {
+ const handedOff = handoff(part);
+ if (current == null || sealed || afterToolCall || handedOff) {
+ begin();
+ }
+ continue;
+ }
+ /** Compaction is a model call of its own; its round previews nothing, but it holds its place. */
+ if (part.type === ContentTypes.SUMMARY) {
+ begin();
+ sealed = true;
+ continue;
+ }
+ if (part.type === ContentTypes.STEER) {
+ sealed = true;
+ continue;
+ }
+ if (part.type !== ContentTypes.TEXT) {
+ continue;
+ }
+ const handedOff = handoff(part);
+ const step = current == null || sealed || afterToolCall || handedOff ? begin() : current;
+ step.text = compact(`${step.text} ${textOf(part.text)}`);
+ }
+ /** A run that failed or never finished kept its early text, not a final answer. */
+ const endedEarly =
+ message?.error === true ||
+ message?.unfinished === true ||
+ 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 };
+ }
+ const finalOnly =
+ !endedEarly &&
+ !sealed &&
+ steps.length === 1 &&
+ steps[0].toolCalls.length === 0 &&
+ steps[0].text !== '';
+ return { steps, finalOnly, parallel };
+}
+
+export function buildStepPreviews(message: TMessage | undefined): StepPreview[] {
+ return buildMessagePreview(message).steps;
+}
+
+/**
+ * The one-line preview each ledger row shows beside its record's name, taken
+ * from the chat's own message rather than from the tracing backend: the text a
+ * model call wrote, or the arguments a tool was called with. Built once per
+ * model in one pass over every step, so search and rendering never rescan a
+ * step per row. Only a step's own roots have a preview: the message describes
+ * the response's calls, not what ran inside a tool (a subagent's model calls, a
+ * tool's nested calls). Tool records are matched to the message's tool calls by
+ * name, in the order they ran within their step; same-name calls that started in
+ * the same millisecond have no reliable order and get none. The turn a page
+ * boundary splits (`partialMessageId`) gets none until its earlier steps load.
+ */
+export function buildPreviewIndex(
+ model: TraceModel,
+ previewsByMessage: ReadonlyMap<string, MessagePreview>,
+ partialMessageId?: string,
+): Map<string, string> {
+ const index = new Map<string, string>();
+ const stepsByTurn = new Map(model.turns.map((turn) => [turn.messageId, turn.steps]));
+ for (const step of model.steps.values()) {
+ const message = previewsByMessage.get(step.messageId);
+ if (
+ message == null ||
+ message.parallel ||
+ step.origin === 'title' ||
+ step.messageId === partialMessageId
+ ) {
+ continue;
+ }
+ if (message.finalOnly) {
+ const text = message.steps[0]?.text;
+ if (step.index === stepsByTurn.get(step.messageId) && step.generationId != null && text) {
+ index.set(step.generationId, text);
+ }
+ continue;
+ }
+ /** Filtering, incomplete traces and silent calls can remove rounds on either side.
+ * Without a shared call id, an unequal count cannot be aligned by ordinal. */
+ if (message.steps.length !== stepsByTurn.get(step.messageId)) {
+ continue;
+ }
+ const round = message.steps[step.index - 1];
+ if (!round) {
+ continue;
+ }
+ const callsByName = new Map<string, string[]>();
+ for (const call of round.toolCalls) {
+ const bucket = callsByName.get(call.name);
+ if (bucket == null) {
+ callsByName.set(call.name, [call.args]);
+ } else {
+ bucket.push(call.args);
+ }
+ }
+ const startsByName = new Map<string, Map<number, number>>();
+ const roots = step.rootIds.flatMap((id) => {
+ const node = model.nodes.get(id);
+ return node != null ? [node] : [];
+ });
+ for (const node of roots) {
+ if (node.record.kind !== 'tool') {
+ continue;
+ }
+ const starts = startsByName.get(node.record.name) ?? new Map<number, number>();
+ starts.set(node.start, (starts.get(node.start) ?? 0) + 1);
+ startsByName.set(node.record.name, starts);
+ }
+ const ordinals = new Map<string, number>();
+ for (const node of roots) {
+ const { record } = node;
+ if (record.kind === 'generation') {
+ if (round.text) {
+ index.set(record.id, round.text);
+ }
+ continue;
+ }
+ if (record.kind !== 'tool') {
+ continue;
+ }
+ const ordinal = ordinals.get(record.name) ?? 0;
+ ordinals.set(record.name, ordinal + 1);
+ const ambiguous = (startsByName.get(record.name)?.get(node.start) ?? 0) > 1;
+ const args = callsByName.get(record.name)?.[ordinal];
+ if (!ambiguous && args) {
+ index.set(record.id, args);
+ }
+ }
+ }
+ return index;
+}
+
+/** Previews for every response in a conversation, keyed by its message id. */
+export function buildPreviews(
+ messages: readonly TMessage[] | undefined,
+): Map<string, MessagePreview> {
+ const previews = new Map<string, MessagePreview>();
+ for (const message of messages ?? []) {
+ if (message.isCreatedByUser) {
+ continue;
+ }
+ previews.set(message.messageId, buildMessagePreview(message));
+ }
+ return previews;
+}
diff --git a/client/src/components/Chat/Trace/store.ts b/client/src/components/Chat/Trace/store.ts
index b0318acfd2..b73bc158b8 100644
--- a/client/src/components/Chat/Trace/store.ts
+++ b/client/src/components/Chat/Trace/store.ts
@@ -1,4 +1,6 @@
import { atom } from 'jotai';
+import type { TraceMode, TraceScale } from './model';
+import { createStorageAtom } from '~/store/jotai-utils';
/**
* The conversation whose trace covers the chat surface, or `null` when the chat
@@ -6,3 +8,9 @@ import { atom } from 'jotai';
* Memory-only: a reload returns to the conversation.
*/
export const traceViewerConversationAtom = atom<string | null>(null);
+
+/** Which records the ledger shows: the model calls and tools, or every span. */
+export const traceModeAtom = createStorageAtom<TraceMode>('traceViewerMode', 'simple');
+
+/** How the overview and bars are scaled: one block per record, or recorded time. */
+export const traceScaleAtom = createStorageAtom<TraceScale>('traceViewerScale', 'sequence');
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index b3b9abb806..6d8a6fe8d2 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -2653,6 +2653,8 @@
"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_all_spans": "All spans",
+ "com_ui_trace_all_spans_description": "Show every recorded span, not only model calls and tools",
"com_ui_trace_bar_description": "{{0}}, starts {{1}} in, {{2}}",
"com_ui_trace_clear_selection": "Clear selection",
"com_ui_trace_close": "Close trace",
@@ -2699,13 +2701,19 @@
"com_ui_trace_record_id": "Record ID",
"com_ui_trace_records": "Trace records",
"com_ui_trace_refresh": "Refresh trace",
+ "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",
"com_ui_trace_selection": "Showing {{0}} to {{1}}",
+ "com_ui_trace_selection_records": "Showing records {{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_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",
@@ -2716,6 +2724,11 @@
"com_ui_trace_summary_turns": "Responses",
"com_ui_trace_timing": "Timing",
"com_ui_trace_title": "Trace",
+ "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_times": "{{0}}×{{1}}",
+ "com_ui_trace_tools_more": "+{{0}} more",
"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",
diff --git a/packages/api/src/langfuse/reader.spec.ts b/packages/api/src/langfuse/reader.spec.ts
index 20cba287bd..18006fc054 100644
--- a/packages/api/src/langfuse/reader.spec.ts
+++ b/packages/api/src/langfuse/reader.spec.ts
@@ -1081,6 +1081,7 @@ describe('createLangfuseTraceReader', () => {
startTime: '2026-09-12T11:30:00.000Z',
endTime: '2026-09-12T11:30:05.000Z',
status: 'ok',
+ origin: 'title',
},
]);
});
diff --git a/packages/api/src/langfuse/reader.ts b/packages/api/src/langfuse/reader.ts
index 2b4d45de6d..422781d8fe 100644
--- a/packages/api/src/langfuse/reader.ts
+++ b/packages/api/src/langfuse/reader.ts
@@ -67,7 +67,9 @@ const pageSchema = z.object({
});
type LangfuseObservation = z.infer<typeof observationSchema>;
-type OwnedObservation = { observation: LangfuseObservation; messageId: string };
+/** The response that owns a trace, and whether the trace is its title run rather than the run itself. */
+type TraceOwner = { messageId: string; origin?: 'title' };
+type OwnedObservation = { observation: LangfuseObservation } & TraceOwner;
export interface LangfuseTraceReaderDeps {
getConversationTraceRefs: (input: {
@@ -168,7 +170,11 @@ function toCost(observation: LangfuseObservation): number | undefined {
return cost != null && Number.isFinite(cost) && cost >= 0 ? cost : undefined;
}
-function toRecord(observation: LangfuseObservation, messageId: string): TTraceRecord {
+function toRecord(
+ observation: LangfuseObservation,
+ messageId: string,
+ origin?: 'title',
+): 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);
@@ -197,6 +203,7 @@ function toRecord(observation: LangfuseObservation, messageId: string): TTraceRe
: {}),
...(usage ? { usage } : {}),
...(cost != null ? { cost } : {}),
+ ...(origin ? { origin } : {}),
};
}
@@ -235,12 +242,12 @@ function traceIdsOf(message: SampledTraceMessage): string[] {
* 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>();
+function buildTraceOwners(messages: SampledTraceMessage[]): Map<string, TraceOwner> {
+ const owners = new Map<string, TraceOwner>();
for (const message of messages) {
- for (const traceId of traceIdsOf(message)) {
- owners.set(traceId, message.messageId);
- }
+ const [run, title] = traceIdsOf(message);
+ owners.set(run, { messageId: message.messageId });
+ owners.set(title, { messageId: message.messageId, origin: 'title' });
}
return owners;
}
@@ -527,7 +534,7 @@ export function createLangfuseTraceReader({
return parsed.data;
}
- function parseRows(rows: unknown[], owners: Map<string, string>): OwnedObservation[] {
+ function parseRows(rows: unknown[], owners: Map<string, TraceOwner>): OwnedObservation[] {
const observations: OwnedObservation[] = [];
let malformed = 0;
for (const row of rows) {
@@ -536,9 +543,9 @@ export function createLangfuseTraceReader({
malformed++;
continue;
}
- const messageId = owners.get(parsed.data.traceId);
- if (messageId != null) {
- observations.push({ observation: parsed.data, messageId });
+ const owner = owners.get(parsed.data.traceId);
+ if (owner != null) {
+ observations.push({ observation: parsed.data, ...owner });
}
}
if (malformed > 0) {
@@ -890,8 +897,8 @@ export function createLangfuseTraceReader({
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));
+ for (const { observation, messageId, origin } of parseRows(page.data, owners)) {
+ records.push(toRecord(observation, messageId, origin));
}
remaining -= page.data.length;
const next = page.meta?.cursor || undefined;
@@ -1072,8 +1079,8 @@ export function createLangfuseTraceReader({
}
return null;
}
- const { observation, messageId } = match;
- const record = toRecord(observation, messageId);
+ const { observation, messageId, origin } = match;
+ const record = toRecord(observation, messageId, origin);
if (!includeContent) {
return { record, contentAvailable: false };
}
diff --git a/packages/data-provider/src/types/traces.ts b/packages/data-provider/src/types/traces.ts
index f1f4a3e5b3..8210e69b37 100644
--- a/packages/data-provider/src/types/traces.ts
+++ b/packages/data-provider/src/types/traces.ts
@@ -38,6 +38,8 @@ export type TTraceRecord = {
usage?: TTraceUsage;
/** Total cost in USD, when the backend priced the record. */
cost?: number;
+ /** Set on records of the turn's title generation; absent on the response run itself. */
+ origin?: 'title';
};
export type TTraceErrorCode =