agent-messenger 1.0.0

package/skills/agent-slack/references/common-patterns.md

@@ -0,0 +1,527 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with Slack using agent-slack.
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Post a notification or update to a channel
+
+```bash
+#!/bin/bash
+
+# Direct approach - use channel name
+agent-slack message send general "Deployment completed successfully!"
+
+# With error handling
+RESULT=$(agent-slack message send general "Hello world")
+if echo "$RESULT" | jq -e '.success' > /dev/null; then
+  echo "Message sent!"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+  exit 1
+fi
+```
+
+**When to use**: Simple one-off messages where you know the channel name.
+
+## Pattern 2: Monitor Channel for New Messages
+
+**Use case**: Watch a channel and respond to new messages
+
+```bash
+#!/bin/bash
+
+CHANNEL="general"
+LAST_TS=""
+
+while true; do
+  # Get latest message
+  MESSAGES=$(agent-slack message list "$CHANNEL" --limit 1)
+  LATEST_TS=$(echo "$MESSAGES" | jq -r '.data.messages[0].ts')
+  
+  # Check if new message
+  if [ "$LATEST_TS" != "$LAST_TS" ] && [ -n "$LAST_TS" ]; then
+    TEXT=$(echo "$MESSAGES" | jq -r '.data.messages[0].text')
+    USER=$(echo "$MESSAGES" | jq -r '.data.messages[0].user')
+    
+    echo "New message from $USER: $TEXT"
+    
+    # Process message here
+    # Example: Respond to mentions
+    if echo "$TEXT" | grep -q "@bot"; then
+      agent-slack message send "$CHANNEL" "You called?" --thread "$LATEST_TS"
+    fi
+  fi
+  
+  LAST_TS="$LATEST_TS"
+  sleep 5
+done
+```
+
+**When to use**: Building a simple bot that reacts to messages.
+
+**Limitations**: Polling-based, not real-time. For production bots, use Slack's Events API.
+
+## Pattern 3: Get Workspace Overview
+
+**Use case**: Understand workspace state before taking action
+
+```bash
+#!/bin/bash
+
+# Get full snapshot
+SNAPSHOT=$(agent-slack snapshot)
+
+# Extract key information
+WORKSPACE_NAME=$(echo "$SNAPSHOT" | jq -r '.data.workspace.name')
+CHANNEL_COUNT=$(echo "$SNAPSHOT" | jq -r '.data.channels | length')
+USER_COUNT=$(echo "$SNAPSHOT" | jq -r '.data.users | length')
+
+echo "Workspace: $WORKSPACE_NAME"
+echo "Channels: $CHANNEL_COUNT"
+echo "Users: $USER_COUNT"
+
+# List all channels
+echo -e "\nChannels:"
+echo "$SNAPSHOT" | jq -r '.channels[] | "  \(.name) (\(.id))"'
+
+# List recent activity
+echo -e "\nRecent messages:"
+echo "$SNAPSHOT" | jq -r '.data.messages[] | "  \(.channel_name): \(.text[0:50])"'
+```
+
+**When to use**: Initial context gathering, status reports, workspace summaries.
+
+## Pattern 4: Thread Conversation
+
+**Use case**: Reply to a message in a thread
+
+```bash
+#!/bin/bash
+
+CHANNEL="general"
+
+# Send initial message
+RESULT=$(agent-slack message send "$CHANNEL" "Starting deployment...")
+THREAD_TS=$(echo "$RESULT" | jq -r '.data.ts')
+
+# Send updates in thread
+agent-slack message send "$CHANNEL" "Building application..." --thread "$THREAD_TS"
+sleep 2
+agent-slack message send "$CHANNEL" "Running tests..." --thread "$THREAD_TS"
+sleep 2
+agent-slack message send "$CHANNEL" "Deploying to production..." --thread "$THREAD_TS"
+sleep 2
+agent-slack message send "$CHANNEL" "✅ Deployment complete!" --thread "$THREAD_TS"
+
+# Add reaction to parent message
+agent-slack reaction add "$CHANNEL" "$THREAD_TS" white_check_mark
+```
+
+**When to use**: Multi-step processes, progress updates, keeping related messages together.
+
+## Pattern 5: Search and Respond
+
+**Use case**: Find specific messages and take action
+
+```bash
+#!/bin/bash
+
+CHANNEL="support"
+
+# Get recent messages
+MESSAGES=$(agent-slack message list "$CHANNEL" --limit 50)
+
+# Find messages containing "urgent"
+URGENT_MESSAGES=$(echo "$MESSAGES" | jq -r '.data.messages[] | select(.text | contains("urgent"))')
+
+# Process each urgent message
+echo "$URGENT_MESSAGES" | jq -c '.' | while read -r msg; do
+  TS=$(echo "$msg" | jq -r '.ts')
+  TEXT=$(echo "$msg" | jq -r '.text')
+  USER=$(echo "$msg" | jq -r '.user')
+  
+  echo "Found urgent message from $USER: $TEXT"
+  
+  # Add eyes reaction to acknowledge
+  agent-slack reaction add "$CHANNEL" "$TS" eyes
+  
+  # Reply in thread
+  agent-slack message send "$CHANNEL" "I've flagged this for the team!" --thread "$TS"
+done
+```
+
+**When to use**: Automated triage, keyword monitoring, support automation.
+
+## Pattern 6: Multi-Channel Broadcast
+
+**Use case**: Send the same message to multiple channels
+
+```bash
+#!/bin/bash
+
+MESSAGE="🚨 System maintenance in 30 minutes"
+CHANNELS=("general" "engineering" "ops")
+
+for channel in "${CHANNELS[@]}"; do
+  echo "Posting to #$channel..."
+  RESULT=$(agent-slack message send "$channel" "$MESSAGE")
+  
+  if echo "$RESULT" | jq -e '.success' > /dev/null; then
+    echo "  ✓ Posted to #$channel"
+  else
+    echo "  ✗ Failed to post to #$channel"
+  fi
+  
+  # Rate limit: Don't spam Slack API
+  sleep 1
+done
+```
+
+**When to use**: Announcements, alerts, status updates across teams.
+
+## Pattern 7: File Upload with Context
+
+**Use case**: Share a file with explanation
+
+```bash
+#!/bin/bash
+
+CHANNEL="engineering"
+REPORT_FILE="./daily-report.pdf"
+
+# Upload file
+UPLOAD_RESULT=$(agent-slack file upload "$CHANNEL" "$REPORT_FILE")
+
+if echo "$UPLOAD_RESULT" | jq -e '.success' > /dev/null; then
+  FILE_ID=$(echo "$UPLOAD_RESULT" | jq -r '.data.id')
+  echo "File uploaded: $FILE_ID"
+  
+  # Send context message
+  agent-slack message send "$CHANNEL" "📊 Daily report is ready! Key highlights:
+  • 95% test coverage
+  • 3 bugs fixed
+  • 2 new features deployed"
+else
+  echo "Upload failed: $(echo "$UPLOAD_RESULT" | jq -r '.error.message')"
+  exit 1
+fi
+```
+
+**When to use**: Automated reporting, log sharing, artifact distribution.
+
+## Pattern 8: User Lookup and Mention
+
+**Use case**: Find a user and mention them in a message
+
+```bash
+#!/bin/bash
+
+CHANNEL="general"
+USERNAME="john.doe"
+
+# Get user info
+USERS=$(agent-slack user list)
+USER_ID=$(echo "$USERS" | jq -r ".data.users[] | select(.name==\"$USERNAME\") | .id")
+
+if [ -z "$USER_ID" ]; then
+  echo "User $USERNAME not found"
+  exit 1
+fi
+
+# Send message with mention
+agent-slack message send "$CHANNEL" "Hey <@$USER_ID>, the build is ready for review!"
+```
+
+**When to use**: Notifications, task assignments, code review requests.
+
+**Note**: Slack mentions require actual user IDs (e.g., `<@U06WXYZ5678>`).
+
+## Pattern 9: Reaction-Based Workflow
+
+**Use case**: Use reactions as simple state indicators
+
+```bash
+#!/bin/bash
+
+CHANNEL="deployments"
+
+# Send deployment message
+RESULT=$(agent-slack message send "$CHANNEL" "Deploying v2.1.0 to production...")
+MSG_TS=$(echo "$RESULT" | jq -r '.data.ts')
+
+# Mark as in-progress
+agent-slack reaction add "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
+
+# Simulate deployment
+sleep 5
+
+# Remove in-progress, add success
+agent-slack reaction remove "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
+agent-slack reaction add "$CHANNEL" "$MSG_TS" white_check_mark
+
+# Update message
+agent-slack message update "$CHANNEL" "$MSG_TS" "✅ Deployed v2.1.0 to production successfully!"
+```
+
+**When to use**: Visual status tracking, workflow states, quick acknowledgments.
+
+## Pattern 10: Error Handling and Retry
+
+**Use case**: Robust message sending with retries
+
+```bash
+#!/bin/bash
+
+send_with_retry() {
+  local channel=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+  
+  while [ $attempt -le $max_attempts ]; do
+    echo "Attempt $attempt/$max_attempts..."
+    
+    RESULT=$(agent-slack message send "$channel" "$message")
+    
+    if echo "$RESULT" | jq -e '.success' > /dev/null; then
+      echo "Message sent successfully!"
+      return 0
+    fi
+    
+    ERROR_CODE=$(echo "$RESULT" | jq -r '.error.code')
+    
+    # Don't retry on certain errors
+    if [ "$ERROR_CODE" = "INVALID_CHANNEL" ]; then
+      echo "Channel not found - not retrying"
+      return 1
+    fi
+    
+    echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+    
+    if [ $attempt -lt $max_attempts ]; then
+      sleep $((attempt * 2))  # Exponential backoff
+    fi
+    
+    attempt=$((attempt + 1))
+  done
+  
+  echo "Failed after $max_attempts attempts"
+  return 1
+}
+
+# Usage
+send_with_retry "general" "Important message!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Pattern 11: Daily Digest
+
+**Use case**: Summarize channel activity
+
+```bash
+#!/bin/bash
+
+CHANNEL="engineering"
+HOURS_AGO=24
+
+# Calculate timestamp for 24 hours ago
+OLDEST_TS=$(date -u -v-${HOURS_AGO}H +%s)
+
+# Get messages
+MESSAGES=$(agent-slack message list "$CHANNEL" --limit 100)
+
+# Filter messages from last 24 hours
+RECENT=$(echo "$MESSAGES" | jq --arg oldest "$OLDEST_TS" '
+  .data.messages[] | 
+  select((.ts | tonumber) > ($oldest | tonumber))
+')
+
+# Count messages
+MSG_COUNT=$(echo "$RECENT" | jq -s 'length')
+
+# Count unique users
+USER_COUNT=$(echo "$RECENT" | jq -s '[.[].user] | unique | length')
+
+# Build digest
+DIGEST="📊 Daily Digest for #$CHANNEL
+
+Messages: $MSG_COUNT
+Active users: $USER_COUNT
+
+Top messages:"
+
+# Add top 3 messages
+TOP_MESSAGES=$(echo "$RECENT" | jq -s 'sort_by(.reaction_count) | reverse | .[0:3]')
+
+echo "$TOP_MESSAGES" | jq -r '.[] | "• \(.text[0:100])"' | while read -r line; do
+  DIGEST="$DIGEST
+$line"
+done
+
+# Send digest
+agent-slack message send "$CHANNEL" "$DIGEST"
+```
+
+**When to use**: Daily summaries, activity reports, team updates.
+
+## Pattern 12: Conditional Messaging
+
+**Use case**: Send message only if condition is met
+
+```bash
+#!/bin/bash
+
+CHANNEL="alerts"
+
+# Check some condition (e.g., disk space)
+DISK_USAGE=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')
+
+if [ "$DISK_USAGE" -gt 80 ]; then
+  agent-slack message send "$CHANNEL" "⚠️ Disk usage is at ${DISK_USAGE}%! Please investigate."
+  
+  # Add urgent reaction
+  RESULT=$(agent-slack message list "$CHANNEL" --limit 1)
+  MSG_TS=$(echo "$RESULT" | jq -r '.data.messages[0].ts')
+  agent-slack reaction add "$CHANNEL" "$MSG_TS" rotating_light
+fi
+```
+
+**When to use**: Alerts, threshold monitoring, conditional notifications.
+
+## Best Practices
+
+### 1. Always Check Success
+
+```bash
+# Good
+RESULT=$(agent-slack message send general "Hello")
+if echo "$RESULT" | jq -e '.success' > /dev/null; then
+  echo "Success!"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+fi
+
+# Bad
+agent-slack message send general "Hello"  # No error checking
+```
+
+### 2. Use Channel Names for Simplicity
+
+```bash
+# Good - readable and maintainable
+agent-slack message send general "Hello"
+
+# Also good - use ID from snapshot
+SNAPSHOT=$(agent-slack snapshot)
+CHANNEL_ID=$(echo "$SNAPSHOT" | jq -r '.channels[0].id')
+agent-slack message send "$CHANNEL_ID" "Hello"
+
+# Bad - hardcoded IDs in scripts
+agent-slack message send C06ABCD1234 "Hello"
+```
+
+### 3. Rate Limit Your Requests
+
+```bash
+# Good - respect Slack API limits
+for channel in "${CHANNELS[@]}"; do
+  agent-slack message send "$channel" "$MESSAGE"
+  sleep 1  # 1 second between requests
+done
+
+# Bad - rapid-fire requests
+for channel in "${CHANNELS[@]}"; do
+  agent-slack message send "$channel" "$MESSAGE"
+done
+```
+
+### 4. Keep Threads Organized
+
+```bash
+# Good - use threads for related messages
+PARENT_TS=$(agent-slack message send general "Task started" | jq -r '.data.ts')
+agent-slack message send general "Step 1 complete" --thread "$PARENT_TS"
+agent-slack message send general "Step 2 complete" --thread "$PARENT_TS"
+
+# Bad - spam channel with separate messages
+agent-slack message send general "Task started"
+agent-slack message send general "Step 1 complete"
+agent-slack message send general "Step 2 complete"
+```
+
+### 5. Use Reactions for Quick Feedback
+
+```bash
+# Good - reactions are lightweight
+agent-slack reaction add general "$MSG_TS" thumbsup
+
+# Okay - but verbose
+agent-slack message send general "Acknowledged!" --thread "$MSG_TS"
+```
+
+## Anti-Patterns
+
+### ❌ Don't Poll Too Frequently
+
+```bash
+# Bad - polls every second
+while true; do
+  agent-slack message list general --limit 1
+  sleep 1
+done
+
+# Good - reasonable interval
+while true; do
+  agent-slack message list general --limit 1
+  sleep 30  # 30 seconds
+done
+```
+
+### ❌ Don't Hardcode IDs
+
+```bash
+# Bad
+agent-slack message send C06ABCD1234 "Hello"
+
+# Good
+agent-slack message send general "Hello"
+```
+
+### ❌ Don't Ignore Errors
+
+```bash
+# Bad
+agent-slack message send general "Hello"
+# Continues even if it failed
+
+# Good
+if ! agent-slack message send general "Hello" | jq -e '.success' > /dev/null; then
+  echo "Failed to send message"
+  exit 1
+fi
+```
+
+### ❌ Don't Spam Channels
+
+```bash
+# Bad - sends 100 messages
+for i in {1..100}; do
+  agent-slack message send general "Message $i"
+done
+
+# Good - batch into single message
+MESSAGE="Updates:\n"
+for i in {1..100}; do
+  MESSAGE="$MESSAGE\n$i. Item $i"
+done
+agent-slack message send general "$MESSAGE"
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up credentials
+- [Templates](../templates/) - Runnable example scripts

package/skills/agent-slack/templates/monitor-channel.sh

@@ -0,0 +1,186 @@
+#!/bin/bash
+#
+# monitor-channel.sh - Monitor a Slack channel for new messages
+#
+# Usage:
+#   ./monitor-channel.sh <channel> [interval]
+#
+# Arguments:
+#   channel  - Channel name or ID to monitor
+#   interval - Polling interval in seconds (default: 10)
+#
+# Example:
+#   ./monitor-channel.sh general
+#   ./monitor-channel.sh engineering 5
+
+set -euo pipefail
+
+# Check arguments
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 <channel> [interval]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 general          # Monitor #general, poll every 10s"
+  echo "  $0 engineering 5    # Monitor #engineering, poll every 5s"
+  exit 1
+fi
+
+CHANNEL="$1"
+INTERVAL="${2:-10}"  # Default 10 seconds
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# State tracking
+LAST_TS=""
+FIRST_RUN=true
+
+# Function to format timestamp
+format_time() {
+  local ts=$1
+  # Extract seconds part (before decimal)
+  local seconds=${ts%.*}
+  date -r "$seconds" "+%Y-%m-%d %H:%M:%S"
+}
+
+# Function to truncate text
+truncate_text() {
+  local text=$1
+  local max_length=100
+  
+  if [ ${#text} -gt $max_length ]; then
+    echo "${text:0:$max_length}..."
+  else
+    echo "$text"
+  fi
+}
+
+# Function to check for new messages
+check_messages() {
+  # Get latest message
+  MESSAGES=$(agent-slack message list "$CHANNEL" --limit 1 2>&1)
+  
+  # Check if successful
+  if ! echo "$MESSAGES" | jq -e '.success' > /dev/null 2>&1; then
+    ERROR_MSG=$(echo "$MESSAGES" | jq -r '.error.message // "Unknown error"')
+    echo -e "${RED}Error: $ERROR_MSG${NC}"
+    return 1
+  fi
+  
+  # Extract latest message
+  LATEST_TS=$(echo "$MESSAGES" | jq -r '.data.messages[0].ts // ""')
+  
+  # No messages in channel
+  if [ -z "$LATEST_TS" ]; then
+    if [ "$FIRST_RUN" = true ]; then
+      echo -e "${YELLOW}No messages in channel yet${NC}"
+    fi
+    return 0
+  fi
+  
+  # Check if new message
+  if [ "$LATEST_TS" != "$LAST_TS" ]; then
+    # Skip notification on first run (just initialize)
+    if [ "$FIRST_RUN" = false ] && [ -n "$LAST_TS" ]; then
+      # Extract message details
+      TEXT=$(echo "$MESSAGES" | jq -r '.data.messages[0].text // ""')
+      USER_ID=$(echo "$MESSAGES" | jq -r '.data.messages[0].user // ""')
+      
+      # Get user name
+      if [ -n "$USER_ID" ]; then
+        USER_INFO=$(agent-slack user info "$USER_ID" 2>&1)
+        if echo "$USER_INFO" | jq -e '.success' > /dev/null 2>&1; then
+          USER_NAME=$(echo "$USER_INFO" | jq -r '.data.name // "Unknown"')
+        else
+          USER_NAME="Unknown"
+        fi
+      else
+        USER_NAME="Unknown"
+      fi
+      
+      # Format timestamp
+      TIME=$(format_time "$LATEST_TS")
+      
+      # Display new message
+      echo ""
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      echo -e "${BLUE}New message in #$CHANNEL${NC}"
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      echo -e "Time:    $TIME"
+      echo -e "From:    $USER_NAME"
+      echo -e "Message: $(truncate_text "$TEXT")"
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      
+      # Example: Auto-respond to mentions
+      # Uncomment to enable
+      # if echo "$TEXT" | grep -q "@bot"; then
+      #   echo -e "${YELLOW}Detected mention, responding...${NC}"
+      #   agent-slack message send "$CHANNEL" "You called?" --thread "$LATEST_TS"
+      # fi
+    fi
+    
+    LAST_TS="$LATEST_TS"
+  fi
+  
+  FIRST_RUN=false
+  return 0
+}
+
+# Check if agent-slack is installed
+if ! command -v agent-slack &> /dev/null; then
+  echo -e "${RED}Error: agent-slack not found${NC}"
+  echo ""
+  echo "Install it with:"
+  echo "  bun install -g agent-slack"
+  exit 1
+fi
+
+# Check authentication
+echo "Checking authentication..."
+AUTH_STATUS=$(agent-slack auth status 2>&1)
+
+if ! echo "$AUTH_STATUS" | jq -e '.success' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run this to authenticate:"
+  echo "  agent-slack auth extract"
+  exit 1
+fi
+
+WORKSPACE_NAME=$(echo "$AUTH_STATUS" | jq -r '.data.workspace_name // "Unknown"')
+echo -e "${GREEN}✓ Authenticated to: $WORKSPACE_NAME${NC}"
+echo ""
+
+# Verify channel exists
+echo "Verifying channel..."
+CHANNEL_INFO=$(agent-slack channel info "$CHANNEL" 2>&1)
+
+if ! echo "$CHANNEL_INFO" | jq -e '.success' > /dev/null 2>&1; then
+  echo -e "${RED}Channel '$CHANNEL' not found${NC}"
+  echo ""
+  echo "List available channels with:"
+  echo "  agent-slack channel list"
+  exit 1
+fi
+
+CHANNEL_NAME=$(echo "$CHANNEL_INFO" | jq -r '.data.name // "Unknown"')
+echo -e "${GREEN}✓ Monitoring: #$CHANNEL_NAME${NC}"
+echo ""
+
+# Start monitoring
+echo -e "${YELLOW}Monitoring for new messages (polling every ${INTERVAL}s)...${NC}"
+echo -e "${YELLOW}Press Ctrl+C to stop${NC}"
+echo ""
+
+# Trap Ctrl+C for clean exit
+trap 'echo -e "\n${YELLOW}Monitoring stopped${NC}"; exit 0' INT
+
+# Main monitoring loop
+while true; do
+  check_messages
+  sleep "$INTERVAL"
+done