agent-messenger 1.2.0 → 1.3.0

package/e2e/slackbot.e2e.test.ts

@@ -0,0 +1,306 @@
+import { describe, test, expect, beforeAll, afterEach } from 'bun:test'
+import { runCLI, parseJSON, generateTestId, waitForRateLimit } from './helpers'
+import {
+  SLACKBOT_TEST_CHANNEL_ID,
+  SLACKBOT_TEST_CHANNEL,
+  validateSlackBotEnvironment,
+} from './config'
+import { SlackBotClient } from '../src/platforms/slackbot/client'
+import { SlackBotCredentialManager } from '../src/platforms/slackbot/credential-manager'
+
+let testMessages: string[] = []
+let cleanupClient: SlackBotClient
+
+async function getClient(): Promise<SlackBotClient> {
+  const credManager = new SlackBotCredentialManager()
+  const creds = await credManager.getCredentials()
+  if (!creds) throw new Error('No slackbot credentials')
+  return new SlackBotClient(creds.token)
+}
+
+async function cleanupBotMessages(channel: string, timestamps: string[]) {
+  for (const ts of timestamps) {
+    try {
+      await cleanupClient.deleteMessage(channel, ts)
+      await waitForRateLimit(500)
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+describe('SlackBot E2E Tests', () => {
+  beforeAll(async () => {
+    await validateSlackBotEnvironment()
+    cleanupClient = await getClient()
+
+    // Bot must be in the channel to send messages
+    try {
+      await cleanupClient.joinChannel(SLACKBOT_TEST_CHANNEL_ID)
+    } catch {
+      // already in channel
+    }
+  })
+
+  afterEach(async () => {
+    if (testMessages.length > 0) {
+      await cleanupBotMessages(SLACKBOT_TEST_CHANNEL_ID, testMessages)
+      testMessages = []
+    }
+    await waitForRateLimit()
+  })
+
+  describe('auth', () => {
+    test('auth status returns valid bot info', async () => {
+      const result = await runCLI('slackbot', ['auth', 'status'])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{
+        valid: boolean
+        workspace_id: string
+        workspace_name: string
+        bot_id: string
+      }>(result.stdout)
+      expect(data).not.toBeNull()
+      expect(data?.valid).toBe(true)
+      expect(data?.workspace_id).toBeTruthy()
+      expect(data?.workspace_name).toBeTruthy()
+      expect(data?.bot_id).toBeTruthy()
+    })
+  })
+
+  describe('message', () => {
+    test('message send creates message and returns ts', async () => {
+      const testId = generateTestId()
+      const result = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Bot test ${testId}`,
+      ])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{ ts: string; channel: string }>(result.stdout)
+      expect(data?.ts).toBeTruthy()
+      expect(data?.channel).toBe(SLACKBOT_TEST_CHANNEL_ID)
+
+      if (data?.ts) testMessages.push(data.ts)
+    })
+
+    test('message list returns messages array', async () => {
+      const result = await runCLI('slackbot', [
+        'message', 'list', SLACKBOT_TEST_CHANNEL_ID, '--limit', '5',
+      ])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<Array<{ ts: string }>>(result.stdout)
+      expect(Array.isArray(data)).toBe(true)
+    })
+
+    test('message get retrieves specific message', async () => {
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Get test ${testId}`,
+      ])
+      const sent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(sent?.ts).toBeTruthy()
+      if (sent?.ts) testMessages.push(sent.ts)
+
+      await waitForRateLimit()
+
+      const result = await runCLI('slackbot', [
+        'message', 'get', SLACKBOT_TEST_CHANNEL_ID, sent!.ts,
+      ])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{ text: string; ts: string }>(result.stdout)
+      expect(data?.text).toContain(testId)
+      expect(data?.ts).toBe(sent!.ts)
+    })
+
+    test('message update modifies message', async () => {
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Original ${testId}`,
+      ])
+      const sent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(sent?.ts).toBeTruthy()
+      if (sent?.ts) testMessages.push(sent.ts)
+
+      await waitForRateLimit()
+
+      const result = await runCLI('slackbot', [
+        'message', 'update', SLACKBOT_TEST_CHANNEL_ID, sent!.ts, `Updated ${testId}`,
+      ])
+      expect(result.exitCode).toBe(0)
+
+      await waitForRateLimit()
+
+      const getResult = await runCLI('slackbot', [
+        'message', 'get', SLACKBOT_TEST_CHANNEL_ID, sent!.ts,
+      ])
+      const data = parseJSON<{ text: string }>(getResult.stdout)
+      expect(data?.text).toContain('Updated')
+    })
+
+    test('message delete removes message', async () => {
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Delete me ${testId}`,
+      ])
+      const sent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(sent?.ts).toBeTruthy()
+
+      await waitForRateLimit()
+
+      const result = await runCLI('slackbot', [
+        'message', 'delete', SLACKBOT_TEST_CHANNEL_ID, sent!.ts, '--force',
+      ])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{ deleted: string }>(result.stdout)
+      expect(data?.deleted).toBe(sent!.ts)
+    })
+
+    test('message send with --thread creates reply', async () => {
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Parent ${testId}`,
+      ])
+      const parent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(parent?.ts).toBeTruthy()
+      if (parent?.ts) testMessages.push(parent.ts)
+
+      await waitForRateLimit()
+
+      const replyResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Reply ${testId}`,
+        '--thread', parent!.ts,
+      ])
+      expect(replyResult.exitCode).toBe(0)
+
+      const reply = parseJSON<{ ts: string; thread_ts: string }>(replyResult.stdout)
+      expect(reply?.thread_ts).toBe(parent!.ts)
+
+      if (reply?.ts) testMessages.push(reply.ts)
+    }, 30000)
+
+    test('message replies gets thread replies', async () => {
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Thread parent ${testId}`,
+      ])
+      const parent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(parent?.ts).toBeTruthy()
+      if (parent?.ts) testMessages.push(parent.ts)
+
+      await waitForRateLimit()
+
+      const replyResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Thread reply ${testId}`,
+        '--thread', parent!.ts,
+      ])
+      expect(replyResult.exitCode).toBe(0)
+      const reply = parseJSON<{ ts: string }>(replyResult.stdout)
+      if (reply?.ts) testMessages.push(reply.ts)
+
+      await waitForRateLimit()
+
+      const result = await runCLI('slackbot', [
+        'message', 'replies', SLACKBOT_TEST_CHANNEL_ID, parent!.ts,
+      ])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<Array<{ ts: string }>>(result.stdout)
+      expect(Array.isArray(data)).toBe(true)
+      expect(data!.length).toBeGreaterThanOrEqual(2)
+    })
+  })
+
+  describe('channel', () => {
+    test('channel list returns channels array', async () => {
+      const result = await runCLI('slackbot', ['channel', 'list', '--limit', '10'])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<Array<{ id: string; name: string }>>(result.stdout)
+      expect(Array.isArray(data)).toBe(true)
+      expect(data!.length).toBeGreaterThan(0)
+    })
+
+    test('channel info returns channel details', async () => {
+      const result = await runCLI('slackbot', ['channel', 'info', SLACKBOT_TEST_CHANNEL_ID])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{ id: string; name: string }>(result.stdout)
+      expect(data?.id).toBe(SLACKBOT_TEST_CHANNEL_ID)
+      expect(data?.name).toBe(SLACKBOT_TEST_CHANNEL)
+    })
+  })
+
+  describe('user', () => {
+    test('user list returns users array', async () => {
+      const result = await runCLI('slackbot', ['user', 'list', '--limit', '10'])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<Array<{ id: string; name: string }>>(result.stdout)
+      expect(Array.isArray(data)).toBe(true)
+      expect(data!.length).toBeGreaterThan(0)
+    })
+
+    test('user info returns user details', async () => {
+      // given: get the bot's own user_id via auth status
+      const statusResult = await runCLI('slackbot', ['auth', 'status'])
+      const status = parseJSON<{ bot_id: string; user: string }>(statusResult.stdout)
+      expect(status?.user).toBeTruthy()
+
+      await waitForRateLimit()
+
+      // when: list users and find the bot user
+      const listResult = await runCLI('slackbot', ['user', 'list', '--limit', '50'])
+      const users = parseJSON<Array<{ id: string; name: string }>>(listResult.stdout)
+      const botUser = users?.find((u) => u.name === status!.user)
+      expect(botUser).toBeTruthy()
+
+      await waitForRateLimit()
+
+      // then: user info returns matching data
+      const result = await runCLI('slackbot', ['user', 'info', botUser!.id])
+      expect(result.exitCode).toBe(0)
+
+      const data = parseJSON<{ id: string; name: string }>(result.stdout)
+      expect(data?.id).toBe(botUser!.id)
+    })
+  })
+
+  describe('reaction', () => {
+    test('reaction add and remove lifecycle', async () => {
+      // given: a message to react to
+      const testId = generateTestId()
+      const sendResult = await runCLI('slackbot', [
+        'message', 'send', SLACKBOT_TEST_CHANNEL_ID, `Reaction test ${testId}`,
+      ])
+      const sent = parseJSON<{ ts: string }>(sendResult.stdout)
+      expect(sent?.ts).toBeTruthy()
+      if (sent?.ts) testMessages.push(sent.ts)
+
+      await waitForRateLimit(2000)
+
+      // when: add reaction
+      const addResult = await runCLI('slackbot', [
+        'reaction', 'add', SLACKBOT_TEST_CHANNEL_ID, sent!.ts, 'thumbsup',
+      ])
+      expect(addResult.exitCode).toBe(0)
+
+      const addData = parseJSON<{ success: boolean }>(addResult.stdout)
+      expect(addData?.success).toBe(true)
+
+      await waitForRateLimit(2000)
+
+      // then: remove reaction
+      const removeResult = await runCLI('slackbot', [
+        'reaction', 'remove', SLACKBOT_TEST_CHANNEL_ID, sent!.ts, 'thumbsup',
+      ])
+      expect(removeResult.exitCode).toBe(0)
+
+      const removeData = parseJSON<{ success: boolean }>(removeResult.stdout)
+      expect(removeData?.success).toBe(true)
+    }, 15000)
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-messenger",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams)",
   "type": "module",
   "module": "dist/cli.js",
@@ -10,7 +10,8 @@
     "amsg": "./src/cli.ts",
     "agent-slack": "./src/platforms/slack/cli.ts",
     "agent-discord": "./src/platforms/discord/cli.ts",
-    "agent-teams": "./src/platforms/teams/cli.ts"
+    "agent-teams": "./src/platforms/teams/cli.ts",
+    "agent-slackbot": "./src/platforms/slackbot/cli.ts"
   },
   "scripts": {
     "build": "tsc",

package/skills/agent-slackbot/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: agent-slackbot
+description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
+allowed-tools: Bash(agent-slackbot:*)
+---
+
+# Agent SlackBot
+
+A TypeScript CLI tool that enables AI agents and humans to interact with Slack workspaces using bot tokens (xoxb-). Unlike agent-slack which extracts user tokens from the desktop app, agent-slackbot uses standard Slack Bot tokens for server-side and CI/CD integrations.
+
+## Quick Start
+
+```bash
+# Set your bot token
+agent-slackbot auth set xoxb-your-bot-token
+
+# Or set with a custom bot identifier for multi-bot setups
+agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"
+
+# Verify authentication
+agent-slackbot auth status
+
+# Send a message
+agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"
+
+# List channels
+agent-slackbot channel list
+```
+
+## Authentication
+
+### Bot Token Setup
+
+agent-slackbot uses Slack Bot tokens (xoxb-) which you get from the Slack App configuration:
+
+```bash
+# Set bot token (validates against Slack API before saving)
+agent-slackbot auth set xoxb-your-bot-token
+
+# Set with a custom bot identifier
+agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"
+
+# Check auth status
+agent-slackbot auth status
+
+# Clear stored credentials
+agent-slackbot auth clear
+```
+
+### Multi-Bot Management
+
+Store multiple bot tokens and switch between them:
+
+```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 (without switching)
+agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert
+
+# Remove a stored bot
+agent-slackbot auth remove deploy
+
+# Disambiguate bots with same ID across workspaces
+agent-slackbot auth use T123456/deploy
+```
+
+The `--bot <id>` flag is available on all commands to override the active bot for a single invocation.
+
+### Getting a Bot Token
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Create New App (or select existing)
+3. Go to **OAuth & Permissions**
+4. Add required bot token scopes (see below)
+5. Install app to workspace
+6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+
+### Required Bot Token Scopes
+
+| Scope | Used For |
+|-------|----------|
+| `chat:write` | Sending messages |
+| `channels:history` | Reading public channel messages |
+| `channels:read` | Listing public channels |
+| `channels:join` | Joining public channels |
+| `groups:history` | Reading private channel messages |
+| `groups:read` | Listing private channels |
+| `users:read` | Listing users |
+| `users:read.email` | Reading user email addresses |
+| `reactions:write` | Adding/removing reactions |
+| `reactions:read` | Listing reactions |
+
+### Environment Variables (CI/CD)
+
+For CI/CD pipelines, set these environment variables instead of using `auth set`:
+
+```bash
+export E2E_SLACKBOT_TOKEN=xoxb-your-bot-token
+export E2E_SLACKBOT_WORKSPACE_ID=T123456
+export E2E_SLACKBOT_WORKSPACE_NAME="My Workspace"
+```
+
+## Commands
+
+### Message Commands
+
+```bash
+# Send a message
+agent-slackbot message send <channel> <text>
+agent-slackbot message send C0ACZKTDDC0 "Hello world"
+
+# Send a threaded reply
+agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>
+
+# List messages
+agent-slackbot message list <channel>
+agent-slackbot message list C0ACZKTDDC0 --limit 50
+
+# Get a single message by timestamp
+agent-slackbot message get <channel> <ts>
+
+# Get thread replies (includes parent message)
+agent-slackbot message replies <channel> <thread_ts>
+agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50
+
+# Update a message (bot's own messages only)
+agent-slackbot message update <channel> <ts> <new-text>
+
+# Delete a message (bot's own messages only)
+agent-slackbot message delete <channel> <ts> --force
+```
+
+### Channel Commands
+
+```bash
+# List channels the bot can see
+agent-slackbot channel list
+agent-slackbot channel list --limit 50
+
+# Get channel info
+agent-slackbot channel info <channel>
+agent-slackbot channel info C0ACZKTDDC0
+```
+
+### User Commands
+
+```bash
+# List users
+agent-slackbot user list
+agent-slackbot user list --limit 50
+
+# Get user info
+agent-slackbot user info <user-id>
+```
+
+### Reaction Commands
+
+```bash
+# Add reaction
+agent-slackbot reaction add <channel> <ts> <emoji>
+agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup
+
+# Remove reaction
+agent-slackbot reaction remove <channel> <ts> <emoji>
+```
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "ts": "1234567890.123456",
+  "channel": "C0ACZKTDDC0",
+  "text": "Hello world"
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-slackbot channel list --pretty
+```
+
+## Common Patterns
+
+See `references/common-patterns.md` for typical AI agent workflows.
+
+## Templates
+
+See `templates/` directory for runnable examples:
+- `post-message.sh` - Send messages with error handling
+- `monitor-channel.sh` - Monitor channel for new messages
+- `workspace-summary.sh` - Generate workspace summary
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "No credentials. Run \"auth set\" first."
+}
+```
+
+Common errors:
+- `missing_token`: No credentials configured
+- `invalid_token_type`: Token is not a bot token (must start with xoxb-)
+- `not_in_channel`: Bot needs to join the channel first
+- `slack_webapi_rate_limited_error`: Hit rate limit (auto-retries with backoff)
+
+## Configuration
+
+Credentials stored in: `~/.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-..."
+        },
+        "alert": {
+          "bot_id": "alert",
+          "bot_name": "Alert Bot",
+          "token": "xoxb-..."
+        }
+      }
+    }
+  }
+}
+```
+
+**Security**: File permissions set to 0600 (owner read/write only)
+
+## Key Differences from agent-slack
+
+| Feature | agent-slack | agent-slackbot |
+|---------|------------|----------------|
+| Token type | User token (xoxc-) | Bot token (xoxb-) |
+| Token source | Auto-extracted from desktop app | Manual from Slack App config |
+| Message search | Yes | No (requires user token) |
+| File operations | Yes | No |
+| Snapshot | Yes | No |
+| Edit/delete messages | Any message | Bot's own messages only |
+| Workspace management | Multi-workspace | Multi-bot, multi-workspace |
+| CI/CD friendly | Requires desktop app | Yes (just set token) |
+
+## Limitations
+
+- No real-time events / Socket Mode
+- No message search (requires user token scope)
+- No file upload/download
+- No workspace snapshot
+- Bot can only edit/delete its own messages
+- Bot must be invited to private channels
+- No scheduled messages
+- Plain text messages only (no blocks/formatting)
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)