agent-messenger 1.0.0 → 1.1.0

package/docs/teams.md

@@ -0,0 +1,321 @@
+# Microsoft Teams Integration
+
+Detailed documentation for Microsoft Teams integration in agent-messenger.
+
+> **Note**: `agent-teams` is a convenient shortcut for `agent-messenger teams`.
+
+## Quick Start
+
+```bash
+# 1. Extract credentials from Teams desktop app (zero-config!)
+agent-teams auth extract
+
+# 2. Get team snapshot
+agent-teams snapshot
+
+# 3. Send a message
+agent-teams message send <channel-id> "Hello from AI agent!"
+```
+
+## Authentication
+
+### Seamless Token Extraction
+
+agent-teams automatically extracts your Microsoft Teams credentials from the desktop app:
+
+```bash
+agent-teams auth extract
+
+# Use --debug for troubleshooting
+agent-teams auth extract --debug
+```
+
+This command:
+- Auto-detects your platform (macOS/Linux/Windows)
+- Extracts Teams access token from the desktop app
+- Validates token against Teams API
+- Discovers ALL joined teams
+- Stores credentials securely in `~/.config/agent-messenger/`
+
+### ⚠️ TOKEN EXPIRY WARNING
+
+**Teams tokens expire in 60-90 minutes!** Unlike Slack and Discord tokens which last much longer, Microsoft Teams uses short-lived OAuth tokens.
+
+```bash
+# Check if your token is still valid
+agent-teams auth status
+
+# Re-extract when expired (just run extract again)
+agent-teams auth extract
+```
+
+**Best practices for AI agents:**
+- Always check `auth status` before operations
+- Re-run `auth extract` if you get 401 errors
+- Consider automating token refresh in long-running workflows
+
+### Authentication Commands
+
+```bash
+# Check auth status (shows expiry time!)
+agent-teams auth status
+
+# Logout (clear stored credentials)
+agent-teams auth logout
+```
+
+### Supported Teams Versions
+
+agent-teams supports both **New Teams** (WebView2-based, com.microsoft.teams2) and **Classic Teams**:
+
+| Version | macOS | Windows | Linux |
+|---------|:-----:|:-------:|:-----:|
+| New Teams | ✅ | ✅ | N/A |
+| Classic Teams | ✅ | ✅ | ✅ |
+
+### Manual Token Input (Last Resort)
+
+If automatic extraction fails, you can manually provide a token:
+
+```bash
+agent-teams auth extract --token <your-skype-token>
+```
+
+**How to get your token manually:**
+
+1. Open Microsoft Teams in your browser (teams.microsoft.com)
+2. Open Developer Tools (F12 or Cmd+Option+I)
+3. Go to **Application** > **Cookies** > `https://teams.microsoft.com`
+4. Find the cookie named `skypetoken_asm`
+5. Copy the **Value** (it's a long string starting with `eyJ...`)
+6. Run: `agent-teams auth extract --token "eyJ..."`
+
+> **Note**: Browser tokens also expire in 60-90 minutes. For long-running workflows, you may need to refresh periodically.
+
+## Team Management
+
+Teams uses "teams" as the top-level organizational unit. You must select a team before using most commands.
+
+```bash
+# List all teams
+agent-teams team list
+
+# Switch to a different team
+agent-teams team switch <team-id>
+
+# Show current team
+agent-teams team current
+
+# Get team info
+agent-teams team info <team-id>
+```
+
+## Commands
+
+### Message Commands
+
+```bash
+# Send a message
+agent-teams message send <channel-id> <content>
+agent-teams message send abc123-def456 "Hello world"
+
+# List messages
+agent-teams message list <channel-id>
+agent-teams message list abc123-def456 --limit 50
+
+# Get a specific message
+agent-teams message get <channel-id> <message-id>
+
+# Delete a message
+agent-teams message delete <channel-id> <message-id> --force
+
+# Reply to a message (thread)
+agent-teams message reply <channel-id> <message-id> "Reply content"
+```
+
+### Channel Commands
+
+```bash
+# List channels in current team
+agent-teams channel list
+
+# Get channel info
+agent-teams channel info <channel-id>
+
+# Get channel message history
+agent-teams channel history <channel-id>
+agent-teams channel history abc123-def456 --limit 100
+```
+
+### User Commands
+
+```bash
+# List team members
+agent-teams user list
+
+# Get user info
+agent-teams user info <user-id>
+
+# Get current authenticated user
+agent-teams user me
+```
+
+### Reaction Commands
+
+```bash
+# Add reaction
+agent-teams reaction add <channel-id> <message-id> <emoji>
+agent-teams reaction add abc123-def456 msg789 like
+
+# Remove reaction
+agent-teams reaction remove <channel-id> <message-id> <emoji>
+
+# List reactions on a message
+agent-teams reaction list <channel-id> <message-id>
+```
+
+### File Commands
+
+```bash
+# Upload file to channel
+agent-teams file upload <channel-id> <path>
+agent-teams file upload abc123-def456 ./report.pdf
+
+# List files in channel
+agent-teams file list <channel-id>
+
+# Get file info
+agent-teams file info <channel-id> <file-id>
+
+# Download file
+agent-teams file download <file-id> <output-path>
+```
+
+### Snapshot Command
+
+Get comprehensive team state for AI agents:
+
+```bash
+# Full snapshot (channels, members, recent messages)
+agent-teams snapshot
+
+# Filtered snapshots
+agent-teams snapshot --channels-only
+agent-teams snapshot --users-only
+
+# Limit messages per channel
+agent-teams snapshot --limit 10
+```
+
+## Global Options
+
+All commands support these options:
+
+```bash
+--pretty      # Pretty-print JSON output (default is compact JSON)
+--team <id>   # Use specific team (overrides current team)
+```
+
+## Key Differences: Teams vs Discord vs Slack
+
+| Concept | Slack | Discord | Teams |
+|---------|-------|---------|-------|
+| Server/Workspace | Workspace | Guild | Team |
+| Channel ID format | Alphanumeric (C01234567) | Numeric snowflake | UUID (abc123-def456-...) |
+| Message ID format | Timestamp (1234567890.123456) | Numeric snowflake | UUID |
+| User ID format | Alphanumeric (U01234567) | Numeric snowflake | UUID (Azure AD Object ID) |
+| Token lifetime | Long-lived | Long-lived | **60-90 minutes** |
+| API | Slack Web API | Discord API | Teams Messaging API |
+| Threads | Thread timestamps | Thread channels | Reply chains |
+| Rate limits | Moderate | Moderate | Strict |
+
+## Troubleshooting
+
+### Token Expired (401 Unauthorized)
+
+```bash
+# Teams tokens expire in 60-90 minutes! To refresh:
+# 1. Open Microsoft Teams desktop app
+# 2. Send any message (this refreshes your session cookies)
+# 3. Re-extract:
+agent-teams auth extract
+```
+
+### "No teams found"
+
+Ensure you're a member of at least one team in the Teams desktop app, then:
+```bash
+agent-teams auth extract --debug
+```
+
+### "Channel not found"
+
+Teams channel IDs are UUIDs. Make sure you're using the full ID:
+```bash
+# Get channel list to find correct IDs
+agent-teams channel list --pretty
+```
+
+### Rate Limiting (429 Too Many Requests)
+
+Teams API has strict rate limits. Wait and retry:
+```bash
+# Add delays between operations in scripts
+sleep 2
+```
+
+### Desktop App Not Detected
+
+Ensure Teams desktop app is:
+1. Installed (not just web version)
+2. Currently running
+3. Signed in to your account
+
+```bash
+# Debug extraction
+agent-teams auth extract --debug
+```
+
+### Permission Errors
+
+Some operations require specific Microsoft 365 permissions. Check with your IT admin if you encounter persistent 403 errors.
+
+## AI Agent Integration
+
+See `skills/agent-messenger/` directory for:
+- Complete skill documentation
+- Runnable templates
+
+### Example: AI Agent Workflow
+
+```bash
+#!/bin/bash
+# Example: Daily standup automation
+
+# 1. Check auth (re-extract if needed)
+if ! agent-teams auth status | grep -q "valid"; then
+  agent-teams auth extract
+fi
+
+# 2. Get team context
+agent-teams snapshot --limit 5 > /tmp/teams-context.json
+
+# 3. Send standup reminder
+agent-teams message send $STANDUP_CHANNEL "🌅 Good morning! Time for standup."
+```
+
+### Token Refresh Pattern for Long-Running Agents
+
+```bash
+# Wrapper function for token-aware operations
+teams_cmd() {
+  # Check token validity
+  if ! agent-teams auth status 2>/dev/null | grep -q "valid"; then
+    agent-teams auth extract
+  fi
+  agent-teams "$@"
+}
+
+# Usage
+teams_cmd message send $CHANNEL "Hello!"
+```

package/e2e/README.md

@@ -0,0 +1,256 @@
+# E2E Tests
+
+End-to-end tests that run every CLI command against real Slack and Discord APIs.
+
+## Prerequisites
+
+Before running E2E tests, you need:
+
+1. **Dedicated Test Workspaces** - Create separate Slack and Discord test workspaces/guilds
+   - **Never run E2E tests against your business or personal accounts**
+   - Tests create and delete messages, which could interfere with real work
+
+2. **Test Channels** - Create an `e2e-test` channel in each test workspace/guild
+   - Slack: Channel named `e2e-test`
+   - Discord: Text channel named `e2e-test`
+
+3. **Authentication** - Either:
+   - Local credentials from desktop apps (via `auth extract`)
+   - Environment variables (for CI)
+
+## Test Infrastructure
+
+| File | Description |
+|------|-------------|
+| `config.ts` | Hardcoded test workspace/guild IDs and validation |
+| `helpers.ts` | CLI runner, JSON parser, message cleanup utilities |
+| `slack.e2e.test.ts` | Slack command tests (23 tests) |
+| `discord.e2e.test.ts` | Discord command tests (20 tests) |
+
+## Running E2E Tests Locally
+
+### Step 1: Extract Credentials
+
+First, make sure the desktop apps (Slack/Discord) are running and logged into your **test** workspaces.
+
+```bash
+# Extract Slack credentials
+agent-slack auth extract
+
+# Extract Discord credentials  
+agent-discord auth extract
+```
+
+### Step 2: Switch to Test Workspace
+
+Ensure you're targeting the correct test workspace:
+
+```bash
+# Verify Slack workspace
+agent-slack workspace current
+# Should show: "Agent Messenger" (T0AC55BSF6E)
+
+# Verify Discord guild
+agent-discord guild current
+# Should show: "Agent Messenger" (1467039439770357844)
+```
+
+If wrong, switch workspaces:
+
+```bash
+agent-slack workspace switch <test-workspace-id>
+agent-discord guild switch <test-guild-id>
+```
+
+### Step 3: Run Tests
+
+```bash
+# Run all E2E tests
+bun test e2e/
+
+# Run only Slack tests
+bun test e2e/slack.e2e.test.ts
+
+# Run only Discord tests
+bun test e2e/discord.e2e.test.ts
+
+# Run specific test by name
+bun test e2e/slack.e2e.test.ts --test-name-pattern "message send"
+```
+
+## Running E2E Tests in CI (GitHub Actions)
+
+### Required Secrets
+
+Set these secrets in your GitHub repository settings:
+
+#### Slack Secrets
+
+| Secret | Description | How to Get |
+|--------|-------------|------------|
+| `E2E_SLACK_TOKEN` | Slack auth token (xoxc-...) | `agent-slack auth extract` → check output |
+| `E2E_SLACK_COOKIE` | Slack cookie (xoxd-...) | Same as above |
+| `E2E_SLACK_WORKSPACE_ID` | Test workspace ID | `agent-slack workspace current` |
+| `E2E_SLACK_WORKSPACE_NAME` | Test workspace name | Same as above |
+
+#### Discord Secrets
+
+| Secret | Description | How to Get |
+|--------|-------------|------------|
+| `E2E_DISCORD_TOKEN` | Discord auth token | `agent-discord auth extract` → check output |
+| `E2E_DISCORD_GUILD_ID` | Test guild ID | `agent-discord guild current` |
+
+### Getting Credentials for CI
+
+Run locally to extract credentials, then copy them to GitHub Secrets:
+
+```bash
+# Slack - extract and view credentials
+agent-slack auth extract
+cat ~/.agent-messenger/slack/credentials.json
+# Copy token and cookie values
+
+# Discord - extract and view credentials
+agent-discord auth extract
+cat ~/.agent-messenger/discord/credentials.json
+# Copy token value
+```
+
+### Workflow Triggers
+
+The E2E workflow (`.github/workflows/e2e.yml`) runs:
+
+- **Manually**: Via `workflow_dispatch` (Actions tab → Run workflow)
+- **On PRs**: When changes are made to `src/`, `e2e/`, or `package.json`
+
+### Manual Trigger Options
+
+When triggering manually, you can select which platform to test:
+
+- `all` - Run both Slack and Discord tests (default)
+- `slack` - Run only Slack tests
+- `discord` - Run only Discord tests
+
+## Test Coverage
+
+### Slack Tests (23 tests)
+
+| Command Group | Tests |
+|---------------|-------|
+| `auth` | status |
+| `workspace` | list, current |
+| `message` | send, list, get, update, delete, thread reply, replies, search |
+| `channel` | list, list --type, info |
+| `user` | list, me, info |
+| `reaction` | add, list, remove |
+| `file` | upload, list, list --channel, info |
+| `snapshot` | default, --channels-only, --users-only, --limit |
+
+### Discord Tests (20 tests)
+
+| Command Group | Tests |
+|---------------|-------|
+| `auth` | status |
+| `guild` | list, current, info |
+| `message` | send, list, get*, delete |
+| `channel` | list, info, history |
+| `user` | list, me, info* |
+| `reaction` | add*, list*, remove* |
+| `file` | upload, list |
+| `snapshot` | default, --channels-only, --users-only |
+
+\* Some Discord tests are skipped because they require Bot Token permissions not available to user tokens.
+
+## Troubleshooting
+
+### "Wrong workspace" / "Wrong guild" Error
+
+The tests detected you're not in the designated test workspace:
+
+```
+Error: Wrong Slack workspace. Expected: Agent Messenger (T0AC55BSF6E), Got: My Company (TXXXXXX)
+```
+
+**Solution**: Switch to the correct test workspace before running tests.
+
+### Authentication Failed
+
+```
+Error: Slack authentication failed. Please run: agent-messenger slack auth login
+```
+
+**Solution**: 
+1. Make sure the desktop app is running
+2. Run `agent-slack auth extract` or `agent-discord auth extract`
+3. For CI, check that secrets are correctly configured
+
+### Rate Limiting
+
+If tests fail intermittently with rate limit errors, try running fewer tests at once:
+
+```bash
+bun test e2e/slack.e2e.test.ts --test-name-pattern "auth"
+```
+
+The test harness includes automatic delays between API calls, but heavy testing may still hit limits.
+
+### Orphaned Test Messages
+
+If tests crash before cleanup, you may have leftover messages in the `e2e-test` channel. Clean them up manually:
+
+```bash
+# List recent messages
+agent-slack message list e2e-test --limit 20 --pretty
+
+# Delete specific message
+agent-slack message delete e2e-test <timestamp> --force
+```
+
+### CI Environment Variables Not Working
+
+Verify the credential managers are reading env vars:
+
+```bash
+# Test locally with env vars
+E2E_SLACK_TOKEN=xoxc-test E2E_SLACK_COOKIE=xoxd-test bun -e "
+  import { CredentialManager } from './src/platforms/slack/credential-manager.ts';
+  const cm = new CredentialManager();
+  const creds = await cm.getWorkspace();
+  console.log(creds);
+"
+```
+
+If this shows your test credentials, env var support is working.
+
+## Safety Features
+
+1. **Hardcoded Test IDs**: Test workspace/guild IDs are hardcoded in `config.ts`. Tests will refuse to run against other workspaces.
+
+2. **Environment Validation**: Before any write operations, tests call `validateSlackEnvironment()` or `validateDiscordEnvironment()` to verify the correct workspace.
+
+3. **Automatic Cleanup**: Tests track created messages and delete them in `afterEach` hooks.
+
+4. **Rate Limiting**: Built-in delays between API calls prevent hitting rate limits.
+
+## Adding New Tests
+
+1. Follow existing patterns in `slack.e2e.test.ts` or `discord.e2e.test.ts`
+2. Use helpers from `helpers.ts` for CLI execution
+3. Track created resources for cleanup in `afterEach`
+4. Add appropriate delays with `waitForRateLimit()`
+
+Example:
+
+```typescript
+test('my new test', async () => {
+  const testId = generateTestId()
+  const { id } = await createTestMessage('slack', SLACK_TEST_CHANNEL_ID, `Test ${testId}`)
+  testMessages.push(id)  // Track for cleanup
+  
+  await waitForRateLimit()
+  
+  // Your test assertions here
+  const result = await runCLI('slack', ['some', 'command', id])
+  expect(result.exitCode).toBe(0)
+})
+```

package/e2e/config.ts

@@ -0,0 +1,45 @@
+export const SLACK_TEST_WORKSPACE_ID = 'T0AC55BSF6E'
+export const SLACK_TEST_WORKSPACE_NAME = 'Agent Messenger'
+export const SLACK_TEST_CHANNEL_ID = 'C0ACZKTDDC0'
+export const SLACK_TEST_CHANNEL = 'e2e-test'
+
+// Discord Test Environment
+export const DISCORD_TEST_GUILD_ID = '1467039439770357844'
+export const DISCORD_TEST_GUILD_NAME = 'Agent Messenger'
+export const DISCORD_TEST_CHANNEL_ID = '1467062262996144162'
+export const DISCORD_TEST_CHANNEL = 'e2e-test'
+
+export async function validateSlackEnvironment() {
+  const { runCLI, parseJSON } = await import('./helpers')
+  
+  const result = await runCLI('slack', ['auth', 'status'])
+  if (result.exitCode !== 0) {
+    throw new Error('Slack authentication failed. Please run: agent-messenger slack auth login')
+  }
+  
+  const data = parseJSON<{ workspace_id: string; workspace_name: string }>(result.stdout)
+  if (data?.workspace_id !== SLACK_TEST_WORKSPACE_ID) {
+    throw new Error(
+      `Wrong Slack workspace. Expected: ${SLACK_TEST_WORKSPACE_NAME} (${SLACK_TEST_WORKSPACE_ID}), ` +
+      `Got: ${data?.workspace_name} (${data?.workspace_id})`
+    )
+  }
+}
+
+export async function validateDiscordEnvironment() {
+  const { runCLI, parseJSON } = await import('./helpers')
+  
+  const result = await runCLI('discord', ['auth', 'status'])
+  if (result.exitCode !== 0) {
+    throw new Error('Discord authentication failed. Please run: agent-messenger discord auth login')
+  }
+  
+  const currentResult = await runCLI('discord', ['guild', 'current'])
+  const data = parseJSON<{ guild_id: string; guild_name: string }>(currentResult.stdout)
+  if (data?.guild_id !== DISCORD_TEST_GUILD_ID) {
+    throw new Error(
+      `Wrong Discord guild. Expected: ${DISCORD_TEST_GUILD_NAME} (${DISCORD_TEST_GUILD_ID}), ` +
+      `Got: ${data?.guild_name} (${data?.guild_id})`
+    )
+  }
+}