π OpenHands: AI-Driven Development
fix(frontend): restore notification sound and browser tab flash on agent completion (#14049)
Xingyao Wang06d0320e5ced
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.mdnew file mode 100644index 0000000000..6add03c6ed--- /dev/null+++ b/.agents/skills/custom-codereview-guide.md@@ -0,0 +1,47 @@+---+name: custom-codereview-guide+description: Repo-specific code review guidelines for All-Hands-AI/OpenHands. Provides frontend and backend review rules in addition to the default code review skill.+triggers:+- /codereview+---++# All-Hands-AI/OpenHands Code Review Guidelines++You are an expert code reviewer for the **All-Hands-AI/OpenHands** repository. This skill provides repo-specific review guidelines.++## Frontend: i18n / Translation Key Usage++**Never dynamically construct i18n keys via string interpolation or template literals.**++All translation keys must come from the `I18nKey` enum (`frontend/src/i18n/declaration.ts`) or from canonical mapping objects like `AGENT_STATUS_MAP` (`frontend/src/utils/status.ts`). Dynamically constructed keys (e.g., `` t(`STATUS$${value.toUpperCase()}`) ``) will silently fall back to the raw key string at runtime because `i18next` returns the key itself when a translation is missing β this produces broken UI text with no build-time or test-time error.++### What to flag++- Any call to `t(...)` or `i18next.t(...)` where the key is built at runtime via template literals, string concatenation, or helper functions rather than referencing `I18nKey` or a known mapping+- Any new i18n key referenced in code that does not exist in `frontend/src/i18n/translation.json`++### Correct pattern++```ts+import { AGENT_STATUS_MAP } from "#/utils/status";++const i18nKey = AGENT_STATUS_MAP[agentState];+const message = i18nKey ? t(i18nKey) : fallback;+```++### Incorrect pattern++```ts+// BAD: constructs a key that may not exist in translation.json+const message = t(`STATUS$${agentState.toUpperCase()}`);+```++## Frontend: Data Fetching Architecture++UI components must never call API client methods (`frontend/src/api/`) directly. All data access must go through TanStack Query hooks:++```+UI components β TanStack Query hooks (frontend/src/hooks/query/ or mutation/) β API client (frontend/src/api/) β API endpoints+```++Flag any component that imports directly from `#/api/` and calls fetch/mutation functions without a TanStack Query wrapper.diff --git a/frontend/__tests__/hooks/use-agent-notification.test.ts b/frontend/__tests__/hooks/use-agent-notification.test.tsnew file mode 100644index 0000000000..28cf36b88d--- /dev/null+++ b/frontend/__tests__/hooks/use-agent-notification.test.ts@@ -0,0 +1,182 @@+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";+import { renderHook, act } from "@testing-library/react";+import { useAgentNotification } from "#/hooks/use-agent-notification";+import { AgentState } from "#/types/agent-state";+import * as browserTabModule from "#/utils/browser-tab";++// Mock useSettings to control the sound notification setting+vi.mock("#/hooks/query/use-settings", () => ({+ useSettings: vi.fn().mockReturnValue({+ data: { enable_sound_notifications: true },+ }),+}));++// Spy on browserTab methods+vi.spyOn(browserTabModule.browserTab, "startNotification");+vi.spyOn(browserTabModule.browserTab, "stopNotification");++// Mock Audio+const mockPlay = vi.fn().mockResolvedValue(undefined);+const mockAudio = {+ play: mockPlay,+ currentTime: 0,+ volume: 0.5,+};++class MockAudio {+ play = mockPlay;+ currentTime = 0;+ volume = 0.5;+ constructor() {+ Object.assign(this, mockAudio);+ return mockAudio as unknown as MockAudio;+ }+}+vi.stubGlobal("Audio", MockAudio);++describe("useAgentNotification", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ vi.clearAllMocks();+ // Simulate tab not focused+ Object.defineProperty(document, "hasFocus", {+ value: () => false,+ configurable: true,+ });+ });++ afterEach(() => {+ vi.useRealTimers();+ // Restore hasFocus+ Object.defineProperty(document, "hasFocus", {+ value: () => true,+ configurable: true,+ });+ });++ it("starts browser tab notification when agent reaches FINISHED state and tab is not focused", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ // Transition to FINISHED+ rerender({ state: AgentState.FINISHED });++ expect(+ browserTabModule.browserTab.startNotification,+ ).toHaveBeenCalledTimes(1);+ });++ it("plays notification sound when agent reaches FINISHED state and sound is enabled", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ // Transition to FINISHED+ rerender({ state: AgentState.FINISHED });++ expect(mockPlay).toHaveBeenCalledTimes(1);+ });++ it("starts notification when agent reaches AWAITING_USER_INPUT state", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ // Transition to AWAITING_USER_INPUT+ rerender({ state: AgentState.AWAITING_USER_INPUT });++ expect(+ browserTabModule.browserTab.startNotification,+ ).toHaveBeenCalledTimes(1);+ });++ it("starts notification when agent reaches AWAITING_USER_CONFIRMATION state", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ rerender({ state: AgentState.AWAITING_USER_CONFIRMATION });++ expect(+ browserTabModule.browserTab.startNotification,+ ).toHaveBeenCalledTimes(1);+ });++ it("stops browser tab notification when window gains focus", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ rerender({ state: AgentState.FINISHED });++ // Simulate window focus+ act(() => {+ window.dispatchEvent(new Event("focus"));+ });++ expect(+ browserTabModule.browserTab.stopNotification,+ ).toHaveBeenCalledTimes(1);+ });++ it("does not start tab flash when focused, but still plays sound", () => {+ Object.defineProperty(document, "hasFocus", {+ value: () => true,+ configurable: true,+ });++ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ rerender({ state: AgentState.FINISHED });++ expect(+ browserTabModule.browserTab.startNotification,+ ).not.toHaveBeenCalled();+ // Sound still plays when focused (completion chime UX pattern)+ expect(mockPlay).toHaveBeenCalledTimes(1);+ });++ it("does not play sound when sound notifications are disabled", async () => {+ const { useSettings } = await import("#/hooks/query/use-settings");+ vi.mocked(useSettings).mockReturnValue({+ data: { enable_sound_notifications: false },+ } as ReturnType<typeof useSettings>);++ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.RUNNING } },+ );++ rerender({ state: AgentState.FINISHED });++ expect(mockPlay).not.toHaveBeenCalled();++ // Restore+ vi.mocked(useSettings).mockReturnValue({+ data: { enable_sound_notifications: true },+ } as ReturnType<typeof useSettings>);+ });++ it("does not trigger for non-notification states like RUNNING", () => {+ const { rerender } = renderHook(+ ({ state }) => useAgentNotification(state),+ { initialProps: { state: AgentState.LOADING } },+ );++ rerender({ state: AgentState.RUNNING });++ expect(+ browserTabModule.browserTab.startNotification,+ ).not.toHaveBeenCalled();+ expect(mockPlay).not.toHaveBeenCalled();+ });+});diff --git a/frontend/__tests__/utils/browser-tab.test.ts b/frontend/__tests__/utils/browser-tab.test.tsnew file mode 100644index 0000000000..f133e431cf--- /dev/null+++ b/frontend/__tests__/utils/browser-tab.test.ts@@ -0,0 +1,77 @@+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";++import { browserTab } from "#/utils/browser-tab";++// These tests exercise the browser-tab notification flasher behavior.+// Specifically we verify that when the document title changes externally+// while a notification is active, the flasher updates its internal+// baseline so it restores/toggles to the new title instead of an old one.++describe("browserTab notifications", () => {+ const MESSAGE = "Agent ready";+ const INITIAL = "Conversation 123 | OpenHands";+ const RENAMED = "My renamed title | OpenHands";++ beforeEach(() => {+ vi.useFakeTimers();+ // reset title for each test+ document.title = INITIAL;+ });++ afterEach(() => {+ browserTab.stopNotification();+ vi.runOnlyPendingTimers();+ vi.useRealTimers();+ });++ it("flashes the browser tab title between the original title and the notification message", () => {+ browserTab.startNotification(MESSAGE);++ // First tick: should switch to the notification message+ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(MESSAGE);++ // Next tick: should switch back to original+ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(INITIAL);++ // Next tick: should switch to message again+ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(MESSAGE);+ });++ it("stops flashing and restores original title when stopNotification is called", () => {+ browserTab.startNotification(MESSAGE);++ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(MESSAGE);++ browserTab.stopNotification();+ expect(document.title).toBe(INITIAL);+ });++ it("updates baseline when title changes during an active notification and restores to the new title", () => {+ // Start flashing+ browserTab.startNotification(MESSAGE);++ // Tick once: should switch to the message+ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(MESSAGE);++ // Simulate an external rename while flashing (e.g., user edits title)+ document.title = RENAMED;++ // Next tick: flasher observes the external change and updates baseline+ vi.advanceTimersByTime(1000);+ // On this tick, we toggle back to the message+ expect(document.title).toBe(MESSAGE);++ // Next tick should toggle to the updated baseline (renamed title)+ vi.advanceTimersByTime(1000);+ expect(document.title).toBe(RENAMED);++ // Stop flashing: title should remain the updated baseline+ browserTab.stopNotification();+ expect(document.title).toBe(RENAMED);+ });+});diff --git a/frontend/src/assets/notification.mp3 b/frontend/src/assets/notification.mp3new file mode 100644index 0000000000..7937b7c566Binary files /dev/null and b/frontend/src/assets/notification.mp3 differdiff --git a/frontend/src/components/features/controls/agent-status.tsx b/frontend/src/components/features/controls/agent-status.tsxindex b0dba1fa25..176bffea23 100644--- a/frontend/src/components/features/controls/agent-status.tsx+++ b/frontend/src/components/features/controls/agent-status.tsx@@ -14,6 +14,7 @@ import { useAgentState } from "#/hooks/use-agent-state";import { useUnifiedWebSocketStatus } from "#/hooks/use-unified-websocket-status";import { useTaskPolling } from "#/hooks/query/use-task-polling";import { useSubConversationTaskPolling } from "#/hooks/query/use-sub-conversation-task-polling";+import { useAgentNotification } from "#/hooks/use-agent-notification";export interface AgentStatusProps {className?: string;@@ -33,6 +34,9 @@ export function AgentStatus({const { t } = useTranslation();const { setShouldShownAgentLoading } = useConversationStore();const { curAgentState, executionStatus } = useAgentState();++ // Trigger browser tab flash and notification sound on state changes+ useAgentNotification(curAgentState);const webSocketStatus = useUnifiedWebSocketStatus();const { data: conversation } = useActiveConversation();const { taskStatus } = useTaskPolling();diff --git a/frontend/src/hooks/use-agent-notification.ts b/frontend/src/hooks/use-agent-notification.tsnew file mode 100644index 0000000000..bef6190811--- /dev/null+++ b/frontend/src/hooks/use-agent-notification.ts@@ -0,0 +1,76 @@+import { useEffect, useRef } from "react";+import { useTranslation } from "react-i18next";+import { AgentState } from "#/types/agent-state";+import { browserTab } from "#/utils/browser-tab";+import { useSettings } from "#/hooks/query/use-settings";+import { AGENT_STATUS_MAP } from "#/utils/status";+import notificationSound from "#/assets/notification.mp3";++const NOTIFICATION_STATES: AgentState[] = [+ AgentState.AWAITING_USER_INPUT,+ AgentState.FINISHED,+ AgentState.AWAITING_USER_CONFIRMATION,+];++/**+ * Hook that triggers browser tab flashing and notification sound+ * when the agent transitions into a state that requires user attention.+ *+ * - Flashes the browser tab title when the tab is not focused.+ * - Plays a notification sound if enabled in settings.+ * - Stops flashing when the user focuses the tab.+ */+export function useAgentNotification(curAgentState: AgentState) {+ const { data: settings } = useSettings();+ const { t } = useTranslation();+ const audioRef = useRef<HTMLAudioElement | undefined>(undefined);+ const prevStateRef = useRef<AgentState | undefined>(undefined);++ // Initialize audio only in browser environment, inside useEffect to+ // avoid side effects during render (React 18 strict mode, SSR safety).+ useEffect(() => {+ if (typeof window !== "undefined" && !audioRef.current) {+ audioRef.current = new Audio(notificationSound);+ audioRef.current.volume = 0.5;+ }+ }, []);++ const isSoundEnabled = settings?.enable_sound_notifications ?? false;++ // Trigger notification only on actual state transitions into a+ // notification-worthy state β not when unrelated deps (e.g. settings) change.+ useEffect(() => {+ if (prevStateRef.current === curAgentState) return;+ prevStateRef.current = curAgentState;++ if (!NOTIFICATION_STATES.includes(curAgentState)) return;++ if (isSoundEnabled && audioRef.current) {+ audioRef.current.currentTime = 0;+ audioRef.current.play().catch(() => {+ // Ignore autoplay errors (browsers may block autoplay)+ });+ }++ if (typeof document !== "undefined" && !document.hasFocus()) {+ const i18nKey = AGENT_STATUS_MAP[curAgentState];+ const message = i18nKey ? t(i18nKey) : curAgentState;+ browserTab.startNotification(message);+ }+ }, [curAgentState, isSoundEnabled, t]);++ // Stop tab notification when window gains focus+ useEffect(() => {+ if (typeof window === "undefined") return undefined;++ const handleFocus = () => {+ browserTab.stopNotification();+ };++ window.addEventListener("focus", handleFocus);+ return () => {+ window.removeEventListener("focus", handleFocus);+ browserTab.stopNotification();+ };+ }, []);+}diff --git a/frontend/src/utils/browser-tab.ts b/frontend/src/utils/browser-tab.tsnew file mode 100644index 0000000000..f08d9656ee--- /dev/null+++ b/frontend/src/utils/browser-tab.ts@@ -0,0 +1,42 @@+let originalTitle = "";+let titleInterval: number | undefined;++const isBrowser =+ typeof window !== "undefined" && typeof document !== "undefined";++export const browserTab = {+ startNotification(message: string) {+ if (!isBrowser) return;++ // Always capture the current title as the baseline to restore to+ originalTitle = document.title;++ // Clear any existing interval+ if (titleInterval) {+ this.stopNotification();+ }++ // Alternate between the latest baseline title and the notification message.+ // If the title changes externally (e.g., user renames conversation),+ // update the baseline so we restore to the new value when stopping.+ titleInterval = window.setInterval(() => {+ const current = document.title;+ if (current !== originalTitle && current !== message) {+ originalTitle = current;+ }+ document.title = current === message ? originalTitle : message;+ }, 1000);+ },++ stopNotification() {+ if (!isBrowser) return;++ if (titleInterval) {+ window.clearInterval(titleInterval);+ titleInterval = undefined;+ }+ if (originalTitle) {+ document.title = originalTitle;+ }+ },+};