agent-messenger 1.0.0

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

@@ -0,0 +1,455 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with Discord using agent-discord.
+
+**Important**: Discord uses Snowflake IDs (large numbers like `1234567890123456789`) for channels, messages, and users. You cannot use channel names directly - always get IDs from `channel list` first.
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Post a notification or update to a channel
+
+```bash
+#!/bin/bash
+
+# First, get channel ID from channel list
+CHANNELS=$(agent-discord channel list)
+CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="general") | .id')
+
+# Send message using channel ID
+agent-discord message send "$CHANNEL_ID" "Deployment completed successfully!"
+
+# With error handling
+RESULT=$(agent-discord message send "$CHANNEL_ID" "Hello world")
+if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+  echo "Message sent!"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
+  exit 1
+fi
+```
+
+**When to use**: Simple one-off messages after looking up the channel ID.
+
+## Pattern 2: Monitor Channel for New Messages
+
+**Use case**: Watch a channel and respond to new messages
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="1234567890123456789"
+LAST_ID=""
+
+while true; do
+  # Get latest message
+  MESSAGES=$(agent-discord message list "$CHANNEL_ID" --limit 1)
+  LATEST_ID=$(echo "$MESSAGES" | jq -r '.[0].id // ""')
+  
+  # Check if new message
+  if [ "$LATEST_ID" != "$LAST_ID" ] && [ -n "$LAST_ID" ]; then
+    CONTENT=$(echo "$MESSAGES" | jq -r '.[0].content')
+    AUTHOR=$(echo "$MESSAGES" | jq -r '.[0].author')
+    
+    echo "New message from $AUTHOR: $CONTENT"
+    
+    # Process message here
+    # Example: Respond to mentions
+    if echo "$CONTENT" | grep -q "bot"; then
+      agent-discord message send "$CHANNEL_ID" "You called?"
+    fi
+  fi
+  
+  LAST_ID="$LATEST_ID"
+  sleep 5
+done
+```
+
+**When to use**: Building a simple bot that reacts to messages.
+
+**Limitations**: Polling-based, not real-time. For production bots, use Discord's Gateway API with a proper bot token.
+
+## Pattern 3: Get Guild Overview
+
+**Use case**: Understand server state before taking action
+
+```bash
+#!/bin/bash
+
+# Get full snapshot
+SNAPSHOT=$(agent-discord snapshot)
+
+# Extract key information
+GUILD_NAME=$(echo "$SNAPSHOT" | jq -r '.guild.name')
+CHANNEL_COUNT=$(echo "$SNAPSHOT" | jq -r '.channels | length')
+MEMBER_COUNT=$(echo "$SNAPSHOT" | jq -r '.members | length')
+
+echo "Server: $GUILD_NAME"
+echo "Channels: $CHANNEL_COUNT"
+echo "Members: $MEMBER_COUNT"
+
+# List all text channels
+echo -e "\nChannels:"
+echo "$SNAPSHOT" | jq -r '.channels[] | "  #\(.name) (\(.id))"'
+
+# List recent activity
+echo -e "\nRecent messages:"
+echo "$SNAPSHOT" | jq -r '.recent_messages[] | "  [\(.channel_name)] \(.author): \(.content[0:50])"'
+```
+
+**When to use**: Initial context gathering, status reports, server summaries.
+
+## Pattern 4: Find Channel by Name
+
+**Use case**: Get channel ID from channel name
+
+```bash
+#!/bin/bash
+
+get_channel_id() {
+  local channel_name=$1
+  
+  CHANNELS=$(agent-discord channel list)
+  CHANNEL_ID=$(echo "$CHANNELS" | jq -r --arg name "$channel_name" '.[] | select(.name==$name) | .id')
+  
+  if [ -z "$CHANNEL_ID" ]; then
+    echo "Channel #$channel_name not found" >&2
+    return 1
+  fi
+  
+  echo "$CHANNEL_ID"
+}
+
+# Usage
+GENERAL_ID=$(get_channel_id "general")
+if [ $? -eq 0 ]; then
+  agent-discord message send "$GENERAL_ID" "Hello!"
+fi
+```
+
+**When to use**: When you know channel name but need the ID.
+
+## Pattern 5: Multi-Channel Broadcast
+
+**Use case**: Send the same message to multiple channels
+
+```bash
+#!/bin/bash
+
+MESSAGE="System maintenance in 30 minutes"
+CHANNEL_NAMES=("general" "announcements" "dev")
+
+# Get all channels once
+CHANNELS=$(agent-discord channel list)
+
+for name in "${CHANNEL_NAMES[@]}"; do
+  CHANNEL_ID=$(echo "$CHANNELS" | jq -r --arg n "$name" '.[] | select(.name==$n) | .id')
+  
+  if [ -z "$CHANNEL_ID" ]; then
+    echo "Channel #$name not found, skipping"
+    continue
+  fi
+  
+  echo "Posting to #$name..."
+  RESULT=$(agent-discord message send "$CHANNEL_ID" "$MESSAGE")
+  
+  if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+    echo "  Posted to #$name"
+  else
+    echo "  Failed to post to #$name"
+  fi
+  
+  # Rate limit: Don't spam Discord API
+  sleep 1
+done
+```
+
+**When to use**: Announcements, alerts, status updates across channels.
+
+## Pattern 6: File Upload with Context
+
+**Use case**: Share a file with explanation
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="1234567890123456789"
+REPORT_FILE="./daily-report.pdf"
+
+# Upload file
+UPLOAD_RESULT=$(agent-discord file upload "$CHANNEL_ID" "$REPORT_FILE")
+
+if echo "$UPLOAD_RESULT" | jq -e '.id' > /dev/null 2>&1; then
+  FILE_ID=$(echo "$UPLOAD_RESULT" | jq -r '.id')
+  echo "File uploaded: $FILE_ID"
+  
+  # Send context message
+  agent-discord message send "$CHANNEL_ID" "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')"
+  exit 1
+fi
+```
+
+**When to use**: Automated reporting, log sharing, artifact distribution.
+
+## Pattern 7: User Lookup and Mention
+
+**Use case**: Find a user and mention them in a message
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="1234567890123456789"
+USERNAME="john"
+
+# Get guild members
+USERS=$(agent-discord user list)
+USER_ID=$(echo "$USERS" | jq -r --arg name "$USERNAME" '.[] | select(.username | contains($name)) | .id' | head -1)
+
+if [ -z "$USER_ID" ]; then
+  echo "User $USERNAME not found"
+  exit 1
+fi
+
+# Send message with mention
+agent-discord message send "$CHANNEL_ID" "Hey <@$USER_ID>, the build is ready for review!"
+```
+
+**When to use**: Notifications, task assignments, code review requests.
+
+**Note**: Discord mentions use format `<@USER_ID>`.
+
+## Pattern 8: Reaction-Based Workflow
+
+**Use case**: Use reactions as simple state indicators
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="1234567890123456789"
+
+# Send deployment message
+RESULT=$(agent-discord message send "$CHANNEL_ID" "Deploying v2.1.0 to production...")
+MSG_ID=$(echo "$RESULT" | jq -r '.id')
+
+# Mark as in-progress
+agent-discord reaction add "$CHANNEL_ID" "$MSG_ID" "hourglass"
+
+# Simulate deployment
+sleep 5
+
+# Remove in-progress, add success
+agent-discord reaction remove "$CHANNEL_ID" "$MSG_ID" "hourglass"
+agent-discord reaction add "$CHANNEL_ID" "$MSG_ID" "white_check_mark"
+
+# Send completion message
+agent-discord message send "$CHANNEL_ID" "Deployed v2.1.0 to production successfully!"
+```
+
+**When to use**: Visual status tracking, workflow states, quick acknowledgments.
+
+## Pattern 9: Error Handling and Retry
+
+**Use case**: Robust message sending with retries
+
+```bash
+#!/bin/bash
+
+send_with_retry() {
+  local channel_id=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+  
+  while [ $attempt -le $max_attempts ]; do
+    echo "Attempt $attempt/$max_attempts..."
+    
+    RESULT=$(agent-discord message send "$channel_id" "$message")
+    
+    if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+      echo "Message sent successfully!"
+      return 0
+    fi
+    
+    ERROR=$(echo "$RESULT" | jq -r '.error // "Unknown error"')
+    echo "Failed: $ERROR"
+    
+    # Don't retry on certain errors
+    if echo "$ERROR" | grep -q "Unknown Channel"; then
+      echo "Channel not found - not retrying"
+      return 1
+    fi
+    
+    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
+CHANNEL_ID="1234567890123456789"
+send_with_retry "$CHANNEL_ID" "Important message!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Pattern 10: Switch Guilds for Operations
+
+**Use case**: Work with multiple Discord servers
+
+```bash
+#!/bin/bash
+
+# List all guilds
+GUILDS=$(agent-discord guild list)
+echo "Available guilds:"
+echo "$GUILDS" | jq -r '.[] | "  \(.name) (\(.id)) \(if .current then "[current]" else "" end)"'
+
+# Switch to a specific guild
+TARGET_GUILD=$(echo "$GUILDS" | jq -r '.[] | select(.name | contains("Production")) | .id')
+if [ -n "$TARGET_GUILD" ]; then
+  agent-discord guild switch "$TARGET_GUILD"
+  echo "Switched to Production guild"
+fi
+
+# Now operations use the new guild
+agent-discord channel list
+```
+
+**When to use**: Managing multiple servers, cross-server operations.
+
+## Best Practices
+
+### 1. Always Get Channel IDs First
+
+```bash
+# Good - look up channel ID
+CHANNELS=$(agent-discord channel list)
+CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="general") | .id')
+agent-discord message send "$CHANNEL_ID" "Hello"
+
+# Bad - hardcoded IDs without documentation
+agent-discord message send 1234567890123456789 "Hello"
+```
+
+### 2. Check for Success
+
+```bash
+# Good
+RESULT=$(agent-discord message send "$CHANNEL_ID" "Hello")
+if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+  echo "Success!"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
+fi
+
+# Bad
+agent-discord message send "$CHANNEL_ID" "Hello"  # No error checking
+```
+
+### 3. Rate Limit Your Requests
+
+```bash
+# Good - respect Discord API limits
+for channel_id in "${CHANNEL_IDS[@]}"; do
+  agent-discord message send "$channel_id" "$MESSAGE"
+  sleep 1  # 1 second between requests
+done
+
+# Bad - rapid-fire requests
+for channel_id in "${CHANNEL_IDS[@]}"; do
+  agent-discord message send "$channel_id" "$MESSAGE"
+done
+```
+
+### 4. Cache Channel Lists
+
+```bash
+# Good - fetch once, reuse
+CHANNELS=$(agent-discord channel list)
+for name in "${CHANNEL_NAMES[@]}"; do
+  id=$(echo "$CHANNELS" | jq -r --arg n "$name" '.[] | select(.name==$n) | .id')
+  agent-discord message send "$id" "$MESSAGE"
+done
+
+# Bad - fetch repeatedly
+for name in "${CHANNEL_NAMES[@]}"; do
+  CHANNELS=$(agent-discord channel list)  # Wasteful!
+  id=$(echo "$CHANNELS" | jq -r --arg n "$name" '.[] | select(.name==$n) | .id')
+  agent-discord message send "$id" "$MESSAGE"
+done
+```
+
+### 5. Use Reactions for Quick Feedback
+
+```bash
+# Good - reactions are lightweight
+agent-discord reaction add "$CHANNEL_ID" "$MSG_ID" "thumbsup"
+
+# Okay - but more verbose for simple acknowledgment
+agent-discord message send "$CHANNEL_ID" "Acknowledged!"
+```
+
+## Anti-Patterns
+
+### Don't Poll Too Frequently
+
+```bash
+# Bad - polls every second (may get rate limited)
+while true; do
+  agent-discord message list "$CHANNEL_ID" --limit 1
+  sleep 1
+done
+
+# Good - reasonable interval
+while true; do
+  agent-discord message list "$CHANNEL_ID" --limit 1
+  sleep 10  # 10 seconds
+done
+```
+
+### Don't Ignore Errors
+
+```bash
+# Bad
+agent-discord message send "$CHANNEL_ID" "Hello"
+# Continues even if it failed
+
+# Good
+RESULT=$(agent-discord message send "$CHANNEL_ID" "Hello")
+if ! echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; 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-discord message send "$CHANNEL_ID" "Message $i"
+done
+
+# Good - batch into single message
+MESSAGE="Updates:"
+for i in {1..100}; do
+  MESSAGE="$MESSAGE\n$i. Item $i"
+done
+agent-discord message send "$CHANNEL_ID" "$MESSAGE"
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up credentials
+- [Templates](../templates/) - Runnable example scripts

package/skills/agent-discord/templates/guild-summary.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+#
+# guild-summary.sh - Generate a comprehensive Discord guild summary
+#
+# Usage:
+#   ./guild-summary.sh [--json]
+#
+# Options:
+#   --json  Output raw JSON instead of formatted text
+#
+# Example:
+#   ./guild-summary.sh
+#   ./guild-summary.sh --json > summary.json
+
+set -euo pipefail
+
+OUTPUT_JSON=false
+if [ $# -gt 0 ] && [ "$1" = "--json" ]; then
+  OUTPUT_JSON=true
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+if ! command -v agent-discord &> /dev/null; then
+  echo -e "${RED}Error: agent-discord not found${NC}" >&2
+  echo "" >&2
+  echo "Install it with:" >&2
+  echo "  bun install -g agent-discord" >&2
+  exit 1
+fi
+
+AUTH_STATUS=$(agent-discord auth status 2>&1)
+
+if echo "$AUTH_STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}" >&2
+  echo "" >&2
+  echo "Run this to authenticate:" >&2
+  echo "  agent-discord auth extract" >&2
+  exit 1
+fi
+
+CURRENT_GUILD=$(echo "$AUTH_STATUS" | jq -r '.current_guild // ""')
+if [ -z "$CURRENT_GUILD" ]; then
+  echo -e "${RED}No guild selected!${NC}" >&2
+  echo "" >&2
+  echo "Run this to select a guild:" >&2
+  echo "  agent-discord guild list" >&2
+  echo "  agent-discord guild switch <guild-id>" >&2
+  exit 1
+fi
+
+echo -e "${YELLOW}Fetching guild snapshot...${NC}" >&2
+SNAPSHOT=$(agent-discord snapshot 2>&1)
+
+if echo "$SNAPSHOT" | jq -e '.error' > /dev/null 2>&1; then
+  echo -e "${RED}Failed to get snapshot${NC}" >&2
+  ERROR_MSG=$(echo "$SNAPSHOT" | jq -r '.error // "Unknown error"')
+  echo -e "${RED}Error: $ERROR_MSG${NC}" >&2
+  exit 1
+fi
+
+if [ "$OUTPUT_JSON" = true ]; then
+  echo "$SNAPSHOT"
+  exit 0
+fi
+
+GUILD_NAME=$(echo "$SNAPSHOT" | jq -r '.guild.name // "Unknown"')
+GUILD_ID=$(echo "$SNAPSHOT" | jq -r '.guild.id // "Unknown"')
+
+CHANNELS=$(echo "$SNAPSHOT" | jq '.channels // []')
+CHANNEL_COUNT=$(echo "$CHANNELS" | jq 'length')
+TEXT_COUNT=$(echo "$CHANNELS" | jq '[.[] | select(.type == 0)] | length')
+VOICE_COUNT=$(echo "$CHANNELS" | jq '[.[] | select(.type == 2)] | length')
+CATEGORY_COUNT=$(echo "$CHANNELS" | jq '[.[] | select(.type == 4)] | length')
+
+MEMBERS=$(echo "$SNAPSHOT" | jq '.members // []')
+MEMBER_COUNT=$(echo "$MEMBERS" | jq 'length')
+
+MESSAGES=$(echo "$SNAPSHOT" | jq '.recent_messages // []')
+MESSAGE_COUNT=$(echo "$MESSAGES" | jq 'length')
+
+echo ""
+echo -e "${BOLD}${BLUE}=====================================================${NC}"
+echo -e "${BOLD}${BLUE}  Discord Guild Summary${NC}"
+echo -e "${BOLD}${BLUE}=====================================================${NC}"
+echo ""
+echo -e "${BOLD}Guild:${NC}     $GUILD_NAME"
+echo -e "${BOLD}ID:${NC}        $GUILD_ID"
+echo ""
+
+echo -e "${BOLD}${CYAN}Channels (${CHANNEL_COUNT} total)${NC}"
+echo -e "  Text:       $TEXT_COUNT"
+echo -e "  Voice:      $VOICE_COUNT"
+echo -e "  Categories: $CATEGORY_COUNT"
+echo ""
+
+echo -e "${BOLD}${CYAN}Text Channels:${NC}"
+echo "$CHANNELS" | jq -r '
+  [.[] | select(.type == 0)] | 
+  .[0:10] | 
+  .[] | 
+  "  #\(.name) (\(.id))"
+'
+if [ "$TEXT_COUNT" -gt 10 ]; then
+  echo "  ... and $((TEXT_COUNT - 10)) more"
+fi
+echo ""
+
+echo -e "${BOLD}${CYAN}Members (${MEMBER_COUNT} shown)${NC}"
+echo ""
+
+echo -e "${BOLD}${CYAN}Sample Members:${NC}"
+echo "$MEMBERS" | jq -r '
+  .[0:10] | 
+  .[] | 
+  "  \(.username) \(if .global_name then "(\(.global_name))" else "" end) [\(.id)]"
+'
+if [ "$MEMBER_COUNT" -gt 10 ]; then
+  echo "  ... and $((MEMBER_COUNT - 10)) more"
+fi
+echo ""
+
+echo -e "${BOLD}${CYAN}Recent Activity (${MESSAGE_COUNT} messages)${NC}"
+echo ""
+
+if [ "$MESSAGE_COUNT" -gt 0 ]; then
+  echo -e "${BOLD}${CYAN}Latest Messages:${NC}"
+  echo "$MESSAGES" | jq -r '
+    .[0:5] | 
+    .[] | 
+    "  [#\(.channel_name)] \(.author): \(.content[0:50])\(if (.content | length) > 50 then "..." else "" end)"
+  '
+  echo ""
+fi
+
+echo -e "${BOLD}${CYAN}Quick Actions:${NC}"
+echo ""
+echo -e "  ${GREEN}# Send message to a channel${NC}"
+FIRST_CHANNEL=$(echo "$CHANNELS" | jq -r '[.[] | select(.type == 0)][0].id // "CHANNEL_ID"')
+FIRST_CHANNEL_NAME=$(echo "$CHANNELS" | jq -r '[.[] | select(.type == 0)][0].name // "general"')
+echo -e "  agent-discord message send $FIRST_CHANNEL \"Hello!\""
+echo ""
+echo -e "  ${GREEN}# List messages in #$FIRST_CHANNEL_NAME${NC}"
+echo -e "  agent-discord message list $FIRST_CHANNEL --limit 10"
+echo ""
+echo -e "  ${GREEN}# Get user info${NC}"
+FIRST_USER=$(echo "$MEMBERS" | jq -r '.[0].id // "USER_ID"')
+echo -e "  agent-discord user info $FIRST_USER"
+echo ""
+echo -e "  ${GREEN}# Switch to another guild${NC}"
+echo -e "  agent-discord guild list"
+echo -e "  agent-discord guild switch <guild-id>"
+echo ""
+
+echo -e "${BOLD}${BLUE}=====================================================${NC}"
+echo ""
+
+SNAPSHOT_FILE="guild-snapshot-$(date +%Y%m%d-%H%M%S).json"
+echo "$SNAPSHOT" > "$SNAPSHOT_FILE"
+echo -e "${GREEN}Full snapshot saved to: $SNAPSHOT_FILE${NC}"
+echo ""