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

packages/cli/src/utils/attentionNotification.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  notifyTerminalAttention,
+  AttentionNotificationReason,
+} from './attentionNotification.js';
+
+describe('notifyTerminalAttention', () => {
+  let stream: { write: ReturnType<typeof vi.fn>; isTTY: boolean };
+
+  beforeEach(() => {
+    stream = { write: vi.fn().mockReturnValue(true), isTTY: true };
+  });
+
+  it('emits terminal bell character', () => {
+    const result = notifyTerminalAttention(
+      AttentionNotificationReason.ToolApproval,
+      {
+        stream,
+      },
+    );
+
+    expect(result).toBe(true);
+    expect(stream.write).toHaveBeenCalledWith('\u0007');
+  });
+
+  it('returns false when not running inside a tty', () => {
+    stream.isTTY = false;
+
+    const result = notifyTerminalAttention(
+      AttentionNotificationReason.ToolApproval,
+      { stream },
+    );
+
+    expect(result).toBe(false);
+    expect(stream.write).not.toHaveBeenCalled();
+  });
+
+  it('returns false when stream write fails', () => {
+    stream.write = vi.fn().mockImplementation(() => {
+      throw new Error('Write failed');
+    });
+
+    const result = notifyTerminalAttention(
+      AttentionNotificationReason.ToolApproval,
+      { stream },
+    );
+
+    expect(result).toBe(false);
+  });
+
+  it('works with different notification reasons', () => {
+    const reasons = [
+      AttentionNotificationReason.ToolApproval,
+      AttentionNotificationReason.LongTaskComplete,
+    ];
+
+    reasons.forEach((reason) => {
+      stream.write.mockClear();
+
+      const result = notifyTerminalAttention(reason, { stream });
+
+      expect(result).toBe(true);
+      expect(stream.write).toHaveBeenCalledWith('\u0007');
+    });
+  });
+});

packages/cli/src/utils/attentionNotification.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import process from 'node:process';
+
+export enum AttentionNotificationReason {
+  ToolApproval = 'tool_approval',
+  LongTaskComplete = 'long_task_complete',
+}
+
+export interface TerminalNotificationOptions {
+  stream?: Pick<NodeJS.WriteStream, 'write' | 'isTTY'>;
+}
+
+const TERMINAL_BELL = '\u0007';
+
+/**
+ * Grabs the user's attention by emitting the terminal bell character.
+ * This causes the terminal to flash or play a sound, alerting the user
+ * to check the CLI for important events.
+ *
+ * @returns true when the bell was successfully written to the terminal.
+ */
+export function notifyTerminalAttention(
+  _reason: AttentionNotificationReason,
+  options: TerminalNotificationOptions = {},
+): boolean {
+  const stream = options.stream ?? process.stdout;
+  if (!stream?.write || stream.isTTY === false) {
+    return false;
+  }
+
+  try {
+    stream.write(TERMINAL_BELL);
+    return true;
+  } catch (error) {
+    console.warn('Failed to send terminal bell:', error);
+    return false;
+  }
+}