Add desktop notifications with anti-spam throttling to AEA monitor

[Copilot]

The AEA monitor logs message arrivals to the terminal but provides no notification when the terminal is not in focus.

Changes

scripts/aea-monitor.sh (+31 lines)

• Added send_notification() helper that conditionally calls notify-send if available
• Integrated notification call in check_project_messages() when unprocessed messages are detected
• Added intelligent throttling to prevent notification spam

Implementation

send_notification() {
    local title="$1"
    local message="$2"
    
    # Optional: Send desktop notification if available
    if command -v notify-send &> /dev/null; then
        notify-send "$title" "$message" -i dialog-information -t 10000 2>/dev/null || true
    fi
}

# Throttling logic - only notify when message count increases
local notif_state_file="$CONFIG_DIR/.notification_state_$(echo "$project_path" | md5sum | cut -d' ' -f1)"
local last_notified_count=0

if [ -f "$notif_state_file" ]; then
    last_notified_count=$(cat "$notif_state_file" 2>/dev/null || echo 0)
fi

# Only notify if message count increased (new messages arrived)
if [ "$unprocessed_count" -gt "$last_notified_count" ]; then
    send_notification "AEA Monitor" "New messages in $project_name"
    echo "$unprocessed_count" > "$notif_state_file"
fi

Notification displays for 10 seconds with dialog-information icon. Gracefully no-ops if notify-send unavailable.

Anti-Spam Throttling

The notification system includes intelligent throttling to prevent spam:

• State tracking: Stores last notified message count per project in ~/.config/aea/.notification_state_<hash>
• Conditional alerts: Only sends notification when message count increases (new messages arrive)
• Automatic cleanup: Clears state when all messages are processed

Example behavior:

• 3 messages detected → ✅ Notification sent
• Same 3 messages (5 min later) → ⏭️ No notification
• 5 messages now (2 new arrived) → ✅ Notification sent
• All processed → State cleared
• 1 new message → ✅ Notification sent

Ready for extension to macOS/Windows notification systems.

• Fixes Enhancement: Add desktop notifications to AEA monitor script #3

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Enhancement: Add desktop notifications to AEA monitor script</issue_title>
<issue_description>## Enhancement Description

The AEA monitor script currently only logs messages to the terminal when new messages are detected. Adding desktop notification support would greatly improve the user experience by providing visual alerts even when the terminal is not in focus.

Proposed Changes

Add optional desktop notification support to scripts/aea-monitor.sh when new AEA messages are detected:

# Optional: Send desktop notification if available
if command -v notify-send &> /dev/null; then
    notify-send "AEA Monitor" "New messages in $project_name" -i dialog-information -t 10000
fi

Benefits

1. Improved User Experience: Users get immediate visual feedback about new messages without constantly watching the terminal
2. Non-intrusive: Only triggers if notify-send is available (Linux desktop environments)
3. Configurable: Can be easily disabled or customized
4. Cross-platform potential: Could be extended to support macOS (osascript) and Windows notifications

Implementation Details

The enhancement has been tested in a production environment and works reliably. The notification:

• Shows for 10 seconds (configurable)
• Displays the project name where messages are waiting
• Uses standard dialog-information icon
• Only triggers when notify-send command is available

Additional Considerations

Future enhancements could include:

• Configuration option to enable/disable notifications
• Custom notification icons for different message types
• Sound alerts for urgent messages
• Integration with other notification systems (Growl, Windows Toast, etc.)

Testing

Tested on Ubuntu 22.04 with GNOME desktop environment. The notification appears correctly and doesn't interfere with the monitor's core functionality.

Would you like me to submit a pull request with this enhancement?</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Enhancement: Add desktop notifications to AEA monitor script #3

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[devloai]

Unable to perform a code review. You have run out of credits 😔
Please upgrade your plan or buy additional credits from the subscription page.

[Copilot]

Pull Request Overview

This PR adds desktop notification support to the AEA monitor script, alerting users when new messages are detected even when the terminal is not in focus.

Key Changes:

• Added send_notification() helper function that uses notify-send when available
• Integrated desktop notifications into the message detection workflow
• Notifications display for 10 seconds with graceful fallback if notify-send is unavailable

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The notification is sent every time check_project_messages() detects unprocessed messages, which could result in repeated notifications during the same monitoring cycle. Consider adding a condition to only send the notification when messages are first detected, or throttling notifications to avoid spam.

[0xrinegade]

@copilot The notification is sent every time check_project_messages() detects unprocessed messages, which could result in repeated notifications during the same monitoring cycle. Consider adding a condition to only send the notification when messages are first detected, or throttling notifications to avoid spam.

[Copilot]

@copilot The notification is sent every time check_project_messages() detects unprocessed messages, which could result in repeated notifications during the same monitoring cycle. Consider adding a con...

Added notification throttling in commit 5156e7b. The monitor now tracks message count per project and only sends notifications when the count increases (new messages arrive). Repeated checks for the same messages no longer trigger notifications. State is automatically cleared when all messages are processed.

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The state file path construction is duplicated in two places (lines 362 and 381). Extract this to a local variable at the beginning of the function to avoid repetition and ensure consistency.

Suggested change

	local notif_state_file="$CONFIG_DIR/.notification_state_$(echo "$project_path" | md5sum | cut -d' ' -f1)"
	local notif_state_file
	notif_state_file="$CONFIG_DIR/.notification_state_$(echo "$project_path" | md5sum | cut -d' ' -f1)"

[Copilot]

The fallback || echo 0 executes when cat fails (file doesn't exist), but also when the file exists and is empty or contains invalid data. This could lead to notifications being sent repeatedly if the state file is corrupted. Consider explicit validation of the file content or initialization with a default value.

Suggested change

	last_notified_count=$(cat "$notif_state_file" 2>/dev/null || echo 0)
	notif_content=$(cat "$notif_state_file" 2>/dev/null)
	if [[ "$notif_content" =~ ^[0-9]+$ ]]; then
	last_notified_count="$notif_content"
	else
	last_notified_count=0
	fi