@shepai/cli 1.53.2 → 1.54.0

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

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

@@ -0,0 +1,101 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import { useSoundEnabled } from './use-sound-enabled';
+
+const SOUND_NAMES = [
+  'button',
+  'caution',
+  'celebration',
+  'disabled',
+  'notification',
+  'progress_loop',
+  'ringtone_loop',
+  'select',
+  'swipe',
+  'swipe_01',
+  'swipe_02',
+  'swipe_03',
+  'swipe_04',
+  'swipe_05',
+  'tap_01',
+  'tap_02',
+  'tap_03',
+  'tap_04',
+  'tap_05',
+  'toggle_off',
+  'toggle_on',
+  'transition_down',
+  'transition_up',
+  'type_01',
+  'type_02',
+  'type_03',
+  'type_04',
+  'type_05',
+] as const;
+
+export type SoundName = (typeof SOUND_NAMES)[number];
+
+export interface UseSoundOptions {
+  volume?: number;
+  loop?: boolean;
+}
+
+export interface UseSoundResult {
+  play: () => void;
+  stop: () => void;
+  isPlaying: boolean;
+}
+
+export function useSound(name: SoundName, options: UseSoundOptions = {}): UseSoundResult {
+  const { volume = 1, loop = false } = options;
+  const { enabled } = useSoundEnabled();
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const isPlayingRef = useRef(false);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const audio = new Audio(`/sounds/${name}.wav`);
+    audio.preload = 'auto';
+    audio.loop = loop;
+    audio.volume = Math.max(0, Math.min(1, volume));
+    audio.addEventListener('ended', () => {
+      isPlayingRef.current = false;
+    });
+    audioRef.current = audio;
+
+    return () => {
+      audio.pause();
+      audio.removeAttribute('src');
+      audioRef.current = null;
+      isPlayingRef.current = false;
+    };
+  }, [name, loop, volume]);
+
+  const play = useCallback(() => {
+    if (!enabled) return;
+    const audio = audioRef.current;
+    if (!audio) return;
+    audio.currentTime = 0;
+    audio.play()?.catch((err) => {
+      if (process.env.NODE_ENV === 'development') {
+        // eslint-disable-next-line no-console
+        console.warn(`[useSound] play("${name}") blocked:`, err.message);
+      }
+    });
+    isPlayingRef.current = true;
+  }, [enabled, name]);
+
+  const stop = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    audio.pause();
+    audio.currentTime = 0;
+    isPlayingRef.current = false;
+  }, []);
+
+  return { play, stop, isPlaying: isPlayingRef.current };
+}
+
+/** All available sound names for enumeration (e.g. in Storybook). */
+export { SOUND_NAMES };

package/web/.next/standalone/src/presentation/web/public/agent-events-sw.js

@@ -0,0 +1,164 @@
+/**
+ * Service Worker: agent-events-sw.js
+ *
+ * Maintains a single SSE connection to /api/agent-events and broadcasts
+ * NotificationEvent deltas to all connected tabs via postMessage.
+ *
+ * Messages FROM clients:
+ *   { type: 'subscribe', runId?: string }  — register this tab
+ *   { type: 'unsubscribe' }                — unregister this tab
+ *
+ * Messages TO clients:
+ *   { type: 'notification', data: NotificationEvent }
+ *   { type: 'status', status: 'connected' | 'connecting' | 'disconnected' }
+ */
+
+/* global self, EventSource, setTimeout, clearTimeout */
+
+const BASE_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+const STABLE_CONNECTION_MS = 5_000;
+
+/** @type {EventSource | null} */
+let eventSource = null;
+/** @type {string | undefined} */
+let currentRunId;
+let backoff = BASE_BACKOFF_MS;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let reconnectTimer = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let stableTimer = null;
+/** @type {'connected' | 'connecting' | 'disconnected'} */
+let connectionStatus = 'disconnected';
+let subscriberCount = 0;
+
+// --- Lifecycle ---
+
+self.addEventListener('install', () => {
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    self.clients.claim().then(async () => {
+      // After claiming clients, check if there are open tabs that need a connection.
+      // This handles the case where the SW updated via skipWaiting() and the old
+      // SW's EventSource was closed — we auto-start for existing clients.
+      const clients = await self.clients.matchAll({ type: 'window' });
+      if (clients.length > 0 && subscriberCount === 0) {
+        subscriberCount = clients.length;
+        connect();
+      }
+    })
+  );
+});
+
+// --- Client messaging ---
+
+self.addEventListener('message', (event) => {
+  const { type, runId } = event.data ?? {};
+
+  if (type === 'subscribe') {
+    subscriberCount++;
+    currentRunId = runId;
+
+    // Send current status to the new subscriber immediately
+    event.source?.postMessage({ type: 'status', status: connectionStatus });
+
+    // Start connection if this is the first subscriber
+    if (subscriberCount === 1) {
+      connect();
+    }
+  } else if (type === 'unsubscribe') {
+    subscriberCount = Math.max(0, subscriberCount - 1);
+
+    // Close connection when no subscribers remain
+    if (subscriberCount === 0) {
+      disconnect();
+    }
+  }
+});
+
+// --- SSE connection management ---
+
+function connect() {
+  if (eventSource) return;
+
+  const url = currentRunId
+    ? `/api/agent-events?runId=${encodeURIComponent(currentRunId)}`
+    : '/api/agent-events';
+
+  eventSource = new EventSource(url);
+  setStatus('connecting');
+
+  eventSource.onopen = () => {
+    setStatus('connected');
+    // Only reset backoff after connection is stable
+    stableTimer = setTimeout(() => {
+      stableTimer = null;
+      backoff = BASE_BACKOFF_MS;
+    }, STABLE_CONNECTION_MS);
+  };
+
+  eventSource.onerror = () => {
+    cleanup();
+    setStatus('disconnected');
+
+    // Don't reconnect if no subscribers
+    if (subscriberCount <= 0) return;
+
+    const delay = backoff;
+    backoff = Math.min(delay * 2, MAX_BACKOFF_MS);
+
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, delay);
+  };
+
+  eventSource.addEventListener('notification', (event) => {
+    /** @type {unknown} */
+    let data;
+    try {
+      data = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    broadcast({ type: 'notification', data });
+  });
+}
+
+function disconnect() {
+  if (reconnectTimer !== null) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  cleanup();
+  backoff = BASE_BACKOFF_MS;
+  setStatus('disconnected');
+}
+
+function cleanup() {
+  if (stableTimer !== null) {
+    clearTimeout(stableTimer);
+    stableTimer = null;
+  }
+  if (eventSource) {
+    eventSource.close();
+    eventSource = null;
+  }
+}
+
+// --- Helpers ---
+
+function setStatus(status) {
+  connectionStatus = status;
+  broadcast({ type: 'status', status });
+}
+
+async function broadcast(message) {
+  const clients = await self.clients.matchAll({ type: 'window' });
+  for (const client of clients) {
+    client.postMessage(message);
+  }
+}