@shepai/cli 1.53.1 → 1.54.0

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;
+    }
+  };
 }

package/web/.next/standalone/src/presentation/web/hooks/use-notifications.stories.tsx

@@ -1,12 +1,20 @@
-import { useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { toast } from 'sonner';
 import { Toaster } from '@/components/ui/sonner';
 import { Button } from '@/components/ui/button';
+import { useSound } from './use-sound';
 
 /** Mirrors NotificationSeverity enum values (inlined to avoid @shepai/core import in Storybook). */
 type Severity = 'info' | 'warning' | 'success' | 'error';
 
+const SEVERITY_SOUNDS: Record<Severity, string> = {
+  success: 'celebration',
+  error: 'caution',
+  warning: 'notification',
+  info: 'button',
+};
+
 interface DemoEvent {
   eventType: string;
   severity: Severity;
@@ -15,16 +23,37 @@ interface DemoEvent {
   phaseName?: string;
 }
 
-function simulateNotification(event: DemoEvent): void {
-  const method: 'success' | 'error' | 'warning' | 'info' = event.severity ?? 'info';
-  toast[method](event.featureName, { description: event.message });
+function NotificationDemo() {
+  const successSound = useSound('celebration', { volume: 0.5 });
+  const errorSound = useSound('caution', { volume: 0.5 });
+  const warningSound = useSound('notification', { volume: 0.5 });
+  const infoSound = useSound('button', { volume: 0.5 });
 
-  if (globalThis.Notification?.permission === 'granted') {
-    new Notification(event.featureName, { body: event.message });
-  }
-}
+  const soundsByName = useMemo<Record<string, { play: () => void }>>(
+    () => ({
+      celebration: successSound,
+      caution: errorSound,
+      notification: warningSound,
+      button: infoSound,
+    }),
+    [successSound, errorSound, warningSound, infoSound]
+  );
+
+  const simulateNotification = useCallback(
+    (event: DemoEvent) => {
+      const method = event.severity ?? 'info';
+      toast[method](event.featureName, { description: event.message });
+
+      if (globalThis.Notification?.permission === 'granted') {
+        new Notification(event.featureName, { body: event.message });
+      }
+
+      const soundName = SEVERITY_SOUNDS[event.severity];
+      soundsByName[soundName]?.play();
+    },
+    [soundsByName]
+  );
 
-function NotificationDemo() {
   const [browserPermission, setBrowserPermission] = useState<NotificationPermission>(
     typeof globalThis.Notification !== 'undefined' ? globalThis.Notification.permission : 'default'
   );
@@ -52,7 +81,7 @@ function NotificationDemo() {
       <div className="flex flex-col gap-2">
         <h3 className="text-sm font-semibold">Simulate Notification Events</h3>
         <p className="text-muted-foreground text-xs">
-          Click a button to fire a toast and browser notification.
+          Click a button to fire a toast, browser notification, and sound.
         </p>
         <div className="flex flex-wrap gap-2">
           <Button

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

@@ -1,10 +1,11 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { toast } from 'sonner';
 import type { NotificationEvent } from '@shepai/core/domain/generated/output';
-import { NotificationSeverity } from '@shepai/core/domain/generated/output';
+import { NotificationEventType, NotificationSeverity } from '@shepai/core/domain/generated/output';
 import { useAgentEventsContext } from './agent-events-provider';
+import { useSound } from './use-sound';
 
 export interface UseNotificationsResult {
   requestBrowserPermission: () => Promise<void>;
@@ -20,18 +21,56 @@ const SEVERITY_TO_TOAST: Record<NotificationSeverity, 'success' | 'error' | 'war
 
 function dispatchToast(event: NotificationEvent): void {
   const method = SEVERITY_TO_TOAST[event.severity] ?? 'info';
-  toast[method](event.featureName, { description: event.message });
+  const isActionable = event.eventType === NotificationEventType.WaitingApproval;
+  toast[method](event.featureName, {
+    description: event.message,
+    ...(isActionable && {
+      action: {
+        label: 'Review',
+        onClick: () => {
+          window.dispatchEvent(
+            new CustomEvent('shep:select-feature', { detail: { featureId: event.featureId } })
+          );
+        },
+      },
+    }),
+  });
 }
 
 function dispatchBrowserNotification(event: NotificationEvent): void {
   if (globalThis.Notification?.permission !== 'granted') {
     return;
   }
-  new Notification(event.featureName, { body: event.message });
+  new Notification(`Shep: ${event.featureName}`, {
+    body: event.message,
+    icon: '/favicon-light.svg',
+  });
 }
 
+const SEVERITY_TO_SOUND = {
+  [NotificationSeverity.Success]: 'celebration',
+  [NotificationSeverity.Error]: 'caution',
+  [NotificationSeverity.Warning]: 'notification',
+  [NotificationSeverity.Info]: 'button',
+} as const;
+
 export function useNotifications(): UseNotificationsResult {
-  const { lastEvent } = useAgentEventsContext();
+  const { events } = useAgentEventsContext();
+
+  const successSound = useSound('celebration', { volume: 0.5 });
+  const errorSound = useSound('caution', { volume: 0.5 });
+  const warningSound = useSound('notification', { volume: 0.5 });
+  const infoSound = useSound('button', { volume: 0.5 });
+
+  const soundsByName = useMemo<Record<string, { play: () => void }>>(
+    () => ({
+      celebration: successSound,
+      caution: errorSound,
+      notification: warningSound,
+      button: infoSound,
+    }),
+    [successSound, errorSound, warningSound, infoSound]
+  );
 
   const [browserPermissionState, setBrowserPermissionState] = useState<NotificationPermission>(
     () => {
@@ -40,20 +79,34 @@ export function useNotifications(): UseNotificationsResult {
     }
   );
 
-  // Track which events we've already dispatched to avoid re-dispatching on re-render
-  const processedRef = useRef<Set<string>>(new Set());
+  // Track how many events from the array we've already processed.
+  // Using the array index (instead of lastEvent) prevents React batching
+  // from silently dropping events when multiple SSE messages arrive together.
+  const processedCountRef = useRef(0);
 
   useEffect(() => {
-    if (!lastEvent) return;
+    if (events.length <= processedCountRef.current) return;
 
-    // Create a key for deduplication
-    const key = `${lastEvent.agentRunId}-${lastEvent.eventType}-${lastEvent.timestamp}`;
-    if (processedRef.current.has(key)) return;
-    processedRef.current.add(key);
+    const newEvents = events.slice(processedCountRef.current);
+    processedCountRef.current = events.length;
 
-    dispatchToast(lastEvent);
-    dispatchBrowserNotification(lastEvent);
-  }, [lastEvent]);
+    for (const event of newEvents) {
+      // Only notify for actionable events and completion celebrations
+      if (
+        event.severity !== NotificationSeverity.Error &&
+        event.severity !== NotificationSeverity.Warning &&
+        event.severity !== NotificationSeverity.Success
+      ) {
+        continue;
+      }
+
+      dispatchToast(event);
+      dispatchBrowserNotification(event);
+
+      const soundName = SEVERITY_TO_SOUND[event.severity];
+      soundsByName[soundName]?.play();
+    }
+  }, [events, soundsByName]);
 
   const requestBrowserPermission = useCallback(async () => {
     if (typeof globalThis.Notification === 'undefined') return;

package/web/.next/standalone/src/presentation/web/hooks/use-sound-enabled.ts

@@ -0,0 +1,38 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+const STORAGE_KEY = 'shep-sound-enabled';
+const SYNC_EVENT = 'shep:sound-toggle';
+
+export interface UseSoundEnabledResult {
+  enabled: boolean;
+  toggle: () => void;
+}
+
+export function useSoundEnabled(): UseSoundEnabledResult {
+  const [enabled, setEnabled] = useState(true);
+
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'false') setEnabled(false);
+
+    // Sync across all useSoundEnabled instances in the same tab
+    const onSync = (e: Event) => {
+      setEnabled((e as CustomEvent<boolean>).detail);
+    };
+    window.addEventListener(SYNC_EVENT, onSync);
+    return () => window.removeEventListener(SYNC_EVENT, onSync);
+  }, []);
+
+  const toggle = useCallback(() => {
+    setEnabled((prev) => {
+      const next = !prev;
+      localStorage.setItem(STORAGE_KEY, String(next));
+      window.dispatchEvent(new CustomEvent(SYNC_EVENT, { detail: next }));
+      return next;
+    });
+  }, []);
+
+  return { enabled, toggle };
+}

package/web/.next/standalone/src/presentation/web/hooks/use-sound.stories.tsx

@@ -0,0 +1,109 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from '@/components/ui/button';
+import { useSound, SOUND_NAMES, type SoundName } from './use-sound';
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+
+const CATEGORIES: Record<string, SoundName[]> = {
+  'UI Actions': ['button', 'select', 'disabled'],
+  Toggles: ['toggle_on', 'toggle_off'],
+  Transitions: ['transition_up', 'transition_down'],
+  Alerts: ['notification', 'caution', 'celebration'],
+  Swipes: ['swipe', 'swipe_01', 'swipe_02', 'swipe_03', 'swipe_04', 'swipe_05'],
+  Taps: ['tap_01', 'tap_02', 'tap_03', 'tap_04', 'tap_05'],
+  Typing: ['type_01', 'type_02', 'type_03', 'type_04', 'type_05'],
+  Loops: ['progress_loop', 'ringtone_loop'],
+};
+
+/* ------------------------------------------------------------------ */
+/*  Single sound player (used per button)                             */
+/* ------------------------------------------------------------------ */
+
+function SoundButton({ name, volume }: { name: SoundName; volume: number }) {
+  const isLoop = name.includes('loop');
+  const { play, stop } = useSound(name, { volume, loop: isLoop });
+  const [playing, setPlaying] = useState(false);
+
+  const handleClick = () => {
+    if (isLoop && playing) {
+      stop();
+      setPlaying(false);
+    } else {
+      play();
+      setPlaying(true);
+      if (!isLoop) {
+        setTimeout(() => setPlaying(false), 2000);
+      }
+    }
+  };
+
+  return (
+    <Button
+      size="sm"
+      variant={playing ? 'default' : 'outline'}
+      onClick={handleClick}
+      className="min-w-[120px] font-mono text-xs"
+    >
+      {isLoop && playing ? `Stop ${name}` : name}
+    </Button>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Full catalog demo                                                 */
+/* ------------------------------------------------------------------ */
+
+function SoundCatalog({ volume }: { volume: number }) {
+  return (
+    <div className="flex w-[560px] flex-col gap-6">
+      <div className="flex flex-col gap-1">
+        <h2 className="text-base font-semibold">Sound Library</h2>
+        <p className="text-muted-foreground text-sm">
+          {SOUND_NAMES.length} sounds available at{' '}
+          <code className="bg-muted rounded px-1 py-0.5 text-xs">/sounds/*.wav</code>
+        </p>
+      </div>
+
+      {Object.entries(CATEGORIES).map(([category, sounds]) => (
+        <div key={category} className="flex flex-col gap-2">
+          <h3 className="text-sm font-semibold">{category}</h3>
+          <div className="flex flex-wrap gap-2">
+            {sounds.map((name) => (
+              <SoundButton key={name} name={name} volume={volume} />
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Storybook meta                                                    */
+/* ------------------------------------------------------------------ */
+
+const meta: Meta = {
+  title: 'Hooks/useSound',
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  argTypes: {
+    volume: {
+      control: { type: 'range', min: 0, max: 1, step: 0.1 },
+      description: 'Playback volume (0 to 1)',
+      defaultValue: 0.5,
+    },
+  },
+  args: {
+    volume: 0.5,
+  },
+};
+
+export default meta;
+type Story = StoryObj<{ volume: number }>;
+
+export const Catalog: Story = {
+  render: ({ volume }) => <SoundCatalog volume={volume} />,
+};