@inkeep/agents-manage-ui 0.31.0 → 0.31.1

package/src/app/api/signoz/conversations/[conversationId]/route.ts

@@ -936,6 +936,30 @@ export async function GET(
       agentName = getString(s, SPAN_KEYS.AGENT_NAME, '') || null;
       if (agentId || agentName) break;
     }
+
+    let allSpanAttributes: Array<{
+      spanId: string;
+      traceId: string;
+      timestamp: string;
+      data: Record<string, any>;
+    }> = [];
+    try {
+      allSpanAttributes = await fetchAllSpanAttributes_SQL(
+        conversationId,
+        SIGNOZ_URL,
+        SIGNOZ_API_KEY
+      );
+    } catch (e) {
+      const logger = getLogger('span-attributes');
+      logger.error({ error: e }, 'allSpanAttributes SQL fetch skipped/failed');
+    }
+
+    const spanIdToParentSpanId = new Map<string, string | null>();
+    for (const spanAttr of allSpanAttributes) {
+      const parentSpanId = spanAttr.data[SPAN_KEYS.PARENT_SPAN_ID] || null;
+      spanIdToParentSpanId.set(spanAttr.spanId, parentSpanId);
+    }
+
     // activities
     type Activity = {
       id: string;
@@ -952,6 +976,7 @@ export async function GET(
         | 'artifact_processing';
       description: string;
       timestamp: string;
+      parentSpanId?: string | null;
       status: 'success' | 'error' | 'pending';
       subAgentId?: string;
       subAgentName?: string;
@@ -1040,12 +1065,14 @@ export async function GET(
           getString(span, SPAN_KEYS.OTEL_STATUS_DESCRIPTION, '')
         : '';
 
+      const toolCall = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: toolCall,
         type: ACTIVITY_TYPES.TOOL_CALL,
         toolName: name,
         description: hasError && statusMessage ? `Tool ${name} failed` : `Called ${name}`,
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(toolCall) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentName: getString(span, SPAN_KEYS.SUB_AGENT_NAME, ACTIVITY_NAMES.UNKNOWN_AGENT),
         subAgentId: getString(span, SPAN_KEYS.SUB_AGENT_ID, ACTIVITY_NAMES.UNKNOWN_AGENT),
@@ -1078,11 +1105,13 @@ export async function GET(
         else if (Array.isArray(rawKeys)) keys = rawKeys as string[];
       } catch {}
 
+      const contextResolution = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: contextResolution,
         type: ACTIVITY_TYPES.CONTEXT_RESOLUTION,
         description: `Context fetch ${hasError ? 'failed' : 'completed'}`,
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(contextResolution) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         contextStatusDescription: statusMessage || undefined,
         contextUrl: getString(span, SPAN_KEYS.CONTEXT_URL, '') || undefined,
@@ -1107,11 +1136,13 @@ export async function GET(
         else if (Array.isArray(rawKeys)) keys = rawKeys as string[];
       } catch {}
 
+      const contextHandle = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: contextHandle,
         type: ACTIVITY_TYPES.CONTEXT_RESOLUTION,
         description: `Context handle ${hasError ? 'failed' : 'completed'}`,
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(contextHandle) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         contextStatusDescription: statusMessage || undefined,
         contextUrl: getString(span, SPAN_KEYS.CONTEXT_URL, '') || undefined,
@@ -1125,11 +1156,13 @@ export async function GET(
     for (const span of userMessageSpans) {
       const hasError = getField(span, SPAN_KEYS.HAS_ERROR) === true;
       const durMs = getNumber(span, SPAN_KEYS.DURATION_NANO) / 1e6;
+      const userMessageSpanId = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: userMessageSpanId,
         type: ACTIVITY_TYPES.USER_MESSAGE,
         description: 'User sent a message',
         timestamp: getString(span, SPAN_KEYS.MESSAGE_TIMESTAMP),
+        parentSpanId: spanIdToParentSpanId.get(userMessageSpanId) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: AGENT_IDS.USER,
         subAgentName: ACTIVITY_NAMES.USER,
@@ -1144,11 +1177,13 @@ export async function GET(
     for (const span of aiAssistantSpans) {
       const hasError = getField(span, SPAN_KEYS.HAS_ERROR) === true;
       const durMs = getNumber(span, SPAN_KEYS.DURATION_NANO) / 1e6;
+      const aiAssistantMessageSpanId = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: aiAssistantMessageSpanId,
         type: ACTIVITY_TYPES.AI_ASSISTANT_MESSAGE,
         description: 'AI Assistant responded',
         timestamp: getString(span, SPAN_KEYS.AI_RESPONSE_TIMESTAMP),
+        parentSpanId: spanIdToParentSpanId.get(aiAssistantMessageSpanId) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: getString(span, SPAN_KEYS.SUB_AGENT_ID, ACTIVITY_NAMES.UNKNOWN_AGENT),
         subAgentName: getString(span, SPAN_KEYS.SUB_AGENT_NAME, ACTIVITY_NAMES.UNKNOWN_AGENT),
@@ -1169,11 +1204,13 @@ export async function GET(
       const aiResponseToolCalls = getString(span, SPAN_KEYS.AI_RESPONSE_TOOL_CALLS, '');
       const aiPromptMessages = getString(span, SPAN_KEYS.AI_PROMPT_MESSAGES, '');
 
+      const aiGeneration = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: aiGeneration,
         type: ACTIVITY_TYPES.AI_GENERATION,
         description: 'AI model generating text response',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(aiGeneration) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: getString(
           span,
@@ -1205,11 +1242,13 @@ export async function GET(
       const otelStatusCode = getString(span, SPAN_KEYS.OTEL_STATUS_CODE, '');
       const otelStatusDescription = getString(span, SPAN_KEYS.OTEL_STATUS_DESCRIPTION, '');
 
+      const agentGeneration = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: agentGeneration,
         type: ACTIVITY_TYPES.AGENT_GENERATION,
         description: hasError ? 'Agent generation failed' : 'Agent generation',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(agentGeneration) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         result: hasError
           ? statusMessage || 'Agent generation failed'
@@ -1226,11 +1265,13 @@ export async function GET(
     for (const span of aiStreamingSpans) {
       const hasError = getField(span, SPAN_KEYS.HAS_ERROR) === true;
       const durMs = getNumber(span, SPAN_KEYS.DURATION_NANO) / 1e6;
+      const aiStreamingText = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: aiStreamingText,
         type: ACTIVITY_TYPES.AI_MODEL_STREAMED_TEXT,
         description: 'AI model streaming text response',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(aiStreamingText) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: getString(
           span,
@@ -1258,11 +1299,13 @@ export async function GET(
     for (const span of aiStreamingObjectSpans) {
       const hasError = getField(span, SPAN_KEYS.HAS_ERROR) === true;
       const durMs = getNumber(span, SPAN_KEYS.DURATION_NANO) / 1e6;
+      const aiStreamingObject = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: aiStreamingObject,
         type: ACTIVITY_TYPES.AI_MODEL_STREAMED_OBJECT,
         description: 'AI model streaming object response',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(aiStreamingObject) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: getString(span, SPAN_KEYS.SUB_AGENT_ID, ACTIVITY_NAMES.UNKNOWN_AGENT),
         subAgentName: getString(span, SPAN_KEYS.SUB_AGENT_NAME, ACTIVITY_NAMES.UNKNOWN_AGENT),
@@ -1281,11 +1324,13 @@ export async function GET(
     // context fetchers
     for (const span of contextFetcherSpans) {
       const hasError = getField(span, SPAN_KEYS.HAS_ERROR) === true;
+      const contextFetcher = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: contextFetcher,
         type: ACTIVITY_TYPES.CONTEXT_FETCH,
         description: '',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(contextFetcher) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: UNKNOWN_VALUE,
         subAgentName: 'Context Fetcher',
@@ -1302,11 +1347,13 @@ export async function GET(
       const artifactType = getString(span, SPAN_KEYS.ARTIFACT_TYPE, '');
       const artifactDescription = getString(span, SPAN_KEYS.ARTIFACT_DESCRIPTION, '');
 
+      const artifactProcessing = getString(span, SPAN_KEYS.SPAN_ID, '');
       activities.push({
-        id: getString(span, SPAN_KEYS.SPAN_ID, ''),
+        id: artifactProcessing,
         type: 'artifact_processing',
         description: 'Artifact processed',
         timestamp: span.timestamp,
+        parentSpanId: spanIdToParentSpanId.get(artifactProcessing) || undefined,
         status: hasError ? ACTIVITY_STATUS.ERROR : ACTIVITY_STATUS.SUCCESS,
         subAgentId: getString(span, SPAN_KEYS.SUB_AGENT_ID, ACTIVITY_NAMES.UNKNOWN_AGENT),
         subAgentName: getString(span, SPAN_KEYS.SUB_AGENT_NAME, ACTIVITY_NAMES.UNKNOWN_AGENT),
@@ -1325,6 +1372,21 @@ export async function GET(
     const operationStartTime = allSpanTimes.length > 0 ? Math.min(...allSpanTimes) : null;
     const operationEndTime = allSpanTimes.length > 0 ? Math.max(...allSpanTimes) : null;
 
+    // Resolve parentSpanId to nearest ancestor activity
+    const activityIds = new Set(activities.map((a) => a.id));
+    function findAncestorActivity(spanId: string): string | undefined {
+      if (!spanId) return undefined;
+      if (activityIds.has(spanId)) return spanId;
+      const parentSpanId = spanIdToParentSpanId.get(spanId);
+      if (!parentSpanId) return undefined;
+      return findAncestorActivity(parentSpanId);
+    }
+    for (const activity of activities) {
+      if (activity.parentSpanId) {
+        activity.parentSpanId = findAncestorActivity(activity.parentSpanId) || undefined;
+      }
+    }
+
     // Sort activities by pre-parsed timestamps
     activities.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
 
@@ -1374,23 +1436,6 @@ export async function GET(
 
     const openAICallsCount = aiGenerationSpans.length;
 
-    let allSpanAttributes: Array<{
-      spanId: string;
-      traceId: string;
-      timestamp: string;
-      data: Record<string, any>;
-    }> = [];
-    try {
-      allSpanAttributes = await fetchAllSpanAttributes_SQL(
-        conversationId,
-        SIGNOZ_URL,
-        SIGNOZ_API_KEY
-      );
-    } catch (e) {
-      const logger = getLogger('span-attributes');
-      logger.error({ error: e }, 'allSpanAttributes SQL fetch skipped/failed');
-    }
-
     const conversation = {
       conversationId,
       startTime: conversationStartTime ? conversationStartTime : null,

package/src/components/traces/timeline/hierarchical-timeline.tsx

@@ -0,0 +1,151 @@
+import { useState } from 'react';
+import { TimelineItem } from '@/components/traces/timeline/timeline-item';
+import { buildActivityTree, type TreeNode } from '@/components/traces/timeline/tree-utils';
+import type { ActivityItem } from '@/components/traces/timeline/types';
+
+interface HierarchicalTimelineProps {
+  activities: ActivityItem[];
+  onSelect: (a: ActivityItem) => void;
+  selectedActivityId?: string | null;
+  collapsedAiMessages?: Set<string>;
+  onToggleAiMessageCollapse?: (activityId: string) => void;
+}
+
+interface TreeNodeItemProps {
+  node: TreeNode;
+  isLast: boolean;
+  onSelect: (a: ActivityItem) => void;
+  selectedActivityId?: string | null;
+  collapsedAiMessages?: Set<string>;
+  onToggleAiMessageCollapse?: (activityId: string) => void;
+  collapsedNodes: Set<string>;
+  toggleNodeCollapse: (nodeId: string) => void;
+}
+
+function TreeNodeItem({
+  node,
+  isLast,
+  onSelect,
+  selectedActivityId,
+  collapsedAiMessages,
+  onToggleAiMessageCollapse,
+  collapsedNodes,
+  toggleNodeCollapse,
+}: TreeNodeItemProps) {
+  const hasChildren = node.children.length > 0;
+  const isCollapsed = collapsedNodes.has(node.activity.id);
+  const indentSize = 24;
+
+  return (
+    <div className="relative">
+      {/* Vertical line extending through all descendants - positioned relative to entire subtree */}
+      {!isCollapsed && !isLast && (
+        <div
+          className="absolute left-0 top-0 border-l border-border"
+          style={{
+            left: node.depth > 0 ? `${(node.depth - 1) * indentSize + 7}px` : '7px',
+            bottom: '-16px',
+          }}
+        />
+      )}
+
+      <div className="flex items-start">
+        <div
+          style={{
+            width: `${node.depth * indentSize}px`,
+            minWidth: `${node.depth * indentSize}px`,
+          }}
+          className="relative flex-shrink-0"
+        >
+          {node.depth > 0 && (
+            <div
+              className="absolute top-[16px] border-t border-border"
+              style={{
+                left: `${(node.depth - 1) * indentSize + 7}px`,
+                width: `${indentSize - 7}px`,
+              }}
+            />
+          )}
+        </div>
+
+        <div className="flex-1">
+          <div className="inline-block w-full">
+            <TimelineItem
+              activity={node.activity}
+              isLast={isLast && (node.children.length === 0 || isCollapsed)}
+              onSelect={() => onSelect(node.activity)}
+              isSelected={selectedActivityId === node.activity.id}
+              isAiMessageCollapsed={collapsedAiMessages?.has(node.activity.id) || false}
+              onToggleAiMessageCollapse={onToggleAiMessageCollapse}
+              hasChildren={hasChildren}
+              isCollapsed={isCollapsed}
+              onToggleCollapse={() => toggleNodeCollapse(node.activity.id)}
+            />
+          </div>
+        </div>
+      </div>
+
+      {!isCollapsed && node.children.length > 0 && (
+        <div>
+          {node.children.map((child, index) => (
+            <TreeNodeItem
+              key={`${child.activity.id}-${child.activity.type}-${index}`}
+              node={child}
+              isLast={index === node.children.length - 1}
+              onSelect={onSelect}
+              selectedActivityId={selectedActivityId}
+              collapsedAiMessages={collapsedAiMessages}
+              onToggleAiMessageCollapse={onToggleAiMessageCollapse}
+              collapsedNodes={collapsedNodes}
+              toggleNodeCollapse={toggleNodeCollapse}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function HierarchicalTimeline({
+  activities,
+  onSelect,
+  selectedActivityId,
+  collapsedAiMessages,
+  onToggleAiMessageCollapse,
+}: HierarchicalTimelineProps) {
+  const [collapsedNodes, setCollapsedNodes] = useState<Set<string>>(new Set());
+
+  const toggleNodeCollapse = (nodeId: string) => {
+    setCollapsedNodes((prev) => {
+      const newSet = new Set(prev);
+      if (newSet.has(nodeId)) {
+        newSet.delete(nodeId);
+      } else {
+        newSet.add(nodeId);
+      }
+      return newSet;
+    });
+  };
+
+  const tree = buildActivityTree(activities);
+
+  return (
+    <div className="pt-2 px-6 pb-6">
+      <div className="relative space-y-2">
+        {tree.map((node, index) => (
+          <TreeNodeItem
+            key={`${node.activity.id}-${node.activity.type}-${index}`}
+            node={node}
+            isLast={index === tree.length - 1}
+            onSelect={onSelect}
+            selectedActivityId={selectedActivityId}
+            collapsedAiMessages={collapsedAiMessages}
+            onToggleAiMessageCollapse={onToggleAiMessageCollapse}
+            collapsedNodes={collapsedNodes}
+            toggleNodeCollapse={toggleNodeCollapse}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/traces/timeline/timeline-item.tsx

@@ -1,6 +1,5 @@
 import {
   ArrowRight,
-  ArrowUpRight,
   ChevronDown,
   ChevronRight,
   Cpu,
@@ -79,6 +78,9 @@ interface TimelineItemProps {
   isSelected?: boolean;
   isAiMessageCollapsed?: boolean;
   onToggleAiMessageCollapse?: (activityId: string) => void;
+  hasChildren?: boolean;
+  isCollapsed?: boolean;
+  onToggleCollapse?: () => void;
 }
 
 export function TimelineItem({
@@ -88,6 +90,9 @@ export function TimelineItem({
   isSelected = false,
   isAiMessageCollapsed = false,
   onToggleAiMessageCollapse,
+  hasChildren = false,
+  isCollapsed = false,
+  onToggleCollapse,
 }: TimelineItemProps) {
   const typeForIcon =
     activity.type === ACTIVITY_TYPES.TOOL_CALL && activity.toolType === TOOL_TYPES.TRANSFER
@@ -113,8 +118,10 @@ export function TimelineItem({
   return (
     <div className={`flex flex-col text-muted-foreground relative text-xs`}>
       <div className="flex items-start">
-        <div className="mr-2 py-2">
-          <Icon className={`w-4 h-4 ${className}`} />
+        <div className="mr-2 py-2" style={{ width: '16px' }}>
+          <div className="absolute left-[7px] top-[8px] -translate-x-1/2 flex items-center justify-center w-5 h-5 rounded bg-white dark:bg-background z-10">
+            <Icon className={`w-4 h-4 ${className}`} />
+          </div>
         </div>
 
         <div
@@ -122,7 +129,7 @@ export function TimelineItem({
             isSelected ? 'ring-1 ring-primary/50 bg-primary/5' : ''
           }`}
         >
-          <div className="flex items-center gap-2">
+          <div className="flex items-center justify-between gap-2">
             <button
               type="button"
               onClick={onSelect}
@@ -132,11 +139,24 @@ export function TimelineItem({
               <span className="font-medium">
                 <Streamdown>{activity.description}</Streamdown>
               </span>
-              <ArrowUpRight
-                className={`h-4 w-4 transition-colors ${activity.status === 'error' ? 'text-red-700 group-hover:text-red-800' : 'text-muted-foreground group-hover:text-primary'}`}
-                aria-hidden="true"
-              />
             </button>
+            {hasChildren && onToggleCollapse && (
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onToggleCollapse();
+                }}
+                className="flex-shrink-0 inline-flex items-center justify-center w-5 h-5 rounded hover:bg-muted transition-colors"
+                title={isCollapsed ? 'Expand children' : 'Collapse children'}
+              >
+                {isCollapsed ? (
+                  <ChevronRight className="w-4 h-4 text-muted-foreground" />
+                ) : (
+                  <ChevronDown className="w-4 h-4 text-muted-foreground" />
+                )}
+              </button>
+            )}
           </div>
 
           {/* user message bubble */}
@@ -400,7 +420,12 @@ export function TimelineItem({
         </div>
       </div>
 
-      {!isLast && <div className="absolute top-8 left-[7px] border-l border-border h-full" />}
+      {!isLast && !isCollapsed && hasChildren && (
+        <div
+          className="absolute top-4 left-[7px] border-l border-border"
+          style={{ height: 'calc(100%)' }}
+        />
+      )}
     </div>
   );
 }

package/src/components/traces/timeline/timeline-wrapper.tsx

@@ -4,7 +4,7 @@ import { toast } from 'sonner';
 import { StickToBottom } from 'use-stick-to-bottom';
 import { ConversationTracesLink } from '@/components/traces/signoz-link';
 import { ActivityDetailsSidePane } from '@/components/traces/timeline/activity-details-sidepane';
-import { ActivityTimeline } from '@/components/traces/timeline/activity-timeline';
+import { HierarchicalTimeline } from '@/components/traces/timeline/hierarchical-timeline';
 import { renderPanelContent } from '@/components/traces/timeline/render-panel-content';
 import type {
   ActivityItem,
@@ -363,7 +363,9 @@ export function TimelineWrapper({
         <div className="bg-background h-full flex flex-col py-4">
           <div className="flex-shrink-0">
             <div className="flex items-center justify-between px-6 pb-4">
-              <div className="text-foreground text-md font-medium">Activity timeline</div>
+              <div className="flex items-center gap-2">
+                <div className="text-foreground text-md font-medium">Activity timeline</div>
+              </div>
               <div className="flex items-center gap-2">
                 {/* Copy JSON Button */}
                 {onCopyTrace && (
@@ -435,7 +437,7 @@ export function TimelineWrapper({
                 initial="smooth"
               >
                 <StickToBottom.Content>
-                  <ActivityTimeline
+                  <HierarchicalTimeline
                     activities={sortedActivities}
                     onSelect={(activity) => {
                       setSelected({
@@ -469,7 +471,7 @@ export function TimelineWrapper({
               </StickToBottom>
             ) : (
               <div className="h-full overflow-y-auto scrollbar-thin scrollbar-thumb-muted-foreground/30 scrollbar-track-transparent dark:scrollbar-thumb-muted-foreground/50">
-                <ActivityTimeline
+                <HierarchicalTimeline
                   activities={sortedActivities}
                   onSelect={(activity) => {
                     setSelected({

package/src/components/traces/timeline/tree-utils.ts

@@ -0,0 +1,81 @@
+import type { ActivityItem } from './types';
+
+export interface TreeNode {
+  activity: ActivityItem;
+  children: TreeNode[];
+  depth: number;
+}
+
+export function buildActivityTree(activities: ActivityItem[]): TreeNode[] {
+  const sortedActivities = [...activities].sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+  );
+
+  const nodeMap = new Map<string, TreeNode>();
+  const rootNodes: TreeNode[] = [];
+  const activityIndexMap = new Map<string, number>();
+
+  for (let i = 0; i < sortedActivities.length; i++) {
+    const activity = sortedActivities[i];
+    activityIndexMap.set(activity.id, i);
+    nodeMap.set(activity.id, {
+      activity,
+      children: [],
+      depth: 0,
+    });
+  }
+
+  for (const activity of sortedActivities) {
+    const node = nodeMap.get(activity.id);
+    if (!node) continue;
+
+    // activity.parentSpanId is already resolved to nearest ancestor activity by API route
+    const parentSpanId = activity.parentSpanId;
+
+    if (parentSpanId && nodeMap.has(parentSpanId)) {
+      const parent = nodeMap.get(parentSpanId);
+      if (parent) {
+        parent.children.push(node);
+        node.depth = parent.depth + 1;
+      }
+    } else {
+      rootNodes.push(node);
+    }
+  }
+
+  function sortChildren(node: TreeNode) {
+    node.children.sort(
+      (a, b) => new Date(a.activity.timestamp).getTime() - new Date(b.activity.timestamp).getTime()
+    );
+    for (const child of node.children) {
+      sortChildren(child);
+    }
+  }
+
+  for (const root of rootNodes) {
+    sortChildren(root);
+  }
+
+  rootNodes.sort(
+    (a, b) => new Date(a.activity.timestamp).getTime() - new Date(b.activity.timestamp).getTime()
+  );
+
+  return rootNodes;
+}
+
+export function flattenTree(nodes: TreeNode[]): ActivityItem[] {
+  const result: ActivityItem[] = [];
+
+  function traverse(node: TreeNode) {
+    result.push(node.activity);
+    for (const child of node.children) {
+      traverse(child);
+    }
+  }
+
+  for (const node of nodes) {
+    traverse(node);
+  }
+
+  return result;
+}

package/src/components/traces/timeline/types.ts

@@ -33,6 +33,7 @@ export interface ActivityItem {
   name?: string;
   description: string;
   timestamp: string;
+  parentSpanId?: string | null;
   subAgentId?: string;
   subAgentName?: string;
   toolName?: string;