Add desktop notifications with anti-spam throttling to AEA monitor

.devwork/plan.md

@@ -0,0 +1,30 @@
+# Execution Plan
+
+## Tasks: 3
+
+{
+  "summary": "Analyze the current state of aea-monitor.sh to verify if desktop notification and anti-spam throttling changes are already implemented, then validate the implementation",
+  "tasks": [
+    {
+      "id": "T001",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git log --oneline -5 scripts/aea-monitor.sh" },
+      "depends_on": [],
+      "description": "Check git history of aea-monitor.sh to see current implementation state"
+    },
+    {
+      "id": "T002",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git status --short" },
+      "depends_on": [],
+      "description": "Check current git status for any uncommitted changes"
+    },
+    {
+      "id": "T003",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git diff HEAD~2..HEAD -- scripts/aea-monitor.sh 2>/dev/null || git show HEAD:scripts/aea-monitor.sh 2>/dev/null | head -100" },
+      "depends_on": ["T001"],
+      "description": "View the current implementation of aea-monitor.sh to check for notification functions"
+    }
+  ]
+}

.devwork/plan_response.txt

@@ -0,0 +1,26 @@
+{
+  "summary": "Analyze the current state of aea-monitor.sh to verify if desktop notification and anti-spam throttling changes are already implemented, then validate the implementation",
+  "tasks": [
+    {
+      "id": "T001",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git log --oneline -5 scripts/aea-monitor.sh" },
+      "depends_on": [],
+      "description": "Check git history of aea-monitor.sh to see current implementation state"
+    },
+    {
+      "id": "T002",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git status --short" },
+      "depends_on": [],
+      "description": "Check current git status for any uncommitted changes"
+    },
+    {
+      "id": "T003",
+      "tool": "Bash",
+      "args": { "command": "cd /tmp/claudev-pr-19260 && git diff HEAD~2..HEAD -- scripts/aea-monitor.sh 2>/dev/null || git show HEAD:scripts/aea-monitor.sh 2>/dev/null | head -100" },
+      "depends_on": ["T001"],
+      "description": "View the current implementation of aea-monitor.sh to check for notification functions"
+    }
+  ]
+}

.devwork/prompt.txt

@@ -0,0 +1,248 @@
+# PR #4: Add desktop notifications with anti-spam throttling to AEA monitor
+
+## Description
+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
+
+```bash
+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 → ✅ Notif
+... (truncated)
+
+## Diff
+```diff
+diff --git a/scripts/aea-monitor.sh b/scripts/aea-monitor.sh
+index d67205a..3040595 100755
+--- a/scripts/aea-monitor.sh
++++ b/scripts/aea-monitor.sh
+@@ -54,6 +54,16 @@ info() {
+     echo -e "${BLUE}[AEA Monitor]${NC} $1"
+ }
+
++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
++}
++
+ #===============================================================================
+ # PID Management
+ #===============================================================================
+@@ -347,10 +357,29 @@ check_project_messages() {
+             echo "[$timestamp] Monitor found $unprocessed_count unprocessed messages" >> ".aea/agent.log"
+         fi
+
++        # Send desktop notification only if message count has increased
++        # Track notification state to avoid spam
++        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
++
+         # TODO: In future, this would trigger Claude via API
+         # For now, just log that messages are waiting
+         warn "⏳ Messages waiting for Claude processing in $project_name"
+         warn "   Run: cd $project_path && /aea"
++    else
++        # Clear notification state when all messages are processed
++        local notif_state_file="$CONFIG_DIR/.notification_state_$(echo "$project_path" | md5sum | cut -d' ' -f1)"
++        rm -f "$notif_state_file" 2>/dev/null
+     fi
+ }
+
+```
+
+## Task
+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
+
+```bash
+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 openSVM/aea#3
+
+<!-- START COPILOT CODING AGENT SUFFIX -->
+
+
+
+<details>
+
+<summary>Original prompt</summary>
+
+> 
+> ----
+> 
+> *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:
+> 
+> ```bash
+> # 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)
+> 
+> <comments>
+> </comments>
+> 
+
+
+</details>
+
+- Fixes openSVM/aea#3
+
+<!-- START COPILOT CODING AGENT TIPS -->
+---
+
+💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).
+