feat: add sound and browser notifications for agent state changes

frontend/package.json

@@ -89,6 +89,7 @@
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
     "@types/react-highlight": "^0.12.8",
+    "@types/react-router-dom": "^5.3.3",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@types/ws": "^8.5.14",
     "@typescript-eslint/eslint-plugin": "^7.18.0",

frontend/src/components/features/controls/agent-status-bar.tsx

@@ -9,12 +9,21 @@ import {
   useWsClient,
   WsClientProviderStatus,
 } from "#/context/ws-client-provider";
+import { useNotification } from "#/hooks/useNotification";
+import { browserTab } from "#/utils/browser-tab";
+
+const notificationStates = [
+  AgentState.AWAITING_USER_INPUT,
+  AgentState.FINISHED,
+  AgentState.AWAITING_USER_CONFIRMATION,
+];
 
 export function AgentStatusBar() {
   const { t, i18n } = useTranslation();
   const { curAgentState } = useSelector((state: RootState) => state.agent);
   const { curStatusMessage } = useSelector((state: RootState) => state.status);
   const { status } = useWsClient();
+  const { notify } = useNotification();
 
   const [statusMessage, setStatusMessage] = React.useState<string>("");
 
@@ -41,13 +50,40 @@ export function AgentStatusBar() {
     updateStatusMessage();
   }, [curStatusMessage.id]);
 
+  // Handle window focus/blur
+  React.useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+
+    const handleFocus = () => {
+      browserTab.stopNotification();
+    };
+
+    window.addEventListener("focus", handleFocus);
+    return () => {
+      window.removeEventListener("focus", handleFocus);
+      browserTab.stopNotification();
+    };
+  }, []);
+
   React.useEffect(() => {
     if (status === WsClientProviderStatus.DISCONNECTED) {
       setStatusMessage("Connecting...");
     } else {
       setStatusMessage(AGENT_STATUS_MAP[curAgentState].message);
+      if (notificationStates.includes(curAgentState)) {
+        const message = t(AGENT_STATUS_MAP[curAgentState].message);
+        notify(t(AGENT_STATUS_MAP[curAgentState].message), {
+          body: t(`Agent state changed to ${curAgentState}`),
+          playSound: true,
+        });
+
+        // Update browser tab if window exists and is not focused
+        if (typeof document !== "undefined" && !document.hasFocus()) {
+          browserTab.startNotification(message);
+        }
+      }
     }
-  }, [curAgentState]);
+  }, [curAgentState, notify, t]);
 
   return (
     <div className="flex flex-col items-center">

frontend/src/components/features/trajectory/trajectory-actions.tsx

@@ -1,7 +1,12 @@
+import { HiVolumeUp, HiVolumeOff } from "react-icons/hi";
+import { useTranslation } from "react-i18next";
+import { useQueryClient } from "@tanstack/react-query";
+import toast from "react-hot-toast";
 import ThumbsUpIcon from "#/icons/thumbs-up.svg?react";
 import ThumbDownIcon from "#/icons/thumbs-down.svg?react";
 import ExportIcon from "#/icons/export.svg?react";
 import { TrajectoryActionButton } from "#/components/shared/buttons/trajectory-action-button";
+import { useCurrentSettings } from "#/context/settings-context";
 
 interface TrajectoryActionsProps {
   onPositiveFeedback: () => void;
@@ -14,22 +19,56 @@
   onNegativeFeedback,
   onExportTrajectory,
 }: TrajectoryActionsProps) {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+  const { settings, saveUserSettings } = useCurrentSettings();
+  const soundEnabled = settings?.ENABLE_SOUND_NOTIFICATIONS ?? true;
+
+  const toggleSound = async () => {
+    try {
+      const newSettings = {
+        ...settings,
+        ENABLE_SOUND_NOTIFICATIONS: !soundEnabled,
+      };
+      await saveUserSettings(newSettings);
+      // Wait for the settings to be saved before invalidating
+      await queryClient.invalidateQueries({ queryKey: ["settings"] });
+      // Immediately update the local state to avoid flicker
+      queryClient.setQueryData(["settings"], newSettings);
+    } catch (error) {
+      toast.error(t("Failed to save sound settings. Please try again."));
+    }
+  };
   return (
     <div data-testid="feedback-actions" className="flex gap-1">
       <TrajectoryActionButton
         testId="positive-feedback"
         onClick={onPositiveFeedback}
         icon={<ThumbsUpIcon width={15} height={15} />}
+        tooltip={t("BUTTON$MARK_HELPFUL")}
       />
       <TrajectoryActionButton
         testId="negative-feedback"
         onClick={onNegativeFeedback}
         icon={<ThumbDownIcon width={15} height={15} />}
+        tooltip={t("BUTTON$MARK_NOT_HELPFUL")}
       />
       <TrajectoryActionButton
         testId="export-trajectory"
         onClick={onExportTrajectory}
         icon={<ExportIcon width={15} height={15} />}
+        tooltip={t("BUTTON$EXPORT_CONVERSATION")}
+      />
+      <TrajectoryActionButton
+        testId="sound-toggle"
+        onClick={toggleSound}
+        icon={
+          soundEnabled ? <HiVolumeUp size={15} /> : <HiVolumeOff size={15} />
+        }
+        tooltip={t(
+          soundEnabled ? "BUTTON$DISABLE_SOUND" : "BUTTON$ENABLE_SOUND",
+          { playSound: false },
+        )}
       />
     </div>
   );

frontend/src/components/shared/buttons/trajectory-action-button.tsx

@@ -1,15 +1,19 @@
+import { Tooltip } from "@nextui-org/react";
+
 interface TrajectoryActionButtonProps {
   testId?: string;
   onClick: () => void;
   icon: React.ReactNode;
+  tooltip?: string;
 }
 
 export function TrajectoryActionButton({
   testId,
   onClick,
   icon,
+  tooltip,
 }: TrajectoryActionButtonProps) {
-  return (
+  const button = (
     <button
       type="button"
       data-testid={testId}
@@ -19,4 +23,14 @@ export function TrajectoryActionButton({
       {icon}
     </button>
   );
+
+  if (tooltip) {
+    return (
+      <Tooltip content={tooltip} closeDelay={100}>
+        {button}
+      </Tooltip>
+    );
+  }
+
+  return button;
 }

frontend/src/hooks/mutation/use-save-settings.ts

@@ -16,6 +16,7 @@ const saveSettingsMutationFn = async (settings: Partial<PostSettings>) => {
     github_token: settings.github_token,
     unset_github_token: settings.unset_github_token,
     enable_default_condenser: settings.ENABLE_DEFAULT_CONDENSER,
+    enable_sound_notifications: settings.ENABLE_SOUND_NOTIFICATIONS,
     user_consents_to_analytics: settings.user_consents_to_analytics,
   };
 

frontend/src/hooks/query/use-settings.ts

@@ -19,6 +19,7 @@ const getSettingsQueryFn = async () => {
     REMOTE_RUNTIME_RESOURCE_FACTOR: apiSettings.remote_runtime_resource_factor,
     GITHUB_TOKEN_IS_SET: apiSettings.github_token_is_set,
     ENABLE_DEFAULT_CONDENSER: apiSettings.enable_default_condenser,
+    ENABLE_SOUND_NOTIFICATIONS: apiSettings.enable_sound_notifications,
     USER_CONSENTS_TO_ANALYTICS: apiSettings.user_consents_to_analytics,
   };
 };
@@ -30,8 +31,9 @@ export const useSettings = () => {
     queryKey: ["settings"],
     queryFn: getSettingsQueryFn,
     initialData: DEFAULT_SETTINGS,
-    staleTime: 0,
-    retry: false,
+    staleTime: 1000, // Consider data fresh for 1 second
+    retry: 1, // Retry failed requests once
+    refetchOnWindowFocus: false, // Don't refetch on window focus
     meta: {
       disableToast: true,
     },

frontend/src/hooks/useNotification.ts

@@ -0,0 +1,56 @@
+import { useCallback, useRef } from "react";
+import notificationSound from "../assets/notification.mp3";
+import { useCurrentSettings } from "../context/settings-context";
+
+export const useNotification = () => {
+  const { settings } = useCurrentSettings();
+  const audioRef = useRef<HTMLAudioElement | undefined>(undefined);
+
+  // Initialize audio only in browser environment
+  if (typeof window !== "undefined" && !audioRef.current) {
+    audioRef.current = new Audio(notificationSound);
+    audioRef.current.volume = 0.5;
+  }
+
+  const notify = useCallback(
+    async (
+      title: string,
+      options?: NotificationOptions & { playSound?: boolean },
+    ): Promise<Notification | undefined> => {
+      if (typeof window === "undefined") return undefined;
+
+      // Only play sound if:
+      // 1. Explicitly requested via playSound option
+      // 2. Sound notifications are enabled in settings
+      // 3. Audio is available
+      // 4. Not a settings-related notification
+      if (
+        options?.playSound === true && // Must be explicitly true
+        settings?.ENABLE_SOUND_NOTIFICATIONS &&
+        audioRef.current &&
+        !title.includes("BUTTON$") // Don't play for button/settings actions
+      ) {
+        // Reset and play sound
+        audioRef.current.currentTime = 0;
+        audioRef.current.play().catch(() => {
+          // Ignore autoplay errors
+        });
+      }
+
+      if (Notification.permission === "default") {
+        await Notification.requestPermission();
+      }
+
+      if (Notification.permission === "granted") {
+        // Remove playSound from options before passing to Notification
+        const { playSound, ...notificationOptions } = options || {};
+        return new Notification(title, notificationOptions);
+      }
+
+      return undefined;
+    },
+    [settings?.ENABLE_SOUND_NOTIFICATIONS],
+  );
+
+  return { notify };
+};