/** * TraceViewer.jsx * Owns: rendering hierarchical agent execution traces (LLM calls, tool calls, state * transitions, errors, retries) in tree and waterfall modes. AG-UI wiring via * TraceViewerContainer. * Does NOT own: routing, session management, or trace storage. * * AG-UI events consumed (via TraceViewerContainer): * RUN_STARTED { detail: { traceId } } * RUN_FINISHED { detail: { traceId, outcome } } * SPAN_STARTED { detail: { spanId, parentSpanId?, name, type, startTime } } * SPAN_ENDED { detail: { spanId, status, endTime, duration, error? } } * TOOL_CALL_START { detail: { spanId, parentSpanId?, tool, args, startTime } } * TOOL_CALL_END { detail: { spanId, result, duration, error? } } * ERROR { detail: { traceId, message, stack?, timestamp } } * TRACE_PAYLOAD { detail: { spanId, payload (raw object) } } * * Span shape: * { id, parentId?, name, type: 'llm'|'tool'|'state'|'error', * status: 'running'|'done'|'error', * startTime (ms), endTime (ms), duration (ms)?, * depth, children?, payload?, error?, agentState? } * * Props (TraceViewer — controlled): * spans: Span[] * mode: 'tree'|'waterfall' * theme: 'light'|'dark'|'auto' * filterType: 'all'|'llm'|'tool'|'state'|'error' * filterStatus: 'all'|'done'|'error'|'running' * search: string * startTime: number — ms epoch, used to compute waterfall offsets * * Zero dependencies beyond React. */ // ─── React hooks (injected externally for zero-build) ───────────────────── const { useState, useEffect, useRef, useMemo, useCallback, useReducer } = React; // ─── Design tokens ───────────────────────────────────────────────────────── const TOKENS = { light: { bg: '#FAFAF8', card: '#FFFFFF', border: '#E8E6E0', fg: '#1a1a1a', fgMuted: '#888', accent: '#F5A623', llm: '#8b5cf6', llmBg: 'rgba(139,92,246,0.1)', tool: '#3b82f6', toolBg: 'rgba(59,130,246,0.1)', state: '#6b7280', stateBg: 'rgba(107,114,128,0.08)', error: '#ef4444', errorBg: 'rgba(239,68,68,0.08)', running: '#3b82f6', runningBg: 'rgba(59,130,246,0.1)', success: '#22c55e', connector: '#E8E6E0', guide: '#E0DDD6', shadow: '0 2px 14px rgba(0,0,0,0.07)', codeBg: '#1C1C1A', codeFg: '#E8E6E0', codeKeyword: '#F5A623', codeString: '#4ade80', codeNumber: '#60a5fa', codeComment: '#555', codeKey: '#e2b97e', codeNull: '#94a3b8', searchBg: 'rgba(0,0,0,0.04)', chipActive: '#F5A623', chipActiveFg: '#fff', }, dark: { bg: '#111110', card: '#1C1C1A', border: '#2E2E2C', fg: '#F0EEE8', fgMuted: '#666', accent: '#F5A623', llm: '#a78bfa', llmBg: 'rgba(167,139,250,0.12)', tool: '#60a5fa', toolBg: 'rgba(96,165,250,0.12)', state: '#94a3b8', stateBg: 'rgba(148,163,184,0.1)', error: '#f87171', errorBg: 'rgba(248,113,113,0.1)', running: '#60a5fa', runningBg: 'rgba(96,165,250,0.12)', success: '#4ade80', connector: '#2E2E2C', guide: '#2E2E2C', shadow: '0 2px 14px rgba(0,0,0,0.5)', codeBg: '#0d0d0b', codeFg: '#E8E6E0', codeKeyword: '#F5A623', codeString: '#4ade80', codeNumber: '#60a5fa', codeComment: '#555', codeKey: '#e2b97e', codeNull: '#94a3b8', searchBg: 'rgba(255,255,255,0.05)', chipActive: '#F5A623', chipActiveFg: '#1a1a1a', }, }; function resolveTheme(theme) { if (theme !== 'auto') return theme || 'light'; if (typeof window === 'undefined') return 'light'; return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; } // ─── CSS keyframes / styles (injected once) ───────────────────────────────── const TV_STYLES = ` @keyframes tv-fade-in { from{opacity:0;transform:translateY(2px)} to{opacity:1;transform:translateY(0)} } @keyframes tv-spin { to{transform:rotate(360deg)} } @keyframes tv-slide-down { from{max-height:0;opacity:0} to{max-height:800px;opacity:1} } @keyframes tv-pulse { 0%,100%{opacity:1} 50%{opacity:0.4} } @keyframes tv-bar-in { from{width:0;opacity:0} to{opacity:1} } `; let _tvStylesInjected = false; function injectTVStyles() { if (_tvStylesInjected || typeof document === 'undefined') return; const el = document.createElement('style'); el.textContent = TV_STYLES; document.head.appendChild(el); _tvStylesInjected = true; } // ─── Helpers ─────────────────────────────────────────────────────────────── function formatTime(ms) { if (ms == null) return ''; const d = new Date(ms); const hh = String(d.getHours()).padStart(2, '0'); const mm = String(d.getMinutes()).padStart(2, '0'); const ss = String(d.getSeconds()).padStart(2, '0'); const ms3 = String(d.getMilliseconds()).padStart(3, '0'); return `${hh}:${mm}:${ss}.${ms3}`; } function formatDuration(ms) { if (ms == null || ms < 0) return ''; if (ms < 1000) return `${Math.round(ms)}ms`; if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`; const m = Math.floor(ms / 60000); const s = Math.round((ms % 60000) / 1000); return `${m}m ${s}s`; } function buildTree(spans) { if (!spans || !spans.length) return []; const map = {}; const roots = []; spans.forEach(s => { map[s.id] = { ...s, children: [] }; }); spans.forEach(s => { if (s.parentId && map[s.parentId]) { map[s.parentId].children.push(map[s.id]); } else { roots.push(map[s.id]); } }); // Sort children by startTime function sortChildren(node) { node.children.sort((a, b) => a.startTime - b.startTime); node.children.forEach(sortChildren); return node; } return roots.map(sortChildren); } // Flatten tree to array with depth annotation function flattenTree(nodes, depth = 0) { const result = []; nodes.forEach(n => { result.push({ ...n, depth }); if (n.children && n.children.length) { result.push(...flattenTree(n.children, depth + 1)); } }); return result; } // ─── Syntax colorizer ─────────────────────────────────────────────────────── function syntaxColorize(obj, tok) { if (obj == null) return `null`; if (typeof obj === 'boolean') return `${obj}`; if (typeof obj === 'number') return `${obj}`; if (typeof obj === 'string') { const escaped = obj.replace(/&/g,'&').replace(//g,'>'); return `"${escaped}"`; } if (Array.isArray(obj)) { if (obj.length === 0) return `[]`; const items = obj.map(v => syntaxColorize(v, tok)).join(', '); return `[${items}]`; } if (typeof obj === 'object') { const entries = Object.entries(obj); if (entries.length === 0) return `{}`; const inner = entries.map(([k, v]) => `"${k}": ${syntaxColorize(v, tok)}` ).join(`, `); return `{${inner}}`; } return String(obj); } // ─── Type / status icons ─────────────────────────────────────────────────── const TYPE_META = { llm: { label: 'LLM', colorKey: 'llm' }, tool: { label: 'TOOL', colorKey: 'tool' }, state: { label: 'STATE', colorKey: 'state' }, error: { label: 'ERROR', colorKey: 'error' }, }; function TypeChip({ type, tok }) { const meta = TYPE_META[type] || TYPE_META.state; const color = tok[meta.colorKey]; return ( {meta.label} ); } function StatusDot({ status, tok }) { switch (status) { case 'done': return ( ); case 'error': return ( ); case 'running': return ( ); default: return ( ); } } // ─── Payload viewer ───────────────────────────────────────────────────────── function PayloadViewer({ payload, tok, defaultOpen = false }) { const [open, setOpen] = useState(defaultOpen); const hasPayload = payload && Object.keys(payload).length > 0; if (!hasPayload) return null; const jsonStr = JSON.stringify(payload, null, 2); // Simple syntax highlight by wrapping in spans const highlighted = syntaxColorize(payload, tok); return (
{open && ( 
      )}
); } // ─── Live elapsed ticker ──────────────────────────────────────────────────── function LiveDuration({ startedAt, tok }) { const [elapsed, setElapsed] = useState(() => startedAt ? Date.now() - startedAt : 0); useEffect(() => { if (!startedAt) return; const id = setInterval(() => setElapsed(Date.now() - startedAt), 500); return () => clearInterval(id); }, [startedAt]); return ( {formatDuration(elapsed)} ); } // ─── Tree row ─────────────────────────────────────────────────────────────── function TreeRow({ span, tok, onToggle, expanded }) { const hasChildren = span.children && span.children.length > 0; const isExpanded = expanded[span.id] !== false; // default true return (
{/* Main row */}
{/* Indent guide lines */}
{Array.from({ length: span.depth }).map((_, i) => (
))}
{/* Chevron (only if has children) */} {hasChildren ? ( ) : (
)} {/* Status dot */} {/* Type chip */} {/* Span name */} {span.name} {/* Duration or live ticker */}
{span.status === 'running' ? : span.duration != null ? ( {formatDuration(span.duration)} ) : null } {/* Timestamp */} {span.startTime && ( {formatTime(span.startTime)} )}
{/* Error message */} {span.status === 'error' && span.error && (
{span.error}
)} {/* Payload */} {(span.payload || span.error) && (
)} {/* Children (expanded) */} {hasChildren && isExpanded && (
{span.children.map(child => ( ))}
)}
); } // ─── Tree view ───────────────────────────────────────────────────────────── function TreeView({ tree, tok, onToggle, expanded }) { if (!tree || tree.length === 0) { return (
No spans recorded
); } return (
{tree.map(span => ( ))}
); } // ─── Waterfall row ────────────────────────────────────────────────────────── function WaterfallRow({ span, tok, startTime, totalDuration }) { const offsetPct = startTime ? ((span.startTime - startTime) / totalDuration) * 100 : 0; const widthPct = span.duration != null && totalDuration > 0 ? Math.max((span.duration / totalDuration) * 100, 2) : 4; const color = span.status === 'error' ? tok.error : span.status === 'running' ? tok.running : tok[span.type + 'Color'] || tok[span.type] || tok.tool; const bgColor = span.status === 'error' ? tok.errorBg : span.status === 'running' ? tok.runningBg : tok[span.type + 'Bg'] || tok.toolBg; return (
{/* Time label */} {span.startTime ? formatTime(span.startTime).slice(0, 11) : '—'} {/* Name */} {' '.repeat(span.depth)}{span.name} {/* Type chip */} {/* Bar */}
{/* Duration label inside bar */} {widthPct > 8 && ( {formatDuration(span.duration)} )}
{/* Duration label */} {span.duration != null ? formatDuration(span.duration) : span.status === 'running' ? 'running…' : '—'}
); } // ─── Waterfall view ───────────────────────────────────────────────────────── function WaterfallView({ flatSpans, tok, startTime, totalDuration }) { if (!flatSpans || flatSpans.length === 0) { return (
No spans to display
); } return (
{/* Header */}
time span type duration
{flatSpans.map(span => ( ))}
); } // ─── Filter bar ───────────────────────────────────────────────────────────── function FilterBar({ filterType, filterStatus, search, onFilterType, onFilterStatus, onSearch, tok }) { const types = ['all', 'llm', 'tool', 'state', 'error']; const statuses = ['all', 'done', 'error', 'running']; return (
{/* Search */}
onSearch(e.target.value)} placeholder="Search spans…" style={{ width: '100%', paddingLeft: 28, paddingRight: 8, background: tok.searchBg, border: `1px solid ${tok.border}`, borderRadius: 7, height: 30, fontSize: '0.8rem', color: tok.fg, fontFamily: "'Space Grotesk', sans-serif", outline: 'none', transition: 'border-color 0.15s', }} onFocus={e => { e.target.style.borderColor = tok.accent; }} onBlur={e => { e.target.style.borderColor = tok.border; }} /> {search && ( )}
{/* Type filters */}
{types.map(t => { const isActive = filterType === t; const color = t === 'all' ? tok.accent : tok[t + 'Color'] || tok[t]; return ( ); })}
{/* Status filters */}
{statuses.map(s => { const isActive = filterStatus === s; return ( ); })}
); } // ─── Mode toggle ──────────────────────────────────────────────────────────── function ModeToggle({ mode, onChange, tok }) { const opts = ['tree', 'waterfall']; return (
{opts.map(o => ( ))}
); } // ─── TraceViewer (controlled) ────────────────────────────────────────────── function TraceViewer({ spans = [], mode = 'tree', theme = 'light', filterType = 'all', filterStatus = 'all', search = '', startTime = null, }) { injectTVStyles(); const [resolvedTheme, setResolvedTheme] = useState(() => resolveTheme(theme)); const [expanded, setExpanded] = useState({}); useEffect(() => { if (theme !== 'auto') { setResolvedTheme(theme); return; } const mq = window.matchMedia('(prefers-color-scheme: dark)'); const handler = e => setResolvedTheme(e.matches ? 'dark' : 'light'); mq.addEventListener('change', handler); return () => mq.removeEventListener('change', handler); }, [theme]); const tok = TOKENS[resolvedTheme] || TOKENS.light; // ─── Filter + search ─────────────────────────────────────────────────── const filtered = useMemo(() => { return spans.filter(s => { if (filterType !== 'all' && s.type !== filterType) return false; if (filterStatus !== 'all' && s.status !== filterStatus) return false; if (search) { const q = search.toLowerCase(); if (!s.name.toLowerCase().includes(q)) return false; } return true; }); }, [spans, filterType, filterStatus, search]); // ─── Tree build ─────────────────────────────────────────────────────── const tree = useMemo(() => buildTree(filtered), [filtered]); const flatSpans = useMemo(() => flattenTree(tree), [tree]); // ─── Waterfall timing ───────────────────────────────────────────────── const waterfallStart = startTime || (spans.length ? Math.min(...spans.map(s => s.startTime)) : null); const totalDuration = useMemo(() => { if (!waterfallStart || !filtered.length) return 1; const maxEnd = Math.max(...filtered.filter(s => s.endTime).map(s => s.endTime)); return Math.max(maxEnd - waterfallStart, 1); }, [filtered, waterfallStart]); // ─── Toggle expand/collapse ──────────────────────────────────────────── const handleToggle = useCallback((id) => { setExpanded(prev => ({ ...prev, [id]: prev[id] === false })); }, []); // ─── Count badge ─────────────────────────────────────────────────────── const totalCount = spans.length; const filteredCount = filtered.length; if (!totalCount) { return (
No trace data
Attach a TraceViewerContainer to receive AG-UI events, or pass a spans array directly.
); } return (
{/* Header row */}
Trace {filteredCount < totalCount ? `${filteredCount} / ${totalCount}` : `${totalCount}`} spans
{/* Controls */}
{}} tok={tok} /> {/* mode controlled via external state — mode prop drives rendering */} mode: {mode}
{/* Filter bar (always visible) */}
{}} onFilterStatus={() => {}} onSearch={() => {}} tok={tok} />
{/* Body */}
{mode === 'tree' ? : }
); } // ─── TraceViewerContainer (AG-UI auto-wiring) ─────────────────────────────── /** * Subscribes to AG-UI trace events and maintains internal spans list. * * Events: * SPAN_STARTED → adds span { running } * SPAN_ENDED → updates span { done / error, endTime, duration } * TOOL_CALL_START → adds span { type: 'tool', running } * TOOL_CALL_END → updates tool span { done/error, duration } * RUN_STARTED → resets spans, sets traceId * RUN_FINISHED → marks trace complete * ERROR → adds span { type: 'error' } * TRACE_PAYLOAD → attaches payload to existing span * * Props: * eventSource: EventTarget | EventEmitter * initialSpans?: Span[] * mode, theme → passed through to TraceViewer */ function TraceViewerContainer({ eventSource, initialSpans = [], mode = 'tree', theme = 'light', }) { const [spans, setSpans] = useState(initialSpans); const [filterType, setFilterType] = useState('all'); const [filterStatus, setFilterStatus] = useState('all'); const [search, setSearch] = useState(''); const [viewMode, setViewMode] = useState(mode); const [startTime, setStartTime] = useState(null); // Expose imperative controls via refs for the parent demo const containerRef = useRef({}); useEffect(() => { setViewMode(mode); }, [mode]); useEffect(() => { if (!eventSource) return; function upsertSpan(partial) { setSpans(prev => { const exists = partial.id && prev.some(s => s.id === partial.id); if (exists) return prev.map(s => s.id === partial.id ? { ...s, ...partial } : s); // New span return [...prev, { status: 'running', depth: 0, ...partial }]; }); } function onRunStarted(e) { const d = e.detail || e; setSpans([]); setStartTime(Date.now()); if (d.traceId && containerRef.current) containerRef.current.traceId = d.traceId; } function onSpanStarted(e) { const d = e.detail || e; upsertSpan({ id: d.spanId, parentId: d.parentSpanId || null, name: d.name || d.spanId, type: d.type || 'state', status: 'running', startTime: d.startTime || Date.now(), depth: d.depth || 0, }); if (!startTime) setStartTime(d.startTime || Date.now()); } function onSpanEnded(e) { const d = e.detail || e; const now = Date.now(); setSpans(prev => prev.map(s => { if (s.id !== d.spanId) return s; const endTime = d.endTime || now; const duration = d.duration != null ? d.duration : (endTime - (s.startTime || endTime)); return { ...s, status: d.status || 'done', endTime, duration, error: d.error }; })); } function onToolCallStart(e) { const d = e.detail || e; upsertSpan({ id: d.spanId, parentId: d.parentSpanId || null, name: d.tool || d.spanId, type: 'tool', status: 'running', startTime: d.startTime || Date.now(), depth: d.depth || 0, payload: { args: d.args }, }); if (!startTime) setStartTime(d.startTime || Date.now()); } function onToolCallEnd(e) { const d = e.detail || e; const now = Date.now(); setSpans(prev => prev.map(s => { if (s.id !== d.spanId) return s; const endTime = d.endTime || now; const duration = d.duration != null ? d.duration : (endTime - (s.startTime || endTime)); return { ...s, status: d.error ? 'error' : 'done', endTime, duration, error: d.error, payload: { ...s.payload, result: d.result }, }; })); } function onRunFinished(e) { const d = e.detail || e; // Mark any running spans as done setSpans(prev => prev.map(s => s.status === 'running' ? { ...s, status: 'done', endTime: Date.now() } : s )); if (containerRef.current) containerRef.current.outcome = d.outcome; } function onError(e) { const d = e.detail || e; upsertSpan({ id: `error-${Date.now()}-${Math.random()}`, name: d.message || 'Error', type: 'error', status: 'error', startTime: d.timestamp || Date.now(), error: d.message, stack: d.stack, depth: 0, }); } function onTracePayload(e) { const d = e.detail || e; setSpans(prev => prev.map(s => s.id === d.spanId ? { ...s, payload: d.payload } : s )); } // Wire listeners const evs = [ ['RUN_STARTED', onRunStarted], ['SPAN_STARTED', onSpanStarted], ['SPAN_ENDED', onSpanEnded], ['TOOL_CALL_START', onToolCallStart], ['TOOL_CALL_END', onToolCallEnd], ['RUN_FINISHED', onRunFinished], ['ERROR', onError], ['TRACE_PAYLOAD', onTracePayload], ]; if (typeof eventSource.addEventListener === 'function') { evs.forEach(([name, fn]) => eventSource.addEventListener(name, fn)); return () => evs.forEach(([name, fn]) => eventSource.removeEventListener(name, fn)); } if (typeof eventSource.on === 'function') { evs.forEach(([name, fn]) => eventSource.on(name, fn)); return () => evs.forEach(([name, fn]) => eventSource.off(name, fn)); } }, [eventSource]); return (
{/* Inline controls */}
); } // ─── Inline controls (for TraceViewerContainer) ──────────────────────────── function ModeToggle2({ viewMode, setViewMode, tok }) { return (
{['tree', 'waterfall'].map(m => ( ))}
); } function TypeFilterChips({ filterType, setFilterType, tok }) { return (
{['all', 'llm', 'tool', 'state', 'error'].map(t => ( ))}
); } function StatusFilterChips({ filterStatus, setFilterStatus, tok }) { return (
{['all', 'done', 'error', 'running'].map(s => ( ))}
); } function SearchBox({ search, setSearch, tok }) { return (
setSearch(e.target.value)} placeholder="Search…" style={{ paddingLeft: 24, paddingRight: search ? 24 : 8, height: 28, fontSize: '0.75rem', background: tok.searchBg, border: `1px solid ${tok.border}`, borderRadius: 7, color: tok.fg, fontFamily: "'Space Grotesk', sans-serif", outline: 'none', }} onFocus={e => { e.target.style.borderColor = tok.accent; }} onBlur={e => { e.target.style.borderColor = tok.border; }} /> {search && ( )}
); } // Exports if (typeof module !== 'undefined') { module.exports = { TraceViewer, TraceViewerContainer }; }