@agent-relay/dashboard 2.0.80 → 2.0.82

package/src/lib/hierarchy.ts

@@ -0,0 +1,242 @@
+/**
+ * Agent Hierarchy Utilities
+ *
+ * Helpers for parsing, displaying, and organizing agents
+ * based on their hierarchical naming convention.
+ */
+
+import type { Agent } from '../types';
+import { getAgentPrefix, getAgentColor, type ColorScheme } from './colors';
+
+export interface HierarchyNode {
+  name: string;
+  level: number;
+  fullPath: string;
+  children: HierarchyNode[];
+  agent?: Agent;
+  color: ColorScheme;
+}
+
+export interface AgentGroup {
+  prefix: string;
+  displayName: string;
+  color: ColorScheme;
+  agents: Agent[];
+  isExpanded: boolean;
+}
+
+/**
+ * Build a tree structure from a list of agents
+ * e.g., ["backend-api", "backend-db", "frontend-ui"]
+ * becomes a tree with "backend" and "frontend" as roots
+ */
+export function buildAgentTree(agents: Agent[]): HierarchyNode[] {
+  const roots: Map<string, HierarchyNode> = new Map();
+
+  for (const agent of agents) {
+    const parts = agent.name.toLowerCase().split('-').filter(Boolean);
+    if (parts.length === 0) continue;
+
+    const prefix = parts[0];
+    const color = getAgentColor(agent.name);
+
+    // Get or create root node
+    let root = roots.get(prefix);
+    if (!root) {
+      root = {
+        name: prefix,
+        level: 0,
+        fullPath: prefix,
+        children: [],
+        color,
+      };
+      roots.set(prefix, root);
+    }
+
+    // For single-segment names, attach agent to root
+    if (parts.length === 1) {
+      root.agent = agent;
+      continue;
+    }
+
+    // Build path for multi-segment names
+    let current = root;
+    for (let i = 1; i < parts.length; i++) {
+      const part = parts[i];
+      const fullPath = parts.slice(0, i + 1).join('-');
+
+      let child = current.children.find((c) => c.name === part);
+      if (!child) {
+        child = {
+          name: part,
+          level: i,
+          fullPath,
+          children: [],
+          color,
+        };
+        current.children.push(child);
+      }
+
+      // Attach agent to leaf node
+      if (i === parts.length - 1) {
+        child.agent = agent;
+      }
+
+      current = child;
+    }
+  }
+
+  // Sort roots alphabetically
+  return Array.from(roots.values()).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+}
+
+/**
+ * Flatten a hierarchy tree for list display
+ * Returns nodes in depth-first order with indentation level
+ */
+export function flattenTree(
+  nodes: HierarchyNode[],
+  depth = 0
+): Array<{ node: HierarchyNode; depth: number }> {
+  const result: Array<{ node: HierarchyNode; depth: number }> = [];
+
+  for (const node of nodes) {
+    result.push({ node, depth });
+
+    if (node.children.length > 0) {
+      result.push(...flattenTree(node.children, depth + 1));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Group agents by their team (if set) or prefix for simpler grouped display.
+ * User-defined teams take priority over auto-extracted prefixes.
+ */
+export function groupAgents(agents: Agent[]): AgentGroup[] {
+  const groups: Map<string, AgentGroup> = new Map();
+
+  for (const agent of agents) {
+    // Use team if set, otherwise fall back to prefix from name
+    const groupKey = agent.team || getAgentPrefix(agent.name);
+    const color = getAgentColor(agent.name);
+
+    let group = groups.get(groupKey);
+    if (!group) {
+      group = {
+        prefix: groupKey,
+        displayName: capitalizeFirst(groupKey),
+        color,
+        agents: [],
+        isExpanded: true,
+      };
+      groups.set(groupKey, group);
+    }
+
+    group.agents.push(agent);
+  }
+
+  // Sort groups and agents within groups
+  const sortedGroups = Array.from(groups.values()).sort((a, b) =>
+    a.prefix.localeCompare(b.prefix)
+  );
+
+  for (const group of sortedGroups) {
+    group.agents.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  return sortedGroups;
+}
+
+/**
+ * Get display name for an agent (last segment, capitalized)
+ * e.g., "backend-api-auth" => "Auth"
+ */
+export function getAgentDisplayName(name: string): string {
+  const parts = name.split('-').filter(Boolean);
+  if (parts.length === 0) return name;
+
+  const lastPart = parts[parts.length - 1];
+  return capitalizeFirst(lastPart);
+}
+
+/**
+ * Get full display path for an agent
+ * e.g., "backend-api-auth" => "Backend > API > Auth"
+ */
+export function getAgentBreadcrumb(name: string): string {
+  const parts = name.split('-').filter(Boolean);
+  return parts.map(capitalizeFirst).join(' > ');
+}
+
+/**
+ * Check if an agent name matches a search query
+ * Matches against all hierarchy segments
+ */
+export function matchesSearch(agentName: string, query: string): boolean {
+  if (!query) return true;
+
+  const lowerQuery = query.toLowerCase();
+  const lowerName = agentName.toLowerCase();
+
+  // Direct match
+  if (lowerName.includes(lowerQuery)) return true;
+
+  // Match any segment
+  const parts = lowerName.split('-');
+  return parts.some((part) => part.includes(lowerQuery));
+}
+
+/**
+ * Filter agents by search query
+ */
+export function filterAgents(agents: Agent[], query: string): Agent[] {
+  if (!query) return agents;
+  return agents.filter((agent) => matchesSearch(agent.name, query));
+}
+
+/**
+ * Sort agents by their hierarchical name for consistent display
+ */
+export function sortAgentsByHierarchy(agents: Agent[]): Agent[] {
+  return [...agents].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Capitalize first letter of a string
+ */
+function capitalizeFirst(str: string): string {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Get statistics for a group of agents
+ */
+export function getGroupStats(agents: Agent[]): {
+  total: number;
+  online: number;
+  offline: number;
+  needsAttention: number;
+} {
+  let online = 0;
+  let offline = 0;
+  let needsAttention = 0;
+
+  for (const agent of agents) {
+    if (agent.status === 'online') online++;
+    else if (agent.status === 'offline') offline++;
+    if (agent.needsAttention) needsAttention++;
+  }
+
+  return {
+    total: agents.length,
+    online,
+    offline,
+    needsAttention,
+  };
+}

package/src/lib/stuckDetection.ts

@@ -0,0 +1,142 @@
+/**
+ * Stuck Agent Detection
+ *
+ * Detects when an agent has received a message but hasn't responded
+ * within a configurable threshold. This helps surface when agents
+ * are blocked or crashed mid-response.
+ */
+
+import type { Agent } from '../types';
+
+/** Default threshold in milliseconds (5 minutes) */
+export const DEFAULT_STUCK_THRESHOLD_MS = 5 * 60 * 1000;
+
+export interface StuckDetectionOptions {
+  /** Threshold in milliseconds before considering an agent stuck */
+  thresholdMs?: number;
+}
+
+/**
+ * Check if an agent is stuck (received message but no output within threshold)
+ *
+ * An agent is considered stuck when:
+ * 1. It has received a message (lastMessageReceivedAt is set)
+ * 2. It hasn't produced output since receiving that message
+ *    (lastOutputAt < lastMessageReceivedAt or lastOutputAt is not set)
+ * 3. The time since receiving the message exceeds the threshold
+ *
+ * @param agent - The agent to check
+ * @param options - Detection options
+ * @returns true if the agent is stuck
+ */
+export function isAgentStuck(
+  agent: Agent,
+  options: StuckDetectionOptions = {}
+): boolean {
+  const { thresholdMs = DEFAULT_STUCK_THRESHOLD_MS } = options;
+  const now = Date.now();
+
+  // No message received, can't be stuck waiting for response
+  if (!agent.lastMessageReceivedAt) {
+    return false;
+  }
+
+  // Agent has output after receiving the message - not stuck
+  if (agent.lastOutputAt && agent.lastOutputAt >= agent.lastMessageReceivedAt) {
+    return false;
+  }
+
+  // Check if threshold has been exceeded
+  const timeSinceMessage = now - agent.lastMessageReceivedAt;
+  return timeSinceMessage > thresholdMs;
+}
+
+/**
+ * Calculate how long an agent has been stuck (in milliseconds)
+ *
+ * @param agent - The agent to check
+ * @returns Time stuck in ms, or 0 if not stuck
+ */
+export function getStuckDuration(agent: Agent): number {
+  if (!agent.lastMessageReceivedAt) {
+    return 0;
+  }
+
+  // Has output after message - not stuck
+  if (agent.lastOutputAt && agent.lastOutputAt >= agent.lastMessageReceivedAt) {
+    return 0;
+  }
+
+  return Date.now() - agent.lastMessageReceivedAt;
+}
+
+/**
+ * Format stuck duration for display
+ *
+ * @param durationMs - Duration in milliseconds
+ * @returns Human-readable string like "5m" or "1h 30m"
+ */
+export function formatStuckDuration(durationMs: number): string {
+  if (durationMs < 60000) {
+    return '<1m';
+  }
+
+  const minutes = Math.floor(durationMs / 60000);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+
+  if (remainingMinutes === 0) {
+    return `${hours}h`;
+  }
+
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+/**
+ * Enrich agents with stuck detection status
+ *
+ * @param agents - Array of agents to process
+ * @param options - Detection options
+ * @returns Agents with isStuck field computed
+ */
+export function enrichAgentsWithStuckStatus(
+  agents: Agent[],
+  options: StuckDetectionOptions = {}
+): Agent[] {
+  return agents.map((agent) => ({
+    ...agent,
+    isStuck: isAgentStuck(agent, options),
+  }));
+}
+
+/**
+ * Get agents that are currently stuck
+ *
+ * @param agents - Array of agents to filter
+ * @param options - Detection options
+ * @returns Only the stuck agents
+ */
+export function getStuckAgents(
+  agents: Agent[],
+  options: StuckDetectionOptions = {}
+): Agent[] {
+  return agents.filter((agent) => isAgentStuck(agent, options));
+}
+
+/**
+ * Get stuck agent count
+ *
+ * @param agents - Array of agents to check
+ * @param options - Detection options
+ * @returns Number of stuck agents
+ */
+export function getStuckCount(
+  agents: Agent[],
+  options: StuckDetectionOptions = {}
+): number {
+  return agents.filter((agent) => isAgentStuck(agent, options)).length;
+}

package/src/lib/useUrlRouting.ts

@@ -0,0 +1,190 @@
+/**
+ * URL Routing Hook
+ *
+ * Manages URL state for deep linking to channels, DMs, and settings.
+ * Supports browser back/forward navigation.
+ */
+
+import { useEffect, useCallback, useRef } from 'react';
+
+export type RouteType = 'activity' | 'channel' | 'dm' | 'agent' | 'settings';
+
+export interface Route {
+  type: RouteType;
+  id?: string;
+  tab?: 'dashboard' | 'workspace' | 'team' | 'billing';
+}
+
+/**
+ * Parse the current URL path into a Route object
+ */
+export function parseRoute(pathname: string): Route {
+  // Remove leading slash and split
+  const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
+
+  if (parts.length === 0 || parts[0] === 'app') {
+    // Check for nested routes under /app
+    if (parts[0] === 'app' && parts.length > 1) {
+      return parseRoute('/' + parts.slice(1).join('/'));
+    }
+    return { type: 'activity' };
+  }
+
+  switch (parts[0]) {
+    case 'channel':
+      return { type: 'channel', id: parts[1] || undefined };
+    case 'dm':
+      return { type: 'dm', id: parts[1] || undefined };
+    case 'agent':
+      return { type: 'agent', id: parts[1] || undefined };
+    case 'settings':
+      const validTabs = ['dashboard', 'workspace', 'team', 'billing'];
+      const tab = parts[1] && validTabs.includes(parts[1])
+        ? parts[1] as Route['tab']
+        : 'dashboard';
+      return { type: 'settings', tab };
+    default:
+      return { type: 'activity' };
+  }
+}
+
+/**
+ * Build a URL path from a Route object
+ */
+export function buildPath(route: Route): string {
+  const base = '/app';
+
+  switch (route.type) {
+    case 'channel':
+      return route.id ? `${base}/channel/${encodeURIComponent(route.id)}` : base;
+    case 'dm':
+      return route.id ? `${base}/dm/${encodeURIComponent(route.id)}` : base;
+    case 'agent':
+      return route.id ? `${base}/agent/${encodeURIComponent(route.id)}` : base;
+    case 'settings':
+      return route.tab && route.tab !== 'dashboard'
+        ? `${base}/settings/${route.tab}`
+        : `${base}/settings`;
+    case 'activity':
+    default:
+      return base;
+  }
+}
+
+export interface UseUrlRoutingOptions {
+  onRouteChange: (route: Route) => void;
+}
+
+/**
+ * Hook for managing URL-based routing
+ */
+export function useUrlRouting({ onRouteChange }: UseUrlRoutingOptions) {
+  const isNavigatingRef = useRef(false);
+  const lastPathRef = useRef<string>('');
+
+  // Navigate to a new route
+  const navigate = useCallback((route: Route, replace = false) => {
+    if (typeof window === 'undefined') return;
+
+    const path = buildPath(route);
+
+    // Don't push if we're already at this path
+    if (path === window.location.pathname) return;
+
+    isNavigatingRef.current = true;
+    lastPathRef.current = path;
+
+    if (replace) {
+      window.history.replaceState({ route }, '', path);
+    } else {
+      window.history.pushState({ route }, '', path);
+    }
+
+    // Reset navigation flag after a tick
+    setTimeout(() => {
+      isNavigatingRef.current = false;
+    }, 0);
+  }, []);
+
+  // Navigate to channel
+  const navigateToChannel = useCallback((channelId: string) => {
+    navigate({ type: 'channel', id: channelId });
+  }, [navigate]);
+
+  // Navigate to DM
+  const navigateToDm = useCallback((username: string) => {
+    navigate({ type: 'dm', id: username });
+  }, [navigate]);
+
+  // Navigate to agent
+  const navigateToAgent = useCallback((agentName: string) => {
+    navigate({ type: 'agent', id: agentName });
+  }, [navigate]);
+
+  // Navigate to settings
+  const navigateToSettings = useCallback((tab?: Route['tab']) => {
+    navigate({ type: 'settings', tab });
+  }, [navigate]);
+
+  // Navigate to activity feed
+  const navigateToActivity = useCallback(() => {
+    navigate({ type: 'activity' });
+  }, [navigate]);
+
+  // Close settings (go back or to activity)
+  const closeSettings = useCallback(() => {
+    if (typeof window === 'undefined') return;
+
+    // If there's history, go back; otherwise go to activity
+    if (window.history.length > 1) {
+      window.history.back();
+    } else {
+      navigate({ type: 'activity' });
+    }
+  }, [navigate]);
+
+  // Handle popstate (browser back/forward)
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handlePopState = (event: PopStateEvent) => {
+      // Parse current URL
+      const route = parseRoute(window.location.pathname);
+      lastPathRef.current = window.location.pathname;
+      onRouteChange(route);
+    };
+
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, [onRouteChange]);
+
+  // Parse initial route on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const currentPath = window.location.pathname;
+
+    // Only process if path is different from last processed
+    if (currentPath !== lastPathRef.current) {
+      lastPathRef.current = currentPath;
+      const route = parseRoute(currentPath);
+
+      // Only trigger route change if we have a specific route
+      if (route.type !== 'activity' || currentPath.includes('/app')) {
+        onRouteChange(route);
+      }
+    }
+  }, [onRouteChange]);
+
+  return {
+    navigate,
+    navigateToChannel,
+    navigateToDm,
+    navigateToAgent,
+    navigateToSettings,
+    navigateToActivity,
+    closeSettings,
+    parseRoute,
+    buildPath,
+  };
+}