@shepai/cli 1.53.2 → 1.55.0

package/web/.next/standalone/src/presentation/web/components/features/control-center/use-control-center-state.ts

@@ -14,6 +14,11 @@ import { deleteFeature } from '@/app/actions/delete-feature';
 import { addRepository } from '@/app/actions/add-repository';
 import { deleteRepository } from '@/app/actions/delete-repository';
 import { useAgentEventsContext } from '@/hooks/agent-events-provider';
+import { useSound } from '@/hooks/use-sound';
+import {
+  mapEventTypeToState,
+  mapPhaseNameToLifecycle,
+} from '@/components/common/feature-node/derive-feature-state';
 
 export interface ControlCenterState {
   nodes: CanvasNodeType[];
@@ -41,6 +46,7 @@ export interface ControlCenterState {
     sourceNodeId: string | null,
     dataOverride?: Partial<FeatureNodeData>
   ) => string;
+  selectFeatureById: (featureId: string) => void;
 }
 
 let nextFeatureId = 0;
@@ -67,6 +73,9 @@ export function useControlCenterState(
   const [selectedNode, setSelectedNode] = useState<FeatureNodeData | null>(null);
   const [isCreateDrawerOpen, setIsCreateDrawerOpen] = useState(false);
   const [isDeleting, setIsDeleting] = useState(false);
+  const deleteSound = useSound('transition_down', { volume: 0.5 });
+  const createSound = useSound('transition_up', { volume: 0.5 });
+  const clickSound = useSound('tap_01', { volume: 0.3 });
   const [pendingRepoNodeId, setPendingRepoNodeId] = useState<string | null>(null);
 
   // Sync server props into local state when router.refresh() delivers new data
@@ -79,6 +88,19 @@ export function useControlCenterState(
     .sort()
     .join(',');
 
+  // Track previous feature states so we can detect transitions on server refresh
+  const prevFeatureStatesRef = useRef<Map<string, FeatureNodeData['state']>>(new Map());
+
+  // Stable key that changes when feature DATA changes (state/lifecycle), not just IDs.
+  const initialDataKey = initialNodes
+    .filter((n) => n.type === 'featureNode')
+    .map((n) => {
+      const d = n.data as FeatureNodeData;
+      return `${n.id}:${d.state}:${d.lifecycle}`;
+    })
+    .sort()
+    .join(',');
+
   // Sync server props into local state — keyed by derived strings (initialNodeKey/initialEdgeKey)
   // to avoid infinite re-renders from unstable array references.
   useEffect(() => {
@@ -119,35 +141,148 @@ export function useControlCenterState(
     setEdges(initialEdges);
   }, [initialEdgeKey, initialEdges, setEdges]);
 
-  // Refresh server data when SSE agent events arrive (status changes)
-  const { lastEvent } = useAgentEventsContext();
-  const processedEventRef = useRef<string | null>(null);
+  // Fallback notifications from server-refresh state transitions.
+  // Fires only when SSE didn't already deliver the matching event for a feature,
+  // e.g. when the SSE connection was down or the event was seeded into the cache.
+  const { events } = useAgentEventsContext();
 
   useEffect(() => {
-    if (!lastEvent) return;
-    const key = `${lastEvent.agentRunId}-${lastEvent.eventType}-${lastEvent.timestamp}`;
-    if (processedEventRef.current === key) return;
-    processedEventRef.current = key;
-    router.refresh();
-  }, [lastEvent, router]);
+    const prevStates = prevFeatureStatesRef.current;
 
-  const onNodesChange = useCallback((changes: NodeChange<CanvasNodeType>[]) => {
-    setNodes((ns) => applyNodeChanges(changes, ns));
-  }, []);
+    for (const node of initialNodes) {
+      if (node.type !== 'featureNode') continue;
+      const data = node.data as FeatureNodeData;
+      const prev = prevStates.get(node.id);
+
+      if (prev !== undefined && prev !== data.state) {
+        // Check if SSE already delivered a matching event for this feature
+        const sseAlreadyCovered = events.some(
+          (e) => e.featureId === data.featureId && mapEventTypeToState(e.eventType) === data.state
+        );
+
+        if (!sseAlreadyCovered) {
+          if (data.state === 'done') {
+            toast.success(data.name, { description: 'Feature completed!' });
+          } else if (data.state === 'action-required') {
+            toast.warning(data.name, {
+              description: 'Waiting for your approval',
+              action: {
+                label: 'Review',
+                onClick: () => {
+                  window.dispatchEvent(
+                    new CustomEvent('shep:select-feature', {
+                      detail: { featureId: data.featureId },
+                    })
+                  );
+                },
+              },
+            });
+          } else if (data.state === 'error') {
+            toast.error(data.name, { description: data.errorMessage ?? 'Agent failed' });
+          }
+        }
+      }
 
-  const clearSelection = useCallback(() => {
-    setSelectedNode(null);
+      prevStates.set(node.id, data.state);
+    }
+  }, [initialDataKey, initialNodes, events]);
+
+  // Targeted optimistic updates from SSE agent events + debounced reconciliation.
+  // Uses `events` array (not `lastEvent`) so that React batching cannot silently
+  // drop events when multiple SSE messages arrive in the same tick.
+  const processedEventCountRef = useRef(0);
+  const reconcileTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  useEffect(() => {
+    return () => clearTimeout(reconcileTimerRef.current);
   }, []);
 
-  const handleNodeClick = useCallback((_event: React.MouseEvent, node: CanvasNodeType) => {
-    if (node.type === 'featureNode') {
-      const data = node.data as FeatureNodeData;
-      if (data.state === 'creating') return;
-      setIsCreateDrawerOpen(false);
-      setSelectedNode(data);
+  useEffect(() => {
+    if (events.length <= processedEventCountRef.current) return;
+
+    const newEvents = events.slice(processedEventCountRef.current);
+    processedEventCountRef.current = events.length;
+
+    for (const event of newEvents) {
+      const newState = mapEventTypeToState(event.eventType);
+      const newLifecycle = mapPhaseNameToLifecycle(event.phaseName);
+
+      // Targeted node update — only clone the matched node
+      setNodes((prev) =>
+        prev.map((node) => {
+          if (node.type !== 'featureNode') return node;
+          const data = node.data as FeatureNodeData;
+          if (data.featureId !== event.featureId) return node;
+          return {
+            ...node,
+            data: {
+              ...data,
+              state: newState,
+              ...(newLifecycle !== undefined && { lifecycle: newLifecycle }),
+            },
+          };
+        })
+      );
+
+      // Update drawer if it's showing the matched feature
+      setSelectedNode((prev) => {
+        if (prev?.featureId !== event.featureId) return prev;
+        return {
+          ...prev,
+          state: newState,
+          ...(newLifecycle !== undefined && { lifecycle: newLifecycle }),
+        };
+      });
     }
+
+    // Debounced background reconciliation (3s after last SSE event)
+    clearTimeout(reconcileTimerRef.current);
+    reconcileTimerRef.current = setTimeout(() => router.refresh(), 3000);
+  }, [events, router]);
+
+  // Periodic polling fallback: refresh server data every 5s when any feature
+  // is in an active state (running/action-required). This ensures the UI stays
+  // current even if the SSE connection drops — belt-and-suspenders alongside SSE.
+  useEffect(() => {
+    const hasActiveFeature = nodes.some((n) => {
+      if (n.type !== 'featureNode') return false;
+      const data = n.data as FeatureNodeData;
+      return (
+        data.state === 'running' || data.state === 'action-required' || data.state === 'creating'
+      );
+    });
+
+    if (!hasActiveFeature) return;
+
+    const interval = setInterval(() => router.refresh(), 5_000);
+    return () => clearInterval(interval);
+  }, [nodes, router]);
+
+  const onNodesChange = useCallback((changes: NodeChange<CanvasNodeType>[]) => {
+    setNodes((ns) => applyNodeChanges(changes, ns));
   }, []);
 
+  const closeSound = useSound('transition_down', { volume: 0.01 });
+  const clearSelection = useCallback(() => {
+    setSelectedNode((prev) => {
+      if (prev) closeSound.play();
+      return null;
+    });
+  }, [closeSound]);
+
+  const handleNodeClick = useCallback(
+    (_event: React.MouseEvent, node: CanvasNodeType) => {
+      if (node.type === 'featureNode') {
+        const data = node.data as FeatureNodeData;
+        if (data.state === 'creating') return;
+        clickSound.play();
+        setIsCreateDrawerOpen(false);
+        setSelectedNode(data);
+      }
+    },
+    [clickSound]
+  );
+
   // Keyboard shortcut: Escape to deselect
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
@@ -319,9 +454,10 @@ export function useControlCenterState(
   );
 
   const handleAddFeature = useCallback(() => {
+    clickSound.play();
     setSelectedNode(null);
     setIsCreateDrawerOpen(true);
-  }, []);
+  }, [clickSound]);
 
   const [pendingParentFeatureId, setPendingParentFeatureId] = useState<string | undefined>();
 
@@ -359,6 +495,7 @@ export function useControlCenterState(
             return;
           }
 
+          createSound.play();
           router.refresh();
         })
         .catch(() => {
@@ -368,13 +505,14 @@ export function useControlCenterState(
           toast.error('Failed to create feature');
         });
     },
-    [router, createFeatureNode, pendingRepoNodeId, pendingParentFeatureId, setEdges]
+    [router, createFeatureNode, pendingRepoNodeId, createSound, pendingParentFeatureId, setEdges]
   );
 
   const closeCreateDrawer = useCallback(() => {
+    closeSound.play();
     setIsCreateDrawerOpen(false);
     setPendingParentFeatureId(undefined);
-  }, []);
+  }, [closeSound]);
 
   const handleDeleteFeature = useCallback(
     async (featureId: string) => {
@@ -401,6 +539,7 @@ export function useControlCenterState(
           setEdges(result.edges);
           return result.nodes;
         });
+        deleteSound.play();
         toast.success('Feature deleted successfully');
         router.refresh();
       } catch {
@@ -409,7 +548,7 @@ export function useControlCenterState(
         setIsDeleting(false);
       }
     },
-    [router, edges, setEdges]
+    [router, edges, deleteSound, setEdges]
   );
 
   const handleDeleteRepository = useCallback(
@@ -429,6 +568,7 @@ export function useControlCenterState(
           return;
         }
 
+        deleteSound.play();
         toast.success('Repository removed');
         router.refresh();
       } catch {
@@ -436,14 +576,18 @@ export function useControlCenterState(
         router.refresh();
       }
     },
-    [router, setEdges]
+    [router, deleteSound, setEdges]
   );
 
-  const handleAddFeatureToRepo = useCallback((repoNodeId: string) => {
-    setSelectedNode(null);
-    setPendingRepoNodeId(repoNodeId);
-    setIsCreateDrawerOpen(true);
-  }, []);
+  const handleAddFeatureToRepo = useCallback(
+    (repoNodeId: string) => {
+      clickSound.play();
+      setSelectedNode(null);
+      setPendingRepoNodeId(repoNodeId);
+      setIsCreateDrawerOpen(true);
+    },
+    [clickSound]
+  );
 
   const handleAddFeatureToFeature = useCallback(
     (featureNodeId: string) => {
@@ -565,6 +709,7 @@ export function useControlCenterState(
             }))
           );
 
+          createSound.play();
           router.refresh();
         })
         .catch(() => {
@@ -581,9 +726,26 @@ export function useControlCenterState(
           toast.error('Failed to add repository');
         });
     },
-    [router, setEdges]
+    [router, createSound, setEdges]
   );
 
+  // Ref keeps latest nodes so selectFeatureById has a stable identity
+  const nodesRef = useRef(nodes);
+  nodesRef.current = nodes;
+
+  const selectFeatureById = useCallback((featureId: string) => {
+    const node = nodesRef.current.find(
+      (n) => n.type === 'featureNode' && (n.data as FeatureNodeData).featureId === featureId
+    );
+    if (node) {
+      const data = node.data as FeatureNodeData;
+      if (data.state !== 'creating') {
+        setIsCreateDrawerOpen(false);
+        setSelectedNode(data);
+      }
+    }
+  }, []);
+
   const pendingNode = pendingRepoNodeId ? nodes.find((n) => n.id === pendingRepoNodeId) : null;
   const pendingRepositoryPath =
     (pendingNode?.data as { repositoryPath?: string } | undefined)?.repositoryPath ?? '';
@@ -610,5 +772,6 @@ export function useControlCenterState(
     handleDeleteRepository,
     isDeleting,
     createFeatureNode,
+    selectFeatureById,
   };
 }

package/web/.next/standalone/src/presentation/web/components/layouts/app-shell/app-shell.tsx

@@ -4,6 +4,7 @@ import { useCallback, type ReactNode } from 'react';
 import { SidebarProvider, SidebarInset } from '@/components/ui/sidebar';
 import { AppSidebar } from '@/components/layouts/app-sidebar';
 import { ThemeToggle } from '@/components/common/theme-toggle';
+import { SoundToggle } from '@/components/common/sound-toggle';
 import { AgentEventsProvider } from '@/hooks/agent-events-provider';
 import { useNotifications } from '@/hooks/use-notifications';
 
@@ -25,7 +26,8 @@ function AppShellInner({ children }: AppShellProps) {
       <AppSidebar features={[]} onNewFeature={handleNewFeature} />
       <SidebarInset>
         <div className="relative h-full">
-          <div className="absolute top-3 right-3 z-50">
+          <div className="absolute top-3 right-3 z-50 flex gap-1">
+            <SoundToggle />
             <ThemeToggle />
           </div>
           <main className="h-full">{children}</main>

package/web/.next/standalone/src/presentation/web/dev-server.ts

@@ -20,6 +20,14 @@ import path from 'node:path';
 import { initializeContainer, container } from '@/infrastructure/di/container.js';
 import { InitializeSettingsUseCase } from '@/application/use-cases/settings/initialize-settings.use-case.js';
 import { initializeSettings } from '@/infrastructure/services/settings.service.js';
+import type { IAgentRunRepository } from '@/application/ports/output/agents/agent-run-repository.interface.js';
+import type { IPhaseTimingRepository } from '@/application/ports/output/agents/phase-timing-repository.interface.js';
+import type { IFeatureRepository } from '@/application/ports/output/repositories/feature-repository.interface.js';
+import type { INotificationService } from '@/application/ports/output/services/notification-service.interface.js';
+import {
+  initializeNotificationWatcher,
+  getNotificationWatcher,
+} from '@/infrastructure/services/notifications/notification-watcher.service.js';
 
 const DEFAULT_PORT = 3000;
 
@@ -62,6 +70,14 @@ async function main() {
     const initSettingsUseCase = container.resolve(InitializeSettingsUseCase);
     const settings = await initSettingsUseCase.execute();
     initializeSettings(settings);
+
+    // Start notification watcher for real-time SSE events (same as shep ui)
+    const runRepo = container.resolve<IAgentRunRepository>('IAgentRunRepository');
+    const phaseTimingRepo = container.resolve<IPhaseTimingRepository>('IPhaseTimingRepository');
+    const featureRepo = container.resolve<IFeatureRepository>('IFeatureRepository');
+    const notificationService = container.resolve<INotificationService>('INotificationService');
+    initializeNotificationWatcher(runRepo, phaseTimingRepo, featureRepo, notificationService);
+    getNotificationWatcher().start();
   } catch (error) {
     console.warn('[dev-server] DI initialization failed — features will be empty:', error);
   }
@@ -104,6 +120,11 @@ async function main() {
     console.log('\n[dev-server] Shutting down...');
     const forceExit = setTimeout(() => process.exit(0), 2000);
     try {
+      try {
+        getNotificationWatcher().stop();
+      } catch {
+        /* not initialized */
+      }
       server.closeAllConnections();
       await Promise.all([
         new Promise<void>((resolve) => server.close(() => resolve())),

package/web/.next/standalone/src/presentation/web/hooks/use-agent-events.ts

@@ -15,66 +15,178 @@ export interface UseAgentEventsResult {
   connectionStatus: ConnectionStatus;
 }
 
-const BASE_BACKOFF_MS = 1000;
-const MAX_BACKOFF_MS = 30_000;
-/** Only reset backoff after connection is stable for this long */
-const STABLE_CONNECTION_MS = 5_000;
-
+const SW_PATH = '/agent-events-sw.js';
+
+/**
+ * Hook that receives real-time agent notification events via a Service Worker.
+ *
+ * The SW maintains a single SSE connection to /api/agent-events and
+ * broadcasts events to all open tabs. Falls back to direct EventSource
+ * when Service Workers are unavailable.
+ */
 export function useAgentEvents(options?: UseAgentEventsOptions): UseAgentEventsResult {
   const [events, setEvents] = useState<NotificationEvent[]>([]);
   const [lastEvent, setLastEvent] = useState<NotificationEvent | null>(null);
   const [connectionStatus, setConnectionStatus] = useState<ConnectionStatus>('disconnected');
 
-  const backoffRef = useRef(BASE_BACKOFF_MS);
-  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const stableTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const esRef = useRef<EventSource | null>(null);
-
   const runId = options?.runId;
+  const swRef = useRef<ServiceWorker | null>(null);
+
+  const onMessage = useCallback((event: MessageEvent) => {
+    const msg = event.data;
+    if (!msg || typeof msg !== 'object') return;
+
+    if (msg.type === 'notification') {
+      const parsed = msg.data as NotificationEvent;
+      setEvents((prev) => [...prev, parsed]);
+      setLastEvent(parsed);
+    } else if (msg.type === 'status') {
+      setConnectionStatus(msg.status as ConnectionStatus);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    // ?sse=direct bypasses the Service Worker for debugging
+    const bypassSW =
+      typeof location !== 'undefined' && new URLSearchParams(location.search).has('sse');
+
+    // Fallback: direct EventSource when SW not supported or bypassed
+    if (!navigator.serviceWorker || bypassSW) {
+      return connectDirectEventSource(runId, setEvents, setLastEvent, setConnectionStatus);
+    }
+
+    let cancelled = false;
+    const fallbackCleanupRef = { current: undefined as (() => void) | undefined };
 
-  const connect = useCallback(() => {
-    if (typeof window === 'undefined' || typeof EventSource === 'undefined') {
-      return;
+    function subscribeToWorker(worker: ServiceWorker) {
+      if (cancelled) return;
+      swRef.current = worker;
+      worker.postMessage({ type: 'subscribe', runId });
+      setConnectionStatus('connecting');
     }
 
-    // Prevent duplicate connections
-    if (esRef.current) {
-      return;
+    // Listen for messages from whatever SW controls this page
+    navigator.serviceWorker.addEventListener('message', onMessage);
+
+    // Re-subscribe when SW controller changes (e.g., after SW update via skipWaiting)
+    function handleControllerChange() {
+      if (cancelled) return;
+      const newController = navigator.serviceWorker.controller;
+      if (newController) {
+        swRef.current = newController;
+        newController.postMessage({ type: 'subscribe', runId });
+        setConnectionStatus('connecting');
+      }
     }
+    navigator.serviceWorker.addEventListener('controllerchange', handleControllerChange);
+
+    navigator.serviceWorker
+      .register(SW_PATH, { scope: '/' })
+      .then((registration) => {
+        if (cancelled) return;
+
+        // Use the active worker, or wait for it to activate
+        const sw = registration.active ?? registration.installing ?? registration.waiting;
+        if (!sw) {
+          // No worker at all — fall back to direct EventSource
+          fallbackCleanupRef.current = connectDirectEventSource(
+            runId,
+            setEvents,
+            setLastEvent,
+            setConnectionStatus
+          );
+          return;
+        }
+
+        if (sw.state === 'activated') {
+          subscribeToWorker(sw);
+        } else {
+          sw.addEventListener('statechange', () => {
+            if (sw.state === 'activated') subscribeToWorker(sw);
+          });
+        }
+      })
+      .catch(() => {
+        // SW registration failed — fall back to direct EventSource
+        if (!cancelled) {
+          fallbackCleanupRef.current = connectDirectEventSource(
+            runId,
+            setEvents,
+            setLastEvent,
+            setConnectionStatus
+          );
+        }
+      });
+
+    return () => {
+      cancelled = true;
+      navigator.serviceWorker.removeEventListener('message', onMessage);
+      navigator.serviceWorker.removeEventListener('controllerchange', handleControllerChange);
+      swRef.current?.postMessage({ type: 'unsubscribe' });
+      swRef.current = null;
+      fallbackCleanupRef.current?.();
+    };
+  }, [runId, onMessage]);
+
+  return { events, lastEvent, connectionStatus };
+}
+
+// --- EventSource fallback (identical to the previous implementation) ---
+
+const BASE_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+const STABLE_CONNECTION_MS = 5_000;
+
+function connectDirectEventSource(
+  runId: string | undefined,
+  setEvents: React.Dispatch<React.SetStateAction<NotificationEvent[]>>,
+  setLastEvent: React.Dispatch<React.SetStateAction<NotificationEvent | null>>,
+  setConnectionStatus: React.Dispatch<React.SetStateAction<ConnectionStatus>>
+): () => void {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  if (typeof EventSource === 'undefined') return () => {};
+
+  let es: EventSource | null = null;
+  let stopped = false;
+  let backoff = BASE_BACKOFF_MS;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stableTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function connect() {
+    if (stopped) return;
 
     const url = runId
       ? `/api/agent-events?runId=${encodeURIComponent(runId)}`
       : '/api/agent-events';
 
-    const es = new EventSource(url);
-    esRef.current = es;
+    es = new EventSource(url);
     setConnectionStatus('connecting');
 
     es.onopen = () => {
       setConnectionStatus('connected');
-      // Only reset backoff after connection stays open for a while
-      stableTimerRef.current = setTimeout(() => {
-        stableTimerRef.current = null;
-        backoffRef.current = BASE_BACKOFF_MS;
+      stableTimer = setTimeout(() => {
+        stableTimer = null;
+        backoff = BASE_BACKOFF_MS;
       }, STABLE_CONNECTION_MS);
     };
 
     es.onerror = () => {
-      es.close();
-      esRef.current = null;
+      es?.close();
+      es = null;
       setConnectionStatus('disconnected');
 
-      // Cancel stable timer — connection wasn't stable
-      if (stableTimerRef.current !== null) {
-        clearTimeout(stableTimerRef.current);
-        stableTimerRef.current = null;
+      if (stableTimer !== null) {
+        clearTimeout(stableTimer);
+        stableTimer = null;
       }
 
-      const delay = backoffRef.current;
-      backoffRef.current = Math.min(delay * 2, MAX_BACKOFF_MS);
+      const delay = backoff;
+      backoff = Math.min(delay * 2, MAX_BACKOFF_MS);
 
-      reconnectTimerRef.current = setTimeout(() => {
-        reconnectTimerRef.current = null;
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
         connect();
       }, delay);
     };
@@ -84,26 +196,23 @@ export function useAgentEvents(options?: UseAgentEventsOptions): UseAgentEventsR
       setEvents((prev) => [...prev, parsed]);
       setLastEvent(parsed);
     }) as EventListener);
-  }, [runId]);
-
-  useEffect(() => {
-    connect();
+  }
 
-    return () => {
-      if (reconnectTimerRef.current !== null) {
-        clearTimeout(reconnectTimerRef.current);
-        reconnectTimerRef.current = null;
-      }
-      if (stableTimerRef.current !== null) {
-        clearTimeout(stableTimerRef.current);
-        stableTimerRef.current = null;
-      }
-      if (esRef.current) {
-        esRef.current.close();
-        esRef.current = null;
-      }
-    };
-  }, [connect]);
+  connect();
 
-  return { events, lastEvent, connectionStatus };
+  return () => {
+    stopped = true;
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (stableTimer !== null) {
+      clearTimeout(stableTimer);
+      stableTimer = null;
+    }
+    if (es) {
+      es.close();
+      es = null;
+    }
+  };
 }