feat: Add Terminal Attention Notifications for User Alerts (#1052)

packages/cli/src/ui/hooks/useAttentionNotifications.test.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { StreamingState } from '../types.js';
+import {
+  AttentionNotificationReason,
+  notifyTerminalAttention,
+} from '../../utils/attentionNotification.js';
+import {
+  LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS,
+  useAttentionNotifications,
+} from './useAttentionNotifications.js';
+
+vi.mock('../../utils/attentionNotification.js', () => ({
+  notifyTerminalAttention: vi.fn(),
+  AttentionNotificationReason: {
+    ToolApproval: 'tool_approval',
+    LongTaskComplete: 'long_task_complete',
+  },
+}));
+
+const mockedNotify = vi.mocked(notifyTerminalAttention);
+
+describe('useAttentionNotifications', () => {
+  beforeEach(() => {
+    mockedNotify.mockReset();
+  });
+
+  const render = (
+    props?: Partial<Parameters<typeof useAttentionNotifications>[0]>,
+  ) =>
+    renderHook(({ hookProps }) => useAttentionNotifications(hookProps), {
+      initialProps: {
+        hookProps: {
+          isFocused: true,
+          streamingState: StreamingState.Idle,
+          elapsedTime: 0,
+          ...props,
+        },
+      },
+    });
+
+  it('notifies when tool approval is required while unfocused', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.WaitingForConfirmation,
+        elapsedTime: 0,
+      },
+    });
+
+    expect(mockedNotify).toHaveBeenCalledWith(
+      AttentionNotificationReason.ToolApproval,
+    );
+  });
+
+  it('notifies when focus is lost after entering approval wait state', () => {
+    const { rerender } = render({
+      isFocused: true,
+      streamingState: StreamingState.WaitingForConfirmation,
+    });
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.WaitingForConfirmation,
+        elapsedTime: 0,
+      },
+    });
+
+    expect(mockedNotify).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends a notification when a long task finishes while unfocused', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Responding,
+        elapsedTime: LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS + 5,
+      },
+    });
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Idle,
+        elapsedTime: 0,
+      },
+    });
+
+    expect(mockedNotify).toHaveBeenCalledWith(
+      AttentionNotificationReason.LongTaskComplete,
+    );
+  });
+
+  it('does not notify about long tasks when the CLI is focused', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: true,
+        streamingState: StreamingState.Responding,
+        elapsedTime: LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS + 2,
+      },
+    });
+
+    rerender({
+      hookProps: {
+        isFocused: true,
+        streamingState: StreamingState.Idle,
+        elapsedTime: 0,
+      },
+    });
+
+    expect(mockedNotify).not.toHaveBeenCalledWith(
+      AttentionNotificationReason.LongTaskComplete,
+      expect.anything(),
+    );
+  });
+
+  it('does not treat short responses as long tasks', () => {
+    const { rerender } = render();
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Responding,
+        elapsedTime: 5,
+      },
+    });
+
+    rerender({
+      hookProps: {
+        isFocused: false,
+        streamingState: StreamingState.Idle,
+        elapsedTime: 0,
+      },
+    });
+
+    expect(mockedNotify).not.toHaveBeenCalled();
+  });
+});

packages/cli/src/ui/hooks/useAttentionNotifications.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useEffect, useRef } from 'react';
+import { StreamingState } from '../types.js';
+import {
+  notifyTerminalAttention,
+  AttentionNotificationReason,
+} from '../../utils/attentionNotification.js';
+
+export const LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS = 20;
+
+interface UseAttentionNotificationsOptions {
+  isFocused: boolean;
+  streamingState: StreamingState;
+  elapsedTime: number;
+}
+
+export const useAttentionNotifications = ({
+  isFocused,
+  streamingState,
+  elapsedTime,
+}: UseAttentionNotificationsOptions) => {
+  const awaitingNotificationSentRef = useRef(false);
+  const respondingElapsedRef = useRef(0);
+
+  useEffect(() => {
+    if (
+      streamingState === StreamingState.WaitingForConfirmation &&
+      !isFocused &&
+      !awaitingNotificationSentRef.current
+    ) {
+      notifyTerminalAttention(AttentionNotificationReason.ToolApproval);
+      awaitingNotificationSentRef.current = true;
+    }
+
+    if (streamingState !== StreamingState.WaitingForConfirmation || isFocused) {
+      awaitingNotificationSentRef.current = false;
+    }
+  }, [isFocused, streamingState]);
+
+  useEffect(() => {
+    if (streamingState === StreamingState.Responding) {
+      respondingElapsedRef.current = elapsedTime;
+      return;
+    }
+
+    if (streamingState === StreamingState.Idle) {
+      const wasLongTask =
+        respondingElapsedRef.current >=
+        LONG_TASK_NOTIFICATION_THRESHOLD_SECONDS;
+      if (wasLongTask && !isFocused) {
+        notifyTerminalAttention(AttentionNotificationReason.LongTaskComplete);
+      }
+      // Reset tracking for next task
+      respondingElapsedRef.current = 0;
+      return;
+    }
+  }, [streamingState, elapsedTime, isFocused]);
+};