@roj-ai/debug 0.0.2

package/src/components/debug/communication/hooks/useDiagramData.ts

@@ -0,0 +1,294 @@
+import type { AgentTreeNode } from '@roj-ai/shared'
+import type { BuiltinEvent, DomainEvent } from '@roj-ai/sdk'
+import { useMemo } from 'react'
+import type { DiagramData, DiagramLLMBlock, DiagramMessage, DiagramParticipant, DiagramToolBlock, ParticipantRole, ParticipantStatus } from '../types'
+import { useTimeCompression } from './useTimeCompression'
+
+interface UseDiagramDataProps {
+	events: DomainEvent[]
+	agents: AgentTreeNode[]
+}
+
+export function useDiagramData({ events, agents }: UseDiagramDataProps): DiagramData & {
+	timestampToY: (timestamp: number) => number
+	formatIdleDuration: (ms: number) => string
+} {
+	// Extract all timestamps for compression
+	const timestamps = useMemo(() => {
+		return events.map((e) => e.timestamp).sort((a, b) => a - b)
+	}, [events])
+
+	const { segments, totalHeight, timestampToY, formatIdleDuration } = useTimeCompression(timestamps)
+
+	// Build participants from agents
+	const participants = useMemo((): DiagramParticipant[] => {
+		const result: DiagramParticipant[] = []
+
+		// User is always first
+		const sessionStart = events.find((e) => e.type === 'session_created')?.timestamp ?? Date.now()
+		result.push({
+			id: 'user',
+			name: 'User',
+			role: 'user',
+			spawnedAt: sessionStart,
+			status: 'idle',
+			columnIndex: 0,
+		})
+
+		// Flatten agent tree with BFS to maintain hierarchy order
+		const flattenAgents = (nodes: AgentTreeNode[], parentRole: ParticipantRole | null = null): void => {
+			for (const agent of nodes) {
+				const role = determineRole(agent.definitionName, parentRole)
+				result.push({
+					id: agent.id as DiagramParticipant['id'],
+					name: formatAgentName(agent.definitionName),
+					role,
+					spawnedAt: getAgentSpawnTime(events, agent.id),
+					status: mapAgentStatus(agent.status),
+					columnIndex: result.length,
+				})
+				flattenAgents(agent.children, role)
+			}
+		}
+
+		flattenAgents(agents)
+
+		return result
+	}, [agents, events])
+
+	// Build messages from mailbox events with parallel message offset
+	const messages = useMemo((): DiagramMessage[] => {
+		const rawMessages: DiagramMessage[] = []
+
+		for (const event of events) {
+			const e = event as BuiltinEvent
+			if (e.type === 'mailbox_message') {
+				const fromId = e.message.from === 'user' ? 'user' : e.message.from
+				rawMessages.push({
+					id: e.message.id,
+					fromId: fromId as DiagramMessage['fromId'],
+					toId: e.toAgentId,
+					timestamp: e.timestamp,
+					content: e.message.content,
+					yPosition: timestampToY(e.timestamp),
+				})
+			}
+
+			// User messages to agents (sent via send_message endpoint)
+			if (e.type === 'user_message_sent') {
+				rawMessages.push({
+					id: e.messageId,
+					fromId: e.agentId,
+					toId: 'user',
+					timestamp: e.timestamp,
+					content: e.message,
+					yPosition: timestampToY(e.timestamp),
+				})
+			}
+		}
+
+		// Sort by timestamp
+		rawMessages.sort((a, b) => a.timestamp - b.timestamp)
+
+		// Offset parallel messages (same timestamp or within 100ms)
+		const PARALLEL_THRESHOLD_MS = 100
+		const MESSAGE_Y_OFFSET = 14
+
+		const result: DiagramMessage[] = []
+		let parallelGroup: DiagramMessage[] = []
+
+		for (const msg of rawMessages) {
+			if (parallelGroup.length === 0) {
+				parallelGroup.push(msg)
+			} else {
+				const lastMsg = parallelGroup[parallelGroup.length - 1]
+				if (Math.abs(msg.timestamp - lastMsg.timestamp) <= PARALLEL_THRESHOLD_MS) {
+					parallelGroup.push(msg)
+				} else {
+					// Process previous group
+					result.push(...offsetParallelMessages(parallelGroup, MESSAGE_Y_OFFSET))
+					parallelGroup = [msg]
+				}
+			}
+		}
+
+		// Process last group
+		if (parallelGroup.length > 0) {
+			result.push(...offsetParallelMessages(parallelGroup, MESSAGE_Y_OFFSET))
+		}
+
+		return result
+	}, [events, timestampToY])
+
+	// Build LLM blocks from inference events
+	const llmBlocks = useMemo((): DiagramLLMBlock[] => {
+		const result: DiagramLLMBlock[] = []
+		const pendingInferences = new Map<string, { event: Extract<BuiltinEvent, { type: 'inference_started' }>; idx: number }>()
+
+		for (const event of events) {
+			const e = event as BuiltinEvent
+			if (e.type === 'inference_started') {
+				const idx = result.length
+				result.push({
+					id: `llm-${e.agentId}-${e.timestamp}`,
+					participantId: e.agentId,
+					startTime: e.timestamp,
+					status: 'running',
+					yStart: timestampToY(e.timestamp),
+					yEnd: timestampToY(e.timestamp) + 30, // Minimum height
+				})
+				pendingInferences.set(e.agentId, { event: e, idx })
+			}
+
+			if (e.type === 'inference_completed') {
+				const pending = pendingInferences.get(e.agentId)
+				if (pending) {
+					result[pending.idx] = {
+						...result[pending.idx],
+						endTime: e.timestamp,
+						status: 'success',
+						model: e.metrics.model,
+						tokens: e.metrics.totalTokens,
+						llmCallId: e.llmCallId,
+						yEnd: timestampToY(e.timestamp),
+					}
+					pendingInferences.delete(e.agentId)
+				}
+			}
+
+			if (e.type === 'inference_failed') {
+				const pending = pendingInferences.get(e.agentId)
+				if (pending) {
+					result[pending.idx] = {
+						...result[pending.idx],
+						endTime: e.timestamp,
+						status: 'error',
+						llmCallId: e.llmCallId,
+						yEnd: timestampToY(e.timestamp),
+					}
+					pendingInferences.delete(e.agentId)
+				}
+			}
+		}
+
+		return result
+	}, [events, timestampToY])
+
+	// Build tool blocks from tool events
+	const toolBlocks = useMemo((): DiagramToolBlock[] => {
+		const result: DiagramToolBlock[] = []
+		const pendingTools = new Map<string, { event: Extract<BuiltinEvent, { type: 'tool_started' }>; idx: number }>()
+
+		for (const event of events) {
+			const e = event as BuiltinEvent
+			if (e.type === 'tool_started') {
+				const idx = result.length
+				result.push({
+					id: `tool-${e.toolCallId}`,
+					toolCallId: e.toolCallId,
+					participantId: e.agentId,
+					toolName: e.toolName,
+					startTime: e.timestamp,
+					status: 'running',
+					yStart: timestampToY(e.timestamp),
+					yEnd: timestampToY(e.timestamp) + 20, // Minimum height
+				})
+				pendingTools.set(e.toolCallId, { event: e, idx })
+			}
+
+			if (e.type === 'tool_completed') {
+				const pending = pendingTools.get(e.toolCallId)
+				if (pending) {
+					result[pending.idx] = {
+						...result[pending.idx],
+						endTime: e.timestamp,
+						status: 'success',
+						yEnd: timestampToY(e.timestamp),
+					}
+					pendingTools.delete(e.toolCallId)
+				}
+			}
+
+			if (e.type === 'tool_failed') {
+				const pending = pendingTools.get(e.toolCallId)
+				if (pending) {
+					result[pending.idx] = {
+						...result[pending.idx],
+						endTime: e.timestamp,
+						status: 'error',
+						yEnd: timestampToY(e.timestamp),
+					}
+					pendingTools.delete(e.toolCallId)
+				}
+			}
+		}
+
+		return result
+	}, [events, timestampToY])
+
+	const sessionStartTime = useMemo(() => {
+		const sessionCreated = events.find((e) => e.type === 'session_created')
+		return sessionCreated?.timestamp ?? Date.now()
+	}, [events])
+
+	return {
+		participants,
+		messages,
+		llmBlocks,
+		toolBlocks,
+		timeSegments: segments,
+		totalHeight,
+		sessionStartTime,
+		timestampToY,
+		formatIdleDuration,
+	}
+}
+
+// Helper functions
+
+function determineRole(definitionName: string, parentRole: ParticipantRole | null): ParticipantRole {
+	const lower = definitionName.toLowerCase()
+	if (lower.includes('communicator')) return 'communicator'
+	if (lower.includes('orchestrator')) return 'orchestrator'
+	if (parentRole === 'orchestrator' || parentRole === 'worker') return 'worker'
+	if (parentRole === null) return 'communicator' // Root agent without orchestrator
+	return 'worker'
+}
+
+function formatAgentName(definitionName: string): string {
+	// Convert kebab-case or snake_case to Title Case
+	return definitionName
+		.replace(/[-_]/g, ' ')
+		.replace(/\b\w/g, (c) => c.toUpperCase())
+		.replace(/^Entry$/, 'Entry Agent')
+}
+
+function getAgentSpawnTime(events: DomainEvent[], agentId: string): number {
+	const spawnEvent = events.find(
+		(e) => e.type === 'agent_spawned' && 'agentId' in e && (e as BuiltinEvent & { type: 'agent_spawned' }).agentId === agentId,
+	)
+	return spawnEvent?.timestamp ?? Date.now()
+}
+
+function mapAgentStatus(status: AgentTreeNode['status']): ParticipantStatus {
+	// AgentTreeNode.status is from common-schemas AgentStatus:
+	// "idle" | "thinking" | "responding" | "waiting_for_user" | "error"
+	// which matches ParticipantStatus exactly
+	return status
+}
+
+function offsetParallelMessages(messages: DiagramMessage[], offset: number): DiagramMessage[] {
+	if (messages.length <= 1) {
+		return messages
+	}
+
+	// Center the group around the original Y position
+	const baseY = messages[0].yPosition
+	const totalHeight = (messages.length - 1) * offset
+	const startY = baseY - totalHeight / 2
+
+	return messages.map((msg, idx) => ({
+		...msg,
+		yPosition: startY + idx * offset,
+	}))
+}

package/src/components/debug/communication/hooks/useTimeCompression.ts

@@ -0,0 +1,140 @@
+import { useMemo } from 'react'
+import type { TimeCompressionConfig, TimeSegment } from '../types'
+
+const DEFAULT_CONFIG: TimeCompressionConfig = {
+	pixelsPerSecond: 50,
+	maxIdleHeight: 40,
+	idleThresholdMs: 30000, // 30 seconds
+}
+
+export function useTimeCompression(
+	timestamps: number[],
+	config: Partial<TimeCompressionConfig> = {},
+): {
+	segments: TimeSegment[]
+	totalHeight: number
+	timestampToY: (timestamp: number) => number
+	formatIdleDuration: (ms: number) => string
+} {
+	const mergedConfig = { ...DEFAULT_CONFIG, ...config }
+
+	const segments = useMemo(() => {
+		if (timestamps.length === 0) {
+			return []
+		}
+
+		const sorted = [...timestamps].sort((a, b) => a - b)
+		const result: TimeSegment[] = []
+
+		let currentStart = sorted[0]
+		let lastTimestamp = sorted[0]
+		let isIdle = false
+
+		for (let i = 1; i < sorted.length; i++) {
+			const gap = sorted[i] - lastTimestamp
+
+			if (gap > mergedConfig.idleThresholdMs && !isIdle) {
+				// End active segment, start idle
+				result.push({
+					startTime: currentStart,
+					endTime: lastTimestamp,
+					type: 'active',
+					displayHeight: Math.max(
+						20,
+						((lastTimestamp - currentStart) / 1000) * mergedConfig.pixelsPerSecond,
+					),
+					actualDuration: lastTimestamp - currentStart,
+				})
+				currentStart = lastTimestamp
+				isIdle = true
+			} else if (gap <= mergedConfig.idleThresholdMs && isIdle) {
+				// End idle segment, start active
+				result.push({
+					startTime: currentStart,
+					endTime: sorted[i],
+					type: 'idle',
+					displayHeight: mergedConfig.maxIdleHeight,
+					actualDuration: sorted[i] - currentStart,
+				})
+				currentStart = sorted[i]
+				isIdle = false
+			}
+
+			lastTimestamp = sorted[i]
+		}
+
+		// Close final segment
+		if (currentStart !== lastTimestamp || result.length === 0) {
+			result.push({
+				startTime: currentStart,
+				endTime: lastTimestamp,
+				type: isIdle ? 'idle' : 'active',
+				displayHeight: isIdle
+					? mergedConfig.maxIdleHeight
+					: Math.max(
+						20,
+						((lastTimestamp - currentStart) / 1000) * mergedConfig.pixelsPerSecond,
+					),
+				actualDuration: lastTimestamp - currentStart,
+			})
+		}
+
+		return result
+	}, [timestamps, mergedConfig.idleThresholdMs, mergedConfig.pixelsPerSecond, mergedConfig.maxIdleHeight])
+
+	const totalHeight = useMemo(() => {
+		return segments.reduce((sum, seg) => sum + seg.displayHeight, 0)
+	}, [segments])
+
+	const timestampToY = useMemo(() => {
+		return (timestamp: number): number => {
+			let y = 0
+
+			for (const segment of segments) {
+				if (timestamp < segment.startTime) {
+					return y
+				}
+
+				if (timestamp <= segment.endTime) {
+					if (segment.type === 'idle') {
+						// Linear interpolation within idle segment
+						const progress = (timestamp - segment.startTime) / (segment.endTime - segment.startTime)
+						return y + progress * segment.displayHeight
+					} else {
+						// Active segment: proportional to time
+						const segmentDuration = segment.endTime - segment.startTime
+						if (segmentDuration === 0) {
+							return y
+						}
+						const progress = (timestamp - segment.startTime) / segmentDuration
+						return y + progress * segment.displayHeight
+					}
+				}
+
+				y += segment.displayHeight
+			}
+
+			return y
+		}
+	}, [segments])
+
+	const formatIdleDuration = (ms: number): string => {
+		const seconds = Math.floor(ms / 1000)
+		const minutes = Math.floor(seconds / 60)
+		const hours = Math.floor(minutes / 60)
+		const days = Math.floor(hours / 24)
+
+		if (days > 0) {
+			return `${days}d ${hours % 24}h idle`
+		}
+		if (hours > 0) {
+			return `${hours}h ${minutes % 60}m idle`
+		}
+		if (minutes > 0) {
+			return `${minutes}m idle`
+		}
+		return `${seconds}s idle`
+	}
+
+	return { segments, totalHeight, timestampToY, formatIdleDuration }
+}

package/src/components/debug/communication/hooks/useZoomPan.ts

@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { ZoomPanState } from '../types'
+
+const MIN_ZOOM = 0.25
+const MAX_ZOOM = 4
+const ZOOM_STEP = 0.25
+
+export function useZoomPan(totalHeight: number) {
+	const [state, setState] = useState<ZoomPanState>({
+		zoom: 1,
+		scrollY: 0,
+		autoScroll: true,
+	})
+
+	const containerRef = useRef<HTMLDivElement>(null)
+	const prevTotalHeightRef = useRef(totalHeight)
+
+	// Auto-scroll to bottom when new content arrives
+	useEffect(() => {
+		if (state.autoScroll && totalHeight > prevTotalHeightRef.current && containerRef.current) {
+			containerRef.current.scrollTop = containerRef.current.scrollHeight
+		}
+		prevTotalHeightRef.current = totalHeight
+	}, [totalHeight, state.autoScroll])
+
+	const zoomIn = useCallback(() => {
+		setState((prev) => ({
+			...prev,
+			zoom: Math.min(MAX_ZOOM, prev.zoom + ZOOM_STEP),
+		}))
+	}, [])
+
+	const zoomOut = useCallback(() => {
+		setState((prev) => ({
+			...prev,
+			zoom: Math.max(MIN_ZOOM, prev.zoom - ZOOM_STEP),
+		}))
+	}, [])
+
+	const resetZoom = useCallback(() => {
+		setState((prev) => ({
+			...prev,
+			zoom: 1,
+		}))
+	}, [])
+
+	const toggleAutoScroll = useCallback(() => {
+		setState((prev) => ({
+			...prev,
+			autoScroll: !prev.autoScroll,
+		}))
+	}, [])
+
+	const handleScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+		const target = e.target as HTMLDivElement
+		const isAtBottom = Math.abs(target.scrollHeight - target.clientHeight - target.scrollTop) < 10
+
+		setState((prev) => ({
+			...prev,
+			scrollY: target.scrollTop,
+			// Disable auto-scroll if user scrolled up manually
+			autoScroll: prev.autoScroll ? isAtBottom : prev.autoScroll,
+		}))
+	}, [])
+
+	const handleWheel = useCallback((e: React.WheelEvent<HTMLDivElement>) => {
+		if (e.ctrlKey || e.metaKey) {
+			e.preventDefault()
+			const delta = e.deltaY > 0 ? -ZOOM_STEP : ZOOM_STEP
+			setState((prev) => ({
+				...prev,
+				zoom: Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, prev.zoom + delta)),
+			}))
+		}
+	}, [])
+
+	return {
+		state,
+		containerRef,
+		zoomIn,
+		zoomOut,
+		resetZoom,
+		toggleAutoScroll,
+		handleScroll,
+		handleWheel,
+	}
+}

package/src/components/debug/communication/popovers/ElementPopover.tsx

@@ -0,0 +1,158 @@
+import type { DiagramLLMBlock, DiagramMessage, DiagramToolBlock, PopoverElement, TimeSegment } from '../types'
+
+interface ElementPopoverProps {
+	element: PopoverElement
+	x: number
+	y: number
+}
+
+export function ElementPopover({ element, x, y }: ElementPopoverProps) {
+	// Offset from cursor
+	const offsetX = 12
+	const offsetY = 12
+
+	return (
+		<div
+			className="fixed z-50 pointer-events-none"
+			style={{
+				left: x + offsetX,
+				top: y + offsetY,
+			}}
+		>
+			<div className="bg-slate-900 text-white text-[11px] rounded-md shadow-xl p-2.5 max-w-[280px] border border-slate-700">
+				{element.type === 'message' && <MessagePopover data={element.data} />}
+				{element.type === 'llm' && <LLMPopover data={element.data} />}
+				{element.type === 'tool' && <ToolPopover data={element.data} />}
+				{element.type === 'idle' && <IdlePopover data={element.data} />}
+			</div>
+		</div>
+	)
+}
+
+function MessagePopover({ data }: { data: DiagramMessage }) {
+	return (
+		<div className="space-y-2">
+			<div className="flex items-center gap-2">
+				<span className="w-1.5 h-1.5 rounded-full bg-blue-400" />
+				<span className="font-medium text-blue-300">Message</span>
+			</div>
+
+			<div className="grid grid-cols-[auto,1fr] gap-x-3 gap-y-1 text-[10px]">
+				<span className="text-slate-500">From</span>
+				<span className="text-slate-300 font-mono">{String(data.fromId).slice(0, 12)}</span>
+				<span className="text-slate-500">To</span>
+				<span className="text-slate-300 font-mono">{String(data.toId).slice(0, 12)}</span>
+				<span className="text-slate-500">Time</span>
+				<span className="text-slate-300">{new Date(data.timestamp).toLocaleTimeString()}</span>
+			</div>
+
+			<div className="pt-1.5 border-t border-slate-700/50">
+				<div className="text-slate-300 leading-relaxed line-clamp-4">
+					{data.content}
+				</div>
+			</div>
+		</div>
+	)
+}
+
+function LLMPopover({ data }: { data: DiagramLLMBlock }) {
+	const duration = data.endTime
+		? ((data.endTime - data.startTime) / 1000).toFixed(1) + 's'
+		: null
+
+	return (
+		<div className="space-y-2">
+			<div className="flex items-center gap-2">
+				<span className="w-1.5 h-1.5 rounded-full bg-violet-400" />
+				<span className="font-medium text-violet-300">LLM Inference</span>
+				{data.status === 'running' && <span className="text-[9px] bg-amber-500/20 text-amber-300 px-1.5 py-0.5 rounded">Running</span>}
+				{data.status === 'error' && <span className="text-[9px] bg-red-500/20 text-red-300 px-1.5 py-0.5 rounded">Error</span>}
+			</div>
+
+			<div className="grid grid-cols-[auto,1fr] gap-x-3 gap-y-1 text-[10px]">
+				{data.model && (
+					<>
+						<span className="text-slate-500">Model</span>
+						<span className="text-slate-300 font-mono">{data.model.split('/').pop()}</span>
+					</>
+				)}
+				{duration && (
+					<>
+						<span className="text-slate-500">Duration</span>
+						<span className="text-slate-300">{duration}</span>
+					</>
+				)}
+				{data.tokens && (
+					<>
+						<span className="text-slate-500">Tokens</span>
+						<span className="text-slate-300">{data.tokens.toLocaleString()}</span>
+					</>
+				)}
+			</div>
+
+			{data.llmCallId && (
+				<div className="pt-1.5 border-t border-slate-700/50 text-[9px] text-slate-500">
+					Click to view details
+				</div>
+			)}
+		</div>
+	)
+}
+
+function ToolPopover({ data }: { data: DiagramToolBlock }) {
+	const duration = data.endTime
+		? ((data.endTime - data.startTime) / 1000).toFixed(1) + 's'
+		: null
+
+	return (
+		<div className="space-y-2">
+			<div className="flex items-center gap-2">
+				<span className="w-1.5 h-1.5 rounded-full bg-teal-400" />
+				<span className="font-medium text-teal-300">Tool Execution</span>
+				{data.status === 'running' && <span className="text-[9px] bg-amber-500/20 text-amber-300 px-1.5 py-0.5 rounded">Running</span>}
+				{data.status === 'error' && <span className="text-[9px] bg-red-500/20 text-red-300 px-1.5 py-0.5 rounded">Error</span>}
+			</div>
+
+			<div className="grid grid-cols-[auto,1fr] gap-x-3 gap-y-1 text-[10px]">
+				<span className="text-slate-500">Tool</span>
+				<span className="text-slate-300 font-mono">{data.toolName}</span>
+				{duration && (
+					<>
+						<span className="text-slate-500">Duration</span>
+						<span className="text-slate-300">{duration}</span>
+					</>
+				)}
+			</div>
+		</div>
+	)
+}
+
+function IdlePopover({ data }: { data: TimeSegment }) {
+	const formatDuration = (ms: number): string => {
+		const seconds = Math.floor(ms / 1000)
+		const minutes = Math.floor(seconds / 60)
+		const hours = Math.floor(minutes / 60)
+
+		if (hours > 0) return `${hours}h ${minutes % 60}m`
+		if (minutes > 0) return `${minutes}m ${seconds % 60}s`
+		return `${seconds}s`
+	}
+
+	return (
+		<div className="space-y-2">
+			<div className="flex items-center gap-2">
+				<span className="w-1.5 h-1.5 rounded-full bg-slate-400" />
+				<span className="font-medium text-slate-300">Idle Period</span>
+			</div>
+
+			<div className="grid grid-cols-[auto,1fr] gap-x-3 gap-y-1 text-[10px]">
+				<span className="text-slate-500">Duration</span>
+				<span className="text-slate-300">{formatDuration(data.actualDuration)}</span>
+				<span className="text-slate-500">From</span>
+				<span className="text-slate-300">{new Date(data.startTime).toLocaleTimeString()}</span>
+				<span className="text-slate-500">To</span>
+				<span className="text-slate-300">{new Date(data.endTime).toLocaleTimeString()}</span>
+			</div>
+		</div>
+	)
+}