agent-messenger 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-messenger",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams)",
   "type": "module",
   "module": "dist/cli.js",
@@ -9,11 +9,14 @@
     "agent-messenger": "./src/cli.ts",
     "amsg": "./src/cli.ts",
     "agent-slack": "./src/platforms/slack/cli.ts",
-    "agent-discord": "./src/platforms/discord/cli.ts"
+    "agent-discord": "./src/platforms/discord/cli.ts",
+    "agent-teams": "./src/platforms/teams/cli.ts"
   },
   "scripts": {
-    "build": "tsc && sed -i '' '1s|#!/usr/bin/env bun|#!/usr/bin/env node|' dist/cli.js",
-    "test": "bun test",
+    "build": "tsc",
+    "postbuild": "bun scripts/postbuild.ts",
+    "test": "bun test src/",
+    "test:e2e": "bun test e2e/",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "format": "biome format --write .",
@@ -32,6 +35,7 @@
     "@types/better-sqlite3": "^7.6.8",
     "@types/bun": "latest",
     "@types/node": "^20.10.6",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }
 }

package/scripts/postbuild.ts

@@ -0,0 +1,15 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+const cliFiles = [
+  'dist/src/cli.js',
+  'dist/src/platforms/slack/cli.js',
+  'dist/src/platforms/discord/cli.js',
+]
+
+for (const file of cliFiles) {
+  const content = readFileSync(file, 'utf8')
+  const updated = content.replace('#!/usr/bin/env bun', '#!/usr/bin/env node')
+  writeFileSync(file, updated)
+}
+
+console.log(`Updated shebang in ${cliFiles.length} CLI files`)

package/skills/agent-teams/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: agent-teams
+description: Interact with Microsoft Teams - send messages, read channels, manage reactions
+allowed-tools: Bash(agent-teams:*)
+---
+
+# Agent Teams
+
+A TypeScript CLI tool that enables AI agents and humans to interact with Microsoft Teams through a simple command interface. Features seamless token extraction from the Teams desktop app and multi-team support.
+
+## TOKEN EXPIRY WARNING
+
+**CRITICAL**: Microsoft Teams tokens expire in **60-90 minutes**! Unlike Discord/Slack, Teams tokens have a short lifespan. You MUST:
+
+1. Check token validity before operations
+2. Re-extract credentials when tokens expire
+3. Handle `401 Unauthorized` errors gracefully
+
+```bash
+# Always check auth status first
+agent-teams auth status
+
+# If expired, re-extract
+agent-teams auth extract
+```
+
+## Quick Start
+
+```bash
+# Extract credentials from Teams desktop app (zero-config)
+agent-teams auth extract
+
+# Get team snapshot
+agent-teams snapshot
+
+# Send a message
+agent-teams message send <channel-id> "Hello from AI agent!"
+
+# List channels
+agent-teams channel list
+```
+
+## Authentication
+
+### Seamless Token Extraction
+
+agent-teams automatically extracts your Teams credentials from the desktop app:
+
+```bash
+# Just run this - no manual token copying needed
+agent-teams auth extract
+
+# Use --debug for troubleshooting
+agent-teams auth extract --debug
+```
+
+This command:
+- Auto-detects your platform (macOS/Linux/Windows)
+- Extracts skypetoken_asm from Teams desktop app's Cookies SQLite database
+- Validates token against Teams API before saving
+- Discovers ALL joined teams
+- Stores credentials securely in `~/.config/agent-messenger/`
+
+### Multi-Team Support
+
+```bash
+# List all available teams
+agent-teams team list
+
+# Switch to a different team
+agent-teams team switch <team-id>
+
+# Show current team
+agent-teams team current
+
+# Check auth status (includes token expiry info)
+agent-teams auth status
+```
+
+## Commands
+
+### Message Commands
+
+```bash
+# Send a message
+agent-teams message send <channel-id> <content>
+agent-teams message send 19:abc123@thread.tacv2 "Hello world"
+
+# List messages
+agent-teams message list <channel-id>
+agent-teams message list 19:abc123@thread.tacv2 --limit 50
+
+# Get a single message by ID
+agent-teams message get <channel-id> <message-id>
+
+# Delete a message
+agent-teams message delete <channel-id> <message-id> --force
+```
+
+### Channel Commands
+
+```bash
+# List channels in current team
+agent-teams channel list
+
+# Get channel info
+agent-teams channel info <channel-id>
+agent-teams channel info 19:abc123@thread.tacv2
+
+# Get channel history (alias for message list)
+agent-teams channel history <channel-id> --limit 100
+```
+
+### Team Commands
+
+```bash
+# List all teams
+agent-teams team list
+
+# Get team info
+agent-teams team info <team-id>
+
+# Switch active team
+agent-teams team switch <team-id>
+
+# Show current team
+agent-teams team current
+```
+
+### User Commands
+
+```bash
+# List team members
+agent-teams user list
+
+# Get user info
+agent-teams user info <user-id>
+
+# Get current user
+agent-teams user me
+```
+
+### Reaction Commands
+
+```bash
+# Add reaction (use emoji name)
+agent-teams reaction add <channel-id> <message-id> <emoji>
+agent-teams reaction add 19:abc123@thread.tacv2 1234567890 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
+agent-teams file upload <channel-id> <path>
+agent-teams file upload 19:abc123@thread.tacv2 ./report.pdf
+
+# List files in channel
+agent-teams file list <channel-id>
+
+# Get file info
+agent-teams file info <channel-id> <file-id>
+```
+
+### Snapshot Command
+
+Get comprehensive team state for AI agents:
+
+```bash
+# Full snapshot
+agent-teams snapshot
+
+# Filtered snapshots
+agent-teams snapshot --channels-only
+agent-teams snapshot --users-only
+
+# Limit messages per channel
+agent-teams snapshot --limit 10
+```
+
+Returns JSON with:
+- Team metadata (id, name)
+- Channels (id, name, type, description)
+- Recent messages (id, content, author, timestamp)
+- Members (id, displayName, email)
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "id": "19:abc123@thread.tacv2",
+  "content": "Hello world",
+  "author": "John Doe",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-teams channel list --pretty
+```
+
+## Key Differences from Discord/Slack
+
+| Feature | Teams | Discord | Slack |
+|---------|-------|---------|-------|
+| Server terminology | Team | Guild | Workspace |
+| Channel identifiers | UUID format (19:xxx@thread.tacv2) | Snowflake IDs | Channel name or ID |
+| Token storage | Cookies SQLite | LevelDB | LevelDB |
+| Token expiry | **60-90 minutes** | Rarely expires | Rarely expires |
+| Mentions | `<at id="user-id">Name</at>` | `<@user_id>` | `<@USER_ID>` |
+
+**Important**: Teams uses UUID-style channel IDs (like `19:abc123@thread.tacv2`). You cannot use channel names directly - use `channel list` to find IDs first.
+
+## 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 (with token refresh)
+- `team-summary.sh` - Generate team summary
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "Not authenticated. Run \"auth extract\" first."
+}
+```
+
+Common errors:
+- `Not authenticated`: No valid token - run `auth extract`
+- `Token expired`: Token has expired (60-90 min limit) - run `auth extract` again
+- `No current team set`: Run `team switch <id>` first
+- `Message not found`: Invalid message ID
+- `Channel not found`: Invalid channel ID
+- `401 Unauthorized`: Token expired - re-authenticate immediately
+
+## Configuration
+
+Credentials stored in: `~/.config/agent-messenger/teams-credentials.json`
+
+Format:
+```json
+{
+  "token": "skypetoken_asm_value_here",
+  "token_extracted_at": "2024-01-15T10:00:00.000Z",
+  "current_team": "team-uuid-here",
+  "teams": {
+    "team-uuid-here": {
+      "team_id": "team-uuid-here",
+      "team_name": "My Team"
+    }
+  }
+}
+```
+
+**Security**: File permissions set to 0600 (owner read/write only)
+
+## Limitations
+
+- No real-time events / WebSocket connection
+- No voice/video channel support
+- No team management (create/delete channels, roles)
+- No meeting support
+- No webhook support
+- Plain text messages only (no adaptive cards in v1)
+- User tokens only (no app tokens)
+- **Token expires in 60-90 minutes** - must re-authenticate frequently
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)

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

@@ -0,0 +1,375 @@
+# Authentication Guide
+
+## Overview
+
+agent-teams uses Microsoft Teams' user token extracted directly from the Teams desktop application. This provides seamless authentication without manual token management.
+
+## TOKEN EXPIRY WARNING
+
+**CRITICAL**: Microsoft Teams tokens expire in **60-90 minutes**!
+
+Unlike Discord or Slack tokens which rarely expire, Teams tokens have a short lifespan. Your scripts and workflows MUST handle token expiry gracefully.
+
+### Token Lifecycle
+
+```
+Token Extracted → Valid for 60-90 min → Expires → Must Re-extract
+```
+
+### Checking Token Age
+
+```bash
+# Check auth status - includes token age
+agent-teams auth status
+```
+
+Output:
+```json
+{
+  "authenticated": true,
+  "user": "john.doe@company.com",
+  "current_team": "team-uuid-here",
+  "teams_count": 3,
+  "token_age_minutes": 45,
+  "token_expires_soon": false
+}
+```
+
+When `token_expires_soon` is `true` (>50 min old), re-authenticate proactively.
+
+## Token Extraction
+
+### Automatic Extraction
+
+The simplest way to authenticate:
+
+```bash
+agent-teams auth extract
+
+# Use --debug for troubleshooting extraction issues
+agent-teams auth extract --debug
+```
+
+This command:
+1. Detects your operating system (macOS, Linux, Windows)
+2. Locates the Teams desktop app data directory
+3. Reads the **Cookies SQLite database** containing session data
+4. Extracts `skypetoken_asm` cookie value
+5. Validates token against Teams API before saving
+6. Discovers ALL joined teams
+7. Stores credentials securely in `~/.config/agent-messenger/teams-credentials.json`
+
+### Platform-Specific Paths
+
+**macOS:**
+```
+~/Library/Application Support/Microsoft/Teams/
+```
+
+**Linux:**
+```
+~/.config/Microsoft/Microsoft Teams/
+```
+
+**Windows:**
+```
+%APPDATA%\Microsoft\Teams\
+```
+
+The tool searches within:
+- `Cookies` - SQLite database containing `skypetoken_asm`
+- `Network/Cookies` - Alternative location on some versions
+
+### What Gets Extracted
+
+- **skypetoken_asm**: Authentication token for Teams API
+- **teams**: All teams you're a member of
+- **token_extracted_at**: Timestamp for expiry tracking
+
+## Multi-Team Management
+
+### List Teams
+
+See all available teams:
+
+```bash
+agent-teams team list
+```
+
+Output:
+```json
+[
+  {
+    "id": "team-uuid-1",
+    "name": "Engineering",
+    "current": true
+  },
+  {
+    "id": "team-uuid-2",
+    "name": "Marketing",
+    "current": false
+  }
+]
+```
+
+### Switch Team
+
+Change the active team:
+
+```bash
+agent-teams team switch team-uuid-2
+```
+
+All subsequent commands will use the selected team until you switch again.
+
+### Current Team
+
+Check which team is active:
+
+```bash
+agent-teams team current
+```
+
+## Credential Storage
+
+### Location
+
+Credentials are stored in:
+```
+~/.config/agent-messenger/teams-credentials.json
+```
+
+### Format
+
+```json
+{
+  "token": "skypetoken_asm_value_here",
+  "token_extracted_at": "2024-01-15T10:00:00.000Z",
+  "current_team": "team-uuid-1",
+  "teams": {
+    "team-uuid-1": {
+      "team_id": "team-uuid-1",
+      "team_name": "Engineering"
+    },
+    "team-uuid-2": {
+      "team_id": "team-uuid-2",
+      "team_name": "Marketing"
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Tokens are stored in plaintext (same as Teams desktop app)
+- Keep this file secure - it grants access to your Teams account
+- **Tokens auto-expire in 60-90 minutes** - provides some security
+
+## Authentication Status
+
+Check if you're authenticated:
+
+```bash
+agent-teams auth status
+```
+
+Output when authenticated:
+```json
+{
+  "authenticated": true,
+  "user": "john.doe@company.com",
+  "current_team": "team-uuid-here",
+  "teams_count": 3,
+  "token_age_minutes": 45,
+  "token_expires_soon": false
+}
+```
+
+Output when token expired:
+```json
+{
+  "authenticated": false,
+  "error": "Token expired. Run \"auth extract\" to re-authenticate."
+}
+```
+
+Output when not authenticated:
+```json
+{
+  "error": "Not authenticated. Run \"auth extract\" first."
+}
+```
+
+## Token Lifecycle
+
+### When Tokens Expire
+
+Teams tokens are invalidated when:
+- **60-90 minutes have passed** (most common!)
+- You sign out of the desktop app
+- Your password is changed
+- Admin revokes your session
+- You manually log out
+
+### Re-authentication Workflow
+
+**Proactive (Recommended):**
+```bash
+# Check token age before operations
+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
+
+# Now proceed with operations
+agent-teams message send "$CHANNEL_ID" "Hello!"
+```
+
+**Reactive (On Error):**
+```bash
+RESULT=$(agent-teams message send "$CHANNEL_ID" "Hello!")
+
+if echo "$RESULT" | jq -e '.error' | grep -q "expired\|401"; then
+  echo "Token expired, re-authenticating..."
+  agent-teams auth extract
+  
+  # Retry the operation
+  agent-teams message send "$CHANNEL_ID" "Hello!"
+fi
+```
+
+## Troubleshooting
+
+### Using Debug Mode
+
+For any extraction issues, run with `--debug` to see detailed information:
+
+```bash
+agent-teams auth extract --debug
+```
+
+This shows:
+- Which Teams directory was found
+- Cookies database location
+- Token extraction progress
+- Token validation results
+- Team discovery details
+
+### "Teams desktop app not found"
+
+**Cause**: Teams desktop app not installed or in non-standard location
+
+**Solution**:
+1. Install Microsoft Teams desktop app
+2. Log in to your account
+3. Run `agent-teams auth extract` again
+
+### "No Teams token found"
+
+**Cause**: Not logged into Teams or cookie storage corrupted
+
+**Solution**:
+1. Open Teams desktop app
+2. Make sure you're logged in (can see your teams)
+3. Run `agent-teams auth extract --debug` to see details
+
+### "Permission denied reading Teams data"
+
+**Cause**: Insufficient file system permissions
+
+**Solution** (macOS):
+1. Grant Terminal/iTerm full disk access in System Preferences
+2. Security & Privacy -> Privacy -> Full Disk Access
+3. Add your terminal application
+
+### "Token validation failed" / "401 Unauthorized"
+
+**Cause**: Token expired (most likely) or invalidated
+
+**Solution**:
+```bash
+# Re-extract fresh credentials
+agent-teams auth extract
+
+# Test authentication
+agent-teams auth status
+```
+
+### "Token expired" errors
+
+**Cause**: Token is older than 60-90 minutes
+
+**Solution**:
+```bash
+# Simply re-extract - this is normal for Teams!
+agent-teams auth extract
+```
+
+**Prevention**: Build token refresh into your scripts (see common-patterns.md)
+
+## Security Considerations
+
+### What agent-teams Can Access
+
+With extracted credentials, agent-teams has the same permissions as you in Teams:
+- Read all channels you have access to
+- Send messages as you
+- Upload/download files
+- Manage reactions
+- Access user information
+- View team member lists
+
+### What agent-teams Cannot Do
+
+- Access channels you don't have permission for
+- Perform admin operations (unless you're an admin)
+- Access other users' private chats without existing conversation
+- Manage team settings (not implemented)
+
+### Best Practices
+
+1. **Protect credentials.json**: Never commit to version control
+2. **Use team switching**: Keep different contexts separate
+3. **Handle token expiry**: Build refresh logic into all scripts
+4. **Re-extract frequently**: Tokens expire in 60-90 minutes
+5. **Revoke if compromised**: Sign out of Teams desktop app to invalidate tokens
+
+## Manual Token Management (Advanced)
+
+If automatic extraction fails, you can manually create credentials:
+
+```bash
+# Create config directory
+mkdir -p ~/.config/agent-messenger
+
+# Create credentials file
+cat > ~/.config/agent-messenger/teams-credentials.json << 'EOF'
+{
+  "token": "YOUR_SKYPETOKEN_ASM_HERE",
+  "token_extracted_at": "2024-01-15T10:00:00.000Z",
+  "current_team": "team-uuid-here",
+  "teams": {
+    "team-uuid-here": {
+      "team_id": "team-uuid-here",
+      "team_name": "My Team"
+    }
+  }
+}
+EOF
+
+# Set secure permissions
+chmod 600 ~/.config/agent-messenger/teams-credentials.json
+```
+
+To find your token manually:
+1. Open Teams in browser (teams.microsoft.com)
+2. Open DevTools -> Application tab
+3. Go to Cookies -> teams.microsoft.com
+4. Find `skypetoken_asm` cookie
+5. Copy the value
+
+**Warning**: Using user tokens for automation may violate Microsoft's Terms of Service. Use responsibly and at your own risk.