agent-messenger 1.0.0 → 1.1.0

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

@@ -0,0 +1,596 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with Microsoft Teams using agent-teams.
+
+**Important**: Teams uses UUID-style channel IDs (like `19:abc123@thread.tacv2`). You cannot use channel names directly - always get IDs from `channel list` first.
+
+**CRITICAL**: Teams tokens expire in 60-90 minutes! All patterns include token refresh handling.
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Post a notification or update to a channel
+
+```bash
+#!/bin/bash
+
+# First, ensure token is valid
+agent-teams auth extract 2>/dev/null || true
+
+# Get channel ID from channel list
+CHANNELS=$(agent-teams channel list)
+CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="General") | .id')
+
+# Send message using channel ID
+agent-teams message send "$CHANNEL_ID" "Deployment completed successfully!"
+
+# With error handling
+RESULT=$(agent-teams message send "$CHANNEL_ID" "Hello world")
+if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+  echo "Message sent!"
+else
+  ERROR=$(echo "$RESULT" | jq -r '.error')
+  
+  # Handle token expiry
+  if echo "$ERROR" | grep -qi "expired\|401"; then
+    echo "Token expired, refreshing..."
+    agent-teams auth extract
+    agent-teams message send "$CHANNEL_ID" "Hello world"
+  else
+    echo "Failed: $ERROR"
+    exit 1
+  fi
+fi
+```
+
+**When to use**: Simple one-off messages after looking up the channel ID.
+
+## Pattern 2: Monitor Channel for New Messages (with Token Refresh)
+
+**Use case**: Watch a channel and respond to new messages
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="19:abc123@thread.tacv2"
+LAST_ID=""
+TOKEN_CHECK_INTERVAL=300  # Check token every 5 minutes
+
+last_token_check=$(date +%s)
+
+refresh_token_if_needed() {
+  local now=$(date +%s)
+  local elapsed=$((now - last_token_check))
+  
+  if [ $elapsed -gt $TOKEN_CHECK_INTERVAL ]; then
+    STATUS=$(agent-teams auth status)
+    EXPIRES_SOON=$(echo "$STATUS" | jq -r '.token_expires_soon // true')
+    
+    if [ "$EXPIRES_SOON" = "true" ]; then
+      echo "Token expiring soon, refreshing..."
+      agent-teams auth extract
+    fi
+    
+    last_token_check=$now
+  fi
+}
+
+while true; do
+  # Proactively refresh token
+  refresh_token_if_needed
+  
+  # Get latest message
+  MESSAGES=$(agent-teams message list "$CHANNEL_ID" --limit 1)
+  
+  # Handle token expiry error
+  if echo "$MESSAGES" | jq -e '.error' | grep -qi "expired\|401" 2>/dev/null; then
+    echo "Token expired, refreshing..."
+    agent-teams auth extract
+    continue
+  fi
+  
+  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
+    if echo "$CONTENT" | grep -q "bot"; then
+      agent-teams 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. Token must be refreshed every 60-90 minutes.
+
+## Pattern 3: Get Team Overview
+
+**Use case**: Understand team state before taking action
+
+```bash
+#!/bin/bash
+
+# Ensure fresh token
+agent-teams auth extract 2>/dev/null || true
+
+# Get full snapshot
+SNAPSHOT=$(agent-teams snapshot)
+
+# Extract key information
+TEAM_NAME=$(echo "$SNAPSHOT" | jq -r '.team.name // "Unknown"')
+CHANNEL_COUNT=$(echo "$SNAPSHOT" | jq -r '.channels | length')
+MEMBER_COUNT=$(echo "$SNAPSHOT" | jq -r '.members | length')
+
+echo "Team: $TEAM_NAME"
+echo "Channels: $CHANNEL_COUNT"
+echo "Members: $MEMBER_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 '.recent_messages[] | "  [\(.channel_name)] \(.author): \(.content[0:50])"'
+```
+
+**When to use**: Initial context gathering, status reports, team 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-teams 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-teams 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" "Engineering")
+
+# Ensure fresh token before bulk operation
+agent-teams auth extract
+
+# Get all channels once
+CHANNELS=$(agent-teams 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-teams 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 Teams 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="19:abc123@thread.tacv2"
+REPORT_FILE="./daily-report.pdf"
+
+# Upload file
+UPLOAD_RESULT=$(agent-teams 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-teams 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="19:abc123@thread.tacv2"
+USERNAME="john"
+
+# Get team members
+USERS=$(agent-teams user list)
+USER=$(echo "$USERS" | jq -r --arg name "$USERNAME" 'first(.[] | select(.displayName | ascii_downcase | contains($name | ascii_downcase)))')
+USER_ID=$(echo "$USER" | jq -r '.id')
+USER_NAME=$(echo "$USER" | jq -r '.displayName')
+
+if [ -z "$USER_ID" ] || [ "$USER_ID" = "null" ]; then
+  echo "User $USERNAME not found"
+  exit 1
+fi
+
+# Send message with mention (Teams format)
+agent-teams message send "$CHANNEL_ID" "Hey <at id=\"$USER_ID\">$USER_NAME</at>, the build is ready for review!"
+```
+
+**When to use**: Notifications, task assignments, code review requests.
+
+**Note**: Teams mentions use format `<at id="USER_ID">Display Name</at>`.
+
+## Pattern 8: Reaction-Based Workflow
+
+**Use case**: Use reactions as simple state indicators
+
+```bash
+#!/bin/bash
+
+CHANNEL_ID="19:abc123@thread.tacv2"
+
+# Send deployment message
+RESULT=$(agent-teams message send "$CHANNEL_ID" "Deploying v2.1.0 to production...")
+MSG_ID=$(echo "$RESULT" | jq -r '.id')
+
+# Mark as in-progress
+agent-teams reaction add "$CHANNEL_ID" "$MSG_ID" "hourglass"
+
+# Simulate deployment
+sleep 5
+
+# Remove in-progress, add success
+agent-teams reaction remove "$CHANNEL_ID" "$MSG_ID" "hourglass"
+agent-teams reaction add "$CHANNEL_ID" "$MSG_ID" "checkmark"
+
+# Send completion message
+agent-teams 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 with Token Refresh
+
+**Use case**: Robust message sending with retries and token refresh
+
+```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-teams 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"
+    
+    # Handle token expiry - refresh and retry
+    if echo "$ERROR" | grep -qi "expired\|401\|unauthorized"; then
+      echo "Token expired, refreshing..."
+      agent-teams auth extract
+      # Don't count this as an attempt
+      continue
+    fi
+    
+    # Don't retry on certain errors
+    if echo "$ERROR" | grep -q "Channel not found"; 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="19:abc123@thread.tacv2"
+send_with_retry "$CHANNEL_ID" "Important message!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Pattern 10: Switch Teams for Operations
+
+**Use case**: Work with multiple Teams
+
+```bash
+#!/bin/bash
+
+# List all teams
+TEAMS=$(agent-teams team list)
+echo "Available teams:"
+echo "$TEAMS" | jq -r '.[] | "  \(.name) (\(.id)) \(if .current then "[current]" else "" end)"'
+
+# Switch to a specific team
+TARGET_TEAM=$(echo "$TEAMS" | jq -r '.[] | select(.name | contains("Production")) | .id')
+if [ -n "$TARGET_TEAM" ]; then
+  agent-teams team switch "$TARGET_TEAM"
+  echo "Switched to Production team"
+fi
+
+# Now operations use the new team
+agent-teams channel list
+```
+
+**When to use**: Managing multiple teams, cross-team operations.
+
+## Pattern 11: Token Refresh Wrapper (TEAMS-SPECIFIC)
+
+**Use case**: Wrap any operation with automatic token refresh
+
+```bash
+#!/bin/bash
+
+# Wrapper function that handles token refresh
+teams_cmd() {
+  local result
+  
+  # First attempt
+  result=$("$@" 2>&1)
+  
+  # Check for token expiry
+  if echo "$result" | grep -qi "expired\|401\|unauthorized"; then
+    echo "Token expired, refreshing..." >&2
+    agent-teams auth extract >&2
+    
+    # Retry
+    result=$("$@" 2>&1)
+  fi
+  
+  echo "$result"
+}
+
+# Usage - wrap any agent-teams command
+CHANNELS=$(teams_cmd agent-teams channel list)
+RESULT=$(teams_cmd agent-teams message send "$CHANNEL_ID" "Hello!")
+SNAPSHOT=$(teams_cmd agent-teams snapshot)
+```
+
+**When to use**: Any script that runs for more than a few minutes.
+
+## Best Practices
+
+### 1. Always Handle Token Expiry
+
+```bash
+# Good - handle token expiry
+RESULT=$(agent-teams message send "$CHANNEL_ID" "Hello")
+if echo "$RESULT" | grep -qi "expired\|401"; then
+  agent-teams auth extract
+  RESULT=$(agent-teams message send "$CHANNEL_ID" "Hello")
+fi
+
+# Bad - assume token is always valid
+agent-teams message send "$CHANNEL_ID" "Hello"
+```
+
+### 2. Refresh Token Proactively for Long-Running Scripts
+
+```bash
+# Good - check token age periodically
+while true; do
+  STATUS=$(agent-teams auth status)
+  if [ "$(echo "$STATUS" | jq -r '.token_expires_soon')" = "true" ]; then
+    agent-teams auth extract
+  fi
+  
+  # Do work...
+  sleep 60
+done
+
+# Bad - wait for failure
+while true; do
+  agent-teams message send "$CHANNEL_ID" "Status update"  # Will fail after 60-90 min
+  sleep 60
+done
+```
+
+### 3. Always Get Channel IDs First
+
+```bash
+# Good - look up channel ID
+CHANNELS=$(agent-teams channel list)
+CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="General") | .id')
+agent-teams message send "$CHANNEL_ID" "Hello"
+
+# Bad - hardcoded IDs without documentation
+agent-teams message send "19:abc123@thread.tacv2" "Hello"
+```
+
+### 4. Check for Success
+
+```bash
+# Good
+RESULT=$(agent-teams 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-teams message send "$CHANNEL_ID" "Hello"  # No error checking
+```
+
+### 5. Rate Limit Your Requests
+
+```bash
+# Good - respect Teams API limits
+for channel_id in "${CHANNEL_IDS[@]}"; do
+  agent-teams message send "$channel_id" "$MESSAGE"
+  sleep 1  # 1 second between requests
+done
+
+# Bad - rapid-fire requests
+for channel_id in "${CHANNEL_IDS[@]}"; do
+  agent-teams message send "$channel_id" "$MESSAGE"
+done
+```
+
+### 6. Cache Channel Lists
+
+```bash
+# Good - fetch once, reuse
+CHANNELS=$(agent-teams channel list)
+for name in "${CHANNEL_NAMES[@]}"; do
+  id=$(echo "$CHANNELS" | jq -r --arg n "$name" '.[] | select(.name==$n) | .id')
+  agent-teams message send "$id" "$MESSAGE"
+done
+
+# Bad - fetch repeatedly
+for name in "${CHANNEL_NAMES[@]}"; do
+  CHANNELS=$(agent-teams channel list)  # Wasteful!
+  id=$(echo "$CHANNELS" | jq -r --arg n "$name" '.[] | select(.name==$n) | .id')
+  agent-teams message send "$id" "$MESSAGE"
+done
+```
+
+## Anti-Patterns
+
+### Don't Ignore Token Expiry
+
+```bash
+# Bad - ignores the 60-90 minute token limit
+while true; do
+  agent-teams message list "$CHANNEL_ID" --limit 1
+  sleep 10
+done
+# Will fail silently after ~1 hour
+
+# Good - handle token refresh
+while true; do
+  # Check and refresh token periodically
+  if should_refresh_token; then
+    agent-teams auth extract
+  fi
+  
+  agent-teams message list "$CHANNEL_ID" --limit 1
+  sleep 10
+done
+```
+
+### Don't Poll Too Frequently
+
+```bash
+# Bad - polls every second (may get rate limited)
+while true; do
+  agent-teams message list "$CHANNEL_ID" --limit 1
+  sleep 1
+done
+
+# Good - reasonable interval
+while true; do
+  agent-teams message list "$CHANNEL_ID" --limit 1
+  sleep 10  # 10 seconds
+done
+```
+
+### Don't Ignore Errors
+
+```bash
+# Bad
+agent-teams message send "$CHANNEL_ID" "Hello"
+# Continues even if it failed
+
+# Good
+RESULT=$(agent-teams 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-teams 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-teams message send "$CHANNEL_ID" "$MESSAGE"
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up credentials and token management
+- [Templates](../templates/) - Runnable example scripts