agent-messenger 1.2.0 → 1.3.0

package/skills/agent-slackbot/references/authentication.md

@@ -0,0 +1,253 @@
+# Authentication Guide
+
+## Overview
+
+agent-slackbot uses Slack Bot tokens (xoxb-) obtained from the Slack App configuration page. Unlike agent-slack which extracts user tokens from the desktop app, bot tokens are explicitly created and managed through the Slack API portal.
+
+## Bot Token Setup
+
+### Creating a Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** > **From scratch**
+3. Enter app name and select workspace
+4. Go to **OAuth & Permissions**
+
+### Required Scopes
+
+Add these **Bot Token Scopes**:
+
+| Scope | Purpose |
+|-------|---------|
+| `chat:write` | Send and update messages |
+| `channels:history` | Read messages in public channels |
+| `channels:read` | List and get info for public channels |
+| `channels:join` | Join public channels |
+| `groups:history` | Read messages in private channels |
+| `groups:read` | List and get info for private channels |
+| `users:read` | List workspace users |
+| `users:read.email` | Access user email addresses |
+| `reactions:write` | Add and remove emoji reactions |
+| `reactions:read` | List reactions on messages |
+
+### Installing the App
+
+1. Click **Install to Workspace** on the OAuth & Permissions page
+2. Review and **Allow** the requested permissions
+3. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+
+### Setting the Token
+
+```bash
+# Basic setup
+agent-slackbot auth set xoxb-your-bot-token
+
+# With a custom bot identifier (for multi-bot setups)
+agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"
+```
+
+This command:
+1. Validates the token format (must start with `xoxb-`)
+2. Calls `auth.test` to verify the token against Slack API
+3. Stores the bot under the workspace with its bot ID and name
+4. Sets this bot as the current active bot
+5. Saves credentials to `~/.config/agent-messenger/slackbot-credentials.json`
+
+## Credential Storage
+
+### Location
+
+```
+~/.config/agent-messenger/slackbot-credentials.json
+```
+
+### Format
+
+```json
+{
+  "current": {
+    "workspace_id": "T123456",
+    "bot_id": "deploy"
+  },
+  "workspaces": {
+    "T123456": {
+      "workspace_id": "T123456",
+      "workspace_name": "My Workspace",
+      "bots": {
+        "deploy": {
+          "bot_id": "deploy",
+          "bot_name": "Deploy Bot",
+          "token": "xoxb-1234567890-1234567890-abcdef..."
+        }
+      }
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Token stored in plaintext (standard for CLI tools)
+- Keep this file secure - it grants bot-level access to your workspace
+
+## Environment Variables (CI/CD)
+
+For automated environments, use environment variables instead of file-based credentials:
+
+```bash
+export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
+export E2E_SLACKBOT_WORKSPACE_ID=T123456
+export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"
+```
+
+Environment variables take precedence over file-based credentials.
+
+## Multi-Bot Management
+
+Store and switch between multiple bot tokens:
+
+```bash
+# Add multiple bots
+agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
+agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"
+
+# List all stored bots
+agent-slackbot auth list
+
+# Switch active bot
+agent-slackbot auth use deploy
+
+# Use a specific bot for one command
+agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert
+
+# Remove a stored bot
+agent-slackbot auth remove deploy
+
+# Disambiguate across workspaces
+agent-slackbot auth use T123456/deploy
+```
+
+## Authentication Status
+
+Check current authentication state:
+
+```bash
+agent-slackbot auth status
+```
+
+Output when authenticated:
+```json
+{
+  "valid": true,
+  "workspace_id": "T123456",
+  "workspace_name": "My Workspace",
+  "bot_id": "deploy",
+  "bot_name": "Deploy Bot",
+  "user": "mybot",
+  "team": "My Workspace"
+}
+```
+
+Output when not authenticated:
+```json
+{
+  "valid": false,
+  "error": "No credentials configured. Run \"auth set <token>\" first."
+}
+```
+
+## Clearing Credentials
+
+Remove stored credentials:
+
+```bash
+agent-slackbot auth clear
+```
+
+## Token Lifecycle
+
+### When Tokens Stop Working
+
+Bot tokens can be invalidated when:
+- App is uninstalled from workspace
+- App is deleted from api.slack.com
+- Token is manually revoked
+- Required scopes change (need reinstall)
+
+### Re-authentication
+
+```bash
+# Get a new token from api.slack.com/apps > OAuth & Permissions
+agent-slackbot auth set xoxb-new-bot-token
+
+# Verify
+agent-slackbot auth status
+```
+
+## Troubleshooting
+
+### "not_in_channel" Error
+
+The bot must join a channel before posting messages to it:
+
+```bash
+# Bots auto-join public channels when posting via API if they have channels:join scope
+# For private channels, manually invite the bot from Slack UI
+```
+
+### "invalid_auth" Error
+
+Token is expired or revoked:
+1. Go to api.slack.com/apps > your app > OAuth & Permissions
+2. Check if the app is still installed
+3. Reinstall if needed and copy the new token
+4. Run `agent-slackbot auth set xoxb-new-token`
+
+### "missing_scope" Error
+
+The bot token lacks required permissions:
+1. Go to api.slack.com/apps > your app > OAuth & Permissions
+2. Add the missing scope under Bot Token Scopes
+3. Reinstall the app to workspace
+4. Copy the new token and run `agent-slackbot auth set xoxb-new-token`
+
+## App Manifest
+
+For quick setup, use this Slack App manifest:
+
+```yaml
+display_information:
+  name: Agent Messenger Bot
+  description: Bot for agent-messenger CLI integration
+  background_color: "#1a1a2e"
+
+features:
+  bot_user:
+    display_name: agent-messenger
+    always_online: false
+
+oauth_config:
+  scopes:
+    bot:
+      - chat:write
+      - channels:history
+      - channels:read
+      - channels:join
+      - groups:history
+      - groups:read
+      - users:read
+      - users:read.email
+      - reactions:write
+      - reactions:read
+
+settings:
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+```
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) > **Create New App** > **From an app manifest**
+2. Select workspace, paste YAML, create
+3. Install to workspace
+4. Copy Bot User OAuth Token

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

@@ -0,0 +1,218 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with Slack using agent-slackbot (bot tokens).
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Post a notification or update to a channel
+
+```bash
+#!/bin/bash
+
+CHANNEL="C0ACZKTDDC0"
+
+RESULT=$(agent-slackbot message send "$CHANNEL" "Deployment completed!")
+TS=$(echo "$RESULT" | jq -r '.ts')
+
+if [ -n "$TS" ] && [ "$TS" != "null" ]; then
+  echo "Message sent: $TS"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
+  exit 1
+fi
+```
+
+**When to use**: Simple one-off messages, notifications, alerts.
+
+## Pattern 2: Thread Conversation
+
+**Use case**: Send progress updates in a thread
+
+```bash
+#!/bin/bash
+
+CHANNEL="C0ACZKTDDC0"
+
+# Send initial message
+RESULT=$(agent-slackbot message send "$CHANNEL" "Starting deployment...")
+THREAD_TS=$(echo "$RESULT" | jq -r '.ts')
+
+# Send updates in thread
+agent-slackbot message send "$CHANNEL" "Building application..." --thread "$THREAD_TS"
+sleep 2
+agent-slackbot message send "$CHANNEL" "Running tests..." --thread "$THREAD_TS"
+sleep 2
+agent-slackbot message send "$CHANNEL" "Deploying to production..." --thread "$THREAD_TS"
+sleep 2
+
+# Update parent with final status
+agent-slackbot message update "$CHANNEL" "$THREAD_TS" "Deployment complete!"
+
+# Add reaction
+agent-slackbot reaction add "$CHANNEL" "$THREAD_TS" white_check_mark
+```
+
+**When to use**: Multi-step processes, CI/CD pipelines, progress tracking.
+
+## Pattern 3: Monitor Channel for New Messages
+
+**Use case**: Poll a channel and respond to new messages
+
+```bash
+#!/bin/bash
+
+CHANNEL="C0ACZKTDDC0"
+LAST_TS=""
+
+while true; do
+  MESSAGES=$(agent-slackbot message list "$CHANNEL" --limit 1)
+  LATEST_TS=$(echo "$MESSAGES" | jq -r '.[0].ts // ""')
+
+  if [ "$LATEST_TS" != "$LAST_TS" ] && [ -n "$LAST_TS" ]; then
+    TEXT=$(echo "$MESSAGES" | jq -r '.[0].text // ""')
+    echo "New message: $TEXT"
+
+    # Respond if needed
+    if echo "$TEXT" | grep -qi "help"; then
+      agent-slackbot message send "$CHANNEL" "How can I help?" --thread "$LATEST_TS"
+    fi
+  fi
+
+  LAST_TS="$LATEST_TS"
+  sleep 10
+done
+```
+
+**Limitations**: Polling-based, not real-time. For production bots, use Slack's Events API.
+
+## Pattern 4: Reaction-Based Workflow
+
+**Use case**: Use reactions as status indicators
+
+```bash
+#!/bin/bash
+
+CHANNEL="C0ACZKTDDC0"
+
+# Send task message
+RESULT=$(agent-slackbot message send "$CHANNEL" "Processing request...")
+MSG_TS=$(echo "$RESULT" | jq -r '.ts')
+
+# Mark as in-progress
+agent-slackbot reaction add "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
+
+# Do work...
+sleep 5
+
+# Remove in-progress, add success
+agent-slackbot reaction remove "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
+agent-slackbot reaction add "$CHANNEL" "$MSG_TS" white_check_mark
+
+# Update message with result
+agent-slackbot message update "$CHANNEL" "$MSG_TS" "Request processed successfully!"
+```
+
+**When to use**: Visual status tracking, acknowledgments, workflow states.
+
+## Pattern 5: Multi-Channel Broadcast
+
+**Use case**: Send the same message to multiple channels
+
+```bash
+#!/bin/bash
+
+MESSAGE="System maintenance in 30 minutes"
+CHANNELS=("C0ACZKTDDC0" "C0AC1NCF8NR")
+
+for channel in "${CHANNELS[@]}"; do
+  RESULT=$(agent-slackbot message send "$channel" "$MESSAGE")
+  TS=$(echo "$RESULT" | jq -r '.ts // "failed"')
+  echo "Channel $channel: $TS"
+  sleep 1
+done
+```
+
+**When to use**: Announcements, alerts across multiple channels.
+
+## Pattern 6: Error Handling and Retry
+
+**Use case**: Robust message sending for production
+
+```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
+    RESULT=$(agent-slackbot message send "$channel" "$message" 2>&1)
+    TS=$(echo "$RESULT" | jq -r '.ts // ""')
+
+    if [ -n "$TS" ] && [ "$TS" != "null" ]; then
+      echo "Sent: $TS"
+      return 0
+    fi
+
+    ERROR=$(echo "$RESULT" | jq -r '.error // "unknown"')
+    echo "Attempt $attempt failed: $ERROR"
+
+    # Don't retry on permanent errors
+    case "$ERROR" in
+      *"not_in_channel"*|*"channel_not_found"*)
+        return 1 ;;
+    esac
+
+    sleep $((attempt * 2))
+    attempt=$((attempt + 1))
+  done
+
+  echo "Failed after $max_attempts attempts"
+  return 1
+}
+
+send_with_retry "C0ACZKTDDC0" "Important notification!"
+```
+
+## Best Practices
+
+### 1. Use Channel IDs, Not Names
+
+Bot tokens require channel IDs (e.g., `C0ACZKTDDC0`), not names:
+
+```bash
+# Get channel ID first
+CHANNELS=$(agent-slackbot channel list)
+CHANNEL_ID=$(echo "$CHANNELS" | jq -r '.[] | select(.name=="general") | .id')
+agent-slackbot message send "$CHANNEL_ID" "Hello"
+```
+
+### 2. Rate Limit Your Requests
+
+```bash
+for channel in "${CHANNELS[@]}"; do
+  agent-slackbot message send "$channel" "$MESSAGE"
+  sleep 1
+done
+```
+
+### 3. Use Threads for Related Messages
+
+```bash
+PARENT_TS=$(agent-slackbot message send "$CHANNEL" "Task started" | jq -r '.ts')
+agent-slackbot message send "$CHANNEL" "Step 1 done" --thread "$PARENT_TS"
+agent-slackbot message send "$CHANNEL" "Step 2 done" --thread "$PARENT_TS"
+```
+
+### 4. Handle the "not_in_channel" Error
+
+Bots need to join channels before posting. With the `channels:join` scope, posting to a public channel auto-joins. For private channels, invite the bot from Slack UI.
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up bot tokens
+- [Templates](../templates/) - Runnable example scripts

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

@@ -0,0 +1,98 @@
+#!/bin/bash
+#
+# monitor-channel.sh - Monitor a Slack channel for new messages via bot token
+#
+# Usage:
+#   ./monitor-channel.sh <channel-id> [interval]
+#
+# Arguments:
+#   channel-id - Channel ID to monitor (e.g., C0ACZKTDDC0)
+#   interval   - Polling interval in seconds (default: 10)
+#
+# Example:
+#   ./monitor-channel.sh C0ACZKTDDC0
+#   ./monitor-channel.sh C0ACZKTDDC0 5
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 <channel-id> [interval]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 C0ACZKTDDC0          # Poll every 10s"
+  echo "  $0 C0ACZKTDDC0 5        # Poll every 5s"
+  exit 1
+fi
+
+CHANNEL="$1"
+INTERVAL="${2:-10}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+LAST_TS=""
+FIRST_RUN=true
+
+check_messages() {
+  MESSAGES=$(agent-slackbot message list "$CHANNEL" --limit 1 2>&1)
+  LATEST_TS=$(echo "$MESSAGES" | jq -r '.[0].ts // ""')
+
+  if [ -z "$LATEST_TS" ]; then
+    if [ "$FIRST_RUN" = true ]; then
+      echo -e "${YELLOW}No messages in channel yet${NC}"
+    fi
+    FIRST_RUN=false
+    return 0
+  fi
+
+  if [ "$LATEST_TS" != "$LAST_TS" ]; then
+    if [ "$FIRST_RUN" = false ] && [ -n "$LAST_TS" ]; then
+      TEXT=$(echo "$MESSAGES" | jq -r '.[0].text // ""')
+      USER=$(echo "$MESSAGES" | jq -r '.[0].user // "Unknown"')
+
+      echo ""
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      echo -e "${BLUE}New message in $CHANNEL${NC}"
+      echo -e "From:    $USER"
+      echo -e "Message: ${TEXT:0:100}"
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    fi
+
+    LAST_TS="$LATEST_TS"
+  fi
+
+  FIRST_RUN=false
+  return 0
+}
+
+if ! command -v agent-slackbot &> /dev/null; then
+  echo -e "${RED}Error: agent-slackbot not found${NC}"
+  echo "Install: npm install -g agent-messenger"
+  exit 1
+fi
+
+echo "Checking authentication..."
+AUTH_STATUS=$(agent-slackbot auth status 2>&1)
+VALID=$(echo "$AUTH_STATUS" | jq -r '.valid // false')
+
+if [ "$VALID" != "true" ]; then
+  echo -e "${RED}Not authenticated! Run: agent-slackbot auth set xoxb-your-token${NC}"
+  exit 1
+fi
+
+WORKSPACE=$(echo "$AUTH_STATUS" | jq -r '.workspace_name // "Unknown"')
+echo -e "${GREEN}Authenticated to: $WORKSPACE${NC}"
+
+echo -e "${YELLOW}Monitoring $CHANNEL (polling every ${INTERVAL}s)...${NC}"
+echo -e "${YELLOW}Press Ctrl+C to stop${NC}"
+echo ""
+
+trap 'echo -e "\n${YELLOW}Monitoring stopped${NC}"; exit 0' INT
+
+while true; do
+  check_messages
+  sleep "$INTERVAL"
+done

package/skills/agent-slackbot/templates/post-message.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+#
+# post-message.sh - Send a message to Slack via bot token with error handling
+#
+# Usage:
+#   ./post-message.sh <channel-id> <message>
+#
+# Example:
+#   ./post-message.sh C0ACZKTDDC0 "Hello from bot!"
+#   ./post-message.sh C0ACZKTDDC0 "Deployment completed"
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <channel-id> <message>"
+  echo ""
+  echo "Examples:"
+  echo "  $0 C0ACZKTDDC0 'Hello world!'"
+  echo "  $0 C0ACZKTDDC0 'Build completed'"
+  exit 1
+fi
+
+CHANNEL="$1"
+MESSAGE="$2"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+send_message() {
+  local channel=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    echo -e "${YELLOW}Attempt $attempt/$max_attempts...${NC}"
+
+    RESULT=$(agent-slackbot message send "$channel" "$message" 2>&1)
+    TS=$(echo "$RESULT" | jq -r '.ts // ""')
+
+    if [ -n "$TS" ] && [ "$TS" != "null" ]; then
+      echo -e "${GREEN}Message sent!${NC}"
+      echo ""
+      echo "  Channel: $channel"
+      echo "  Timestamp: $TS"
+      return 0
+    fi
+
+    ERROR=$(echo "$RESULT" | jq -r '.error // "Unknown error"')
+    echo -e "${RED}Failed: $ERROR${NC}"
+
+    case "$ERROR" in
+      *"No credentials"*)
+        echo ""
+        echo "Run: agent-slackbot auth set xoxb-your-token"
+        return 1
+        ;;
+      *"not_in_channel"*)
+        echo ""
+        echo "Bot is not in this channel. Invite the bot from Slack."
+        return 1
+        ;;
+    esac
+
+    if [ $attempt -lt $max_attempts ]; then
+      SLEEP_TIME=$((attempt * 2))
+      echo "Retrying in ${SLEEP_TIME}s..."
+      sleep $SLEEP_TIME
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  echo -e "${RED}Failed after $max_attempts attempts${NC}"
+  return 1
+}
+
+if ! command -v agent-slackbot &> /dev/null; then
+  echo -e "${RED}Error: agent-slackbot not found${NC}"
+  echo ""
+  echo "Install it with:"
+  echo "  npm install -g agent-messenger"
+  exit 1
+fi
+
+echo "Checking authentication..."
+AUTH_STATUS=$(agent-slackbot auth status 2>&1)
+VALID=$(echo "$AUTH_STATUS" | jq -r '.valid // false')
+
+if [ "$VALID" != "true" ]; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run: agent-slackbot auth set xoxb-your-token"
+  exit 1
+fi
+
+WORKSPACE=$(echo "$AUTH_STATUS" | jq -r '.workspace_name // "Unknown"')
+echo -e "${GREEN}Authenticated to: $WORKSPACE${NC}"
+echo ""
+
+echo "Sending message to $CHANNEL..."
+echo "Message: $MESSAGE"
+echo ""
+
+send_message "$CHANNEL" "$MESSAGE"