agent-messenger 1.14.0 → 2.0.0

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

@@ -16,11 +16,11 @@ agent-slack message send general "Deployment completed successfully!"
 
 # With error handling
 RESULT=$(agent-slack message send general "Hello world")
-if echo "$RESULT" | jq -e '.success' > /dev/null; then
-  echo "Message sent!"
-else
-  echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+if [ -z "$RESULT" ] || ! echo "$RESULT" | jq -e '.ts' > /dev/null 2>&1; then
+  echo "Failed: $(echo "$RESULT" | jq -r '.error // "unknown_error"')"
   exit 1
+else
+  echo "Message sent: $(echo "$RESULT" | jq -r '.ts')"
 fi
 ```
 
@@ -39,12 +39,12 @@ LAST_TS=""
 while true; do
   # Get latest message
   MESSAGES=$(agent-slack message list "$CHANNEL" --limit 1)
-  LATEST_TS=$(echo "$MESSAGES" | jq -r '.data.messages[0].ts')
+  LATEST_TS=$(echo "$MESSAGES" | jq -r '.[0].ts')
 
   # Check if new message
   if [ "$LATEST_TS" != "$LAST_TS" ] && [ -n "$LAST_TS" ]; then
-    TEXT=$(echo "$MESSAGES" | jq -r '.data.messages[0].text')
-    USER=$(echo "$MESSAGES" | jq -r '.data.messages[0].user')
+    TEXT=$(echo "$MESSAGES" | jq -r '.[0].text')
+    USER=$(echo "$MESSAGES" | jq -r '.[0].user')
 
     echo "New message from $USER: $TEXT"
 
@@ -62,7 +62,7 @@ done
 
 **When to use**: Building a simple bot that reacts to messages.
 
-**Limitations**: Polling-based, not real-time. For production bots, use Slack's Events API.
+**Limitations**: Polling-based, not real-time. For real-time events, use the `SlackListener` SDK (see SKILL.md → SDK: Real-Time Events).
 
 ## Pattern 3: Get Workspace Overview
 
@@ -75,9 +75,9 @@ done
 SNAPSHOT=$(agent-slack snapshot)
 
 # Extract key information
-WORKSPACE_NAME=$(echo "$SNAPSHOT" | jq -r '.data.workspace.name')
-CHANNEL_COUNT=$(echo "$SNAPSHOT" | jq -r '.data.channels | length')
-USER_COUNT=$(echo "$SNAPSHOT" | jq -r '.data.users | length')
+WORKSPACE_NAME=$(echo "$SNAPSHOT" | jq -r '.workspace.name')
+CHANNEL_COUNT=$(echo "$SNAPSHOT" | jq -r '.channels | length')
+USER_COUNT=$(echo "$SNAPSHOT" | jq -r '.users | length')
 
 echo "Workspace: $WORKSPACE_NAME"
 echo "Channels: $CHANNEL_COUNT"
@@ -89,7 +89,7 @@ echo "$SNAPSHOT" | jq -r '.channels[] | "  \(.name) (\(.id))"'
 
 # List recent activity
 echo -e "\nRecent messages:"
-echo "$SNAPSHOT" | jq -r '.data.messages[] | "  \(.channel_name): \(.text[0:50])"'
+echo "$SNAPSHOT" | jq -r '.recent_messages[] | "  \(.channel_name): \(.text[0:50])"'
 ```
 
 **When to use**: Initial context gathering, status reports, workspace summaries.
@@ -105,7 +105,7 @@ CHANNEL="general"
 
 # Send initial message
 RESULT=$(agent-slack message send "$CHANNEL" "Starting deployment...")
-THREAD_TS=$(echo "$RESULT" | jq -r '.data.ts')
+THREAD_TS=$(echo "$RESULT" | jq -r '.ts')
 
 # Send updates in thread
 agent-slack message send "$CHANNEL" "Building application..." --thread "$THREAD_TS"
@@ -135,13 +135,13 @@ CHANNEL="support"
 MESSAGES=$(agent-slack message list "$CHANNEL" --limit 50)
 
 # Find messages containing "urgent"
-URGENT_MESSAGES=$(echo "$MESSAGES" | jq -r '.data.messages[] | select(.text | contains("urgent"))')
+URGENT_MESSAGES=$(echo "$MESSAGES" | jq -r '.[] | select(.text | contains("urgent"))')
 
 # Process each urgent message
 echo "$URGENT_MESSAGES" | jq -c '.' | while read -r msg; do
-  TS=$(echo "$msg" | jq -r '.ts')
-  TEXT=$(echo "$msg" | jq -r '.text')
-  USER=$(echo "$msg" | jq -r '.user')
+  TS=$(echo "$msg" | jq -r '.ts // ""')
+  TEXT=$(echo "$msg" | jq -r '.text // ""')
+  USER=$(echo "$msg" | jq -r '.user // ""')
 
   echo "Found urgent message from $USER: $TEXT"
 
@@ -169,10 +169,10 @@ for channel in "${CHANNELS[@]}"; do
   echo "Posting to #$channel..."
   RESULT=$(agent-slack message send "$channel" "$MESSAGE")
 
-  if echo "$RESULT" | jq -e '.success' > /dev/null; then
-    echo "  ✓ Posted to #$channel"
-  else
+  if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
     echo "  ✗ Failed to post to #$channel"
+  else
+    echo "  ✓ Posted to #$channel"
   fi
 
   # Rate limit: Don't spam Slack API
@@ -195,8 +195,11 @@ REPORT_FILE="./daily-report.pdf"
 # Upload file
 UPLOAD_RESULT=$(agent-slack file upload "$CHANNEL" "$REPORT_FILE")
 
-if echo "$UPLOAD_RESULT" | jq -e '.success' > /dev/null; then
-  FILE_ID=$(echo "$UPLOAD_RESULT" | jq -r '.data.id')
+if echo "$UPLOAD_RESULT" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Upload failed: $(echo "$UPLOAD_RESULT" | jq -r '.error')"
+  exit 1
+else
+  FILE_ID=$(echo "$UPLOAD_RESULT" | jq -r '.id')
   echo "File uploaded: $FILE_ID"
 
   # Send context message
@@ -204,9 +207,6 @@ if echo "$UPLOAD_RESULT" | jq -e '.success' > /dev/null; then
   • 95% test coverage
   • 3 bugs fixed
   • 2 new features deployed"
-else
-  echo "Upload failed: $(echo "$UPLOAD_RESULT" | jq -r '.error.message')"
-  exit 1
 fi
 ```
 
@@ -252,7 +252,7 @@ USERNAME="john.doe"
 
 # Get user info
 USERS=$(agent-slack user list)
-USER_ID=$(echo "$USERS" | jq -r ".data.users[] | select(.name==\"$USERNAME\") | .id")
+USER_ID=$(echo "$USERS" | jq -r ".[] | select(.name==\"$USERNAME\") | .id")
 
 if [ -z "$USER_ID" ]; then
   echo "User $USERNAME not found"
@@ -278,7 +278,7 @@ CHANNEL="deployments"
 
 # Send deployment message
 RESULT=$(agent-slack message send "$CHANNEL" "Deploying v2.1.0 to production...")
-MSG_TS=$(echo "$RESULT" | jq -r '.data.ts')
+MSG_TS=$(echo "$RESULT" | jq -r '.ts')
 
 # Mark as in-progress
 agent-slack reaction add "$CHANNEL" "$MSG_TS" hourglass_flowing_sand
@@ -314,20 +314,20 @@ send_with_retry() {
 
     RESULT=$(agent-slack message send "$channel" "$message")
 
-    if echo "$RESULT" | jq -e '.success' > /dev/null; then
+    if echo "$RESULT" | jq -e '.ts' > /dev/null 2>&1; then
       echo "Message sent successfully!"
       return 0
     fi
 
-    ERROR_CODE=$(echo "$RESULT" | jq -r '.error.code')
+    ERROR=$(echo "$RESULT" | jq -r '.error // "unknown"')
 
     # Don't retry on certain errors
-    if [ "$ERROR_CODE" = "INVALID_CHANNEL" ]; then
+    if [ "$ERROR" = "channel_not_found" ]; then
       echo "Channel not found - not retrying"
       return 1
     fi
 
-    echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+    echo "Failed: $ERROR"
 
     if [ $attempt -lt $max_attempts ]; then
       sleep $((attempt * 2))  # Exponential backoff
@@ -364,7 +364,7 @@ MESSAGES=$(agent-slack message list "$CHANNEL" --limit 100)
 
 # Filter messages from last 24 hours
 RECENT=$(echo "$MESSAGES" | jq --arg oldest "$OLDEST_TS" '
-  .data.messages[] |
+  .[] |
   select((.ts | tonumber) > ($oldest | tonumber))
 ')
 
@@ -413,7 +413,7 @@ if [ "$DISK_USAGE" -gt 80 ]; then
 
   # Add urgent reaction
   RESULT=$(agent-slack message list "$CHANNEL" --limit 1)
-  MSG_TS=$(echo "$RESULT" | jq -r '.data.messages[0].ts')
+  MSG_TS=$(echo "$RESULT" | jq -r '.[0].ts')
   agent-slack reaction add "$CHANNEL" "$MSG_TS" rotating_light
 fi
 ```
@@ -427,10 +427,10 @@ fi
 ```bash
 # Good
 RESULT=$(agent-slack message send general "Hello")
-if echo "$RESULT" | jq -e '.success' > /dev/null; then
-  echo "Success!"
+if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
 else
-  echo "Failed: $(echo "$RESULT" | jq -r '.error.message')"
+  echo "Success: $(echo "$RESULT" | jq -r '.ts')"
 fi
 
 # Bad
@@ -443,7 +443,7 @@ agent-slack message send general "Hello"  # No error checking
 # Good - readable and maintainable
 agent-slack message send general "Hello"
 
-# Also good - use ID from snapshot
+# Also good — use ID from snapshot
 SNAPSHOT=$(agent-slack snapshot)
 CHANNEL_ID=$(echo "$SNAPSHOT" | jq -r '.channels[0].id')
 agent-slack message send "$CHANNEL_ID" "Hello"
@@ -471,7 +471,7 @@ done
 
 ```bash
 # Good - use threads for related messages
-PARENT_TS=$(agent-slack message send general "Task started" | jq -r '.data.ts')
+PARENT_TS=$(agent-slack message send general "Task started" | jq -r '.ts')
 agent-slack message send general "Step 1 complete" --thread "$PARENT_TS"
 agent-slack message send general "Step 2 complete" --thread "$PARENT_TS"
 
@@ -527,7 +527,7 @@ agent-slack message send general "Hello"
 # Continues even if it failed
 
 # Good
-if ! agent-slack message send general "Hello" | jq -e '.success' > /dev/null; then
+if agent-slack message send general "Hello" | jq -e '.error' > /dev/null 2>&1; then
   echo "Failed to send message"
   exit 1
 fi
@@ -549,6 +549,72 @@ done
 agent-slack message send general "$MESSAGE"
 ```
 
+## Pattern: Schedule and Manage Messages
+
+**Use case**: Schedule a message for later delivery and manage the queue.
+
+```bash
+#!/bin/bash
+
+# Schedule a message for a specific time (Unix timestamp)
+SCHEDULED=$(agent-slack message schedule general "Weekly report" 1700000000)
+SCHED_ID=$(echo "$SCHEDULED" | jq -r '.id // .scheduled_message_id')
+
+# List all scheduled messages
+agent-slack message scheduled-list
+
+# Cancel a scheduled message
+agent-slack message scheduled-delete general "$SCHED_ID"
+```
+
+## Pattern: Channel Setup Automation
+
+**Use case**: Create a project channel and configure it.
+
+```bash
+#!/bin/bash
+
+PROJECT="project-alpha"
+
+# Create the channel
+CHANNEL=$(agent-slack channel create "$PROJECT")
+CHANNEL_ID=$(echo "$CHANNEL" | jq -r '.id')
+
+# Set topic and purpose
+agent-slack channel set-topic "$CHANNEL_ID" "Discussion for Project Alpha"
+agent-slack channel set-purpose "$CHANNEL_ID" "Coordinate development tasks for Alpha release"
+
+# Invite team members
+agent-slack channel invite "$CHANNEL_ID" "U001,U002,U003"
+
+# Add a useful bookmark
+agent-slack bookmark add "$CHANNEL_ID" "Project Wiki" "https://wiki.example.com/alpha"
+
+# Pin the welcome message
+WELCOME=$(agent-slack message send "$CHANNEL_ID" "Welcome to Project Alpha! 🎉")
+WELCOME_TS=$(echo "$WELCOME" | jq -r '.ts')
+agent-slack pin add "$CHANNEL_ID" "$WELCOME_TS"
+```
+
+## Pattern: Reminder Workflows
+
+**Use case**: Set reminders for follow-ups.
+
+```bash
+#!/bin/bash
+
+# Set a reminder for yourself
+agent-slack reminder add "Review the PR" 1700000000
+
+# Set a reminder for someone else
+agent-slack reminder add "Submit timesheet" 1700000000 --user U0ABC123
+
+# List and manage reminders
+agent-slack reminder list
+agent-slack reminder complete Rm001
+agent-slack reminder delete Rm002
+```
+
 ## See Also
 
 - [Authentication Guide](authentication.md) - Setting up credentials

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 1.14.0
+version: 2.0.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

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

@@ -178,6 +178,58 @@ send_with_retry() {
 send_with_retry "C0ACZKTDDC0" "Important notification!"
 ```
 
+## Pattern 7: Multi-Bot Switching
+
+**Use case**: Use different bots for different tasks
+
+```bash
+#!/bin/bash
+
+# Set up 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 configured bots
+agent-slackbot auth list
+
+# Switch active bot
+agent-slackbot auth use deploy
+
+# Or use --bot flag for a single command without switching
+agent-slackbot message send C0ACZKTDDC0 "Deploy starting..." --bot deploy
+agent-slackbot message send C0ACZKTDDC0 "Error rate spike!" --bot alert
+
+# Remove a bot you no longer need
+agent-slackbot auth remove alert
+```
+
+**When to use**: Separate bots for deployment, alerting, support, etc.
+
+## Pattern 8: Get a Single Message
+
+**Use case**: Retrieve a specific message by timestamp for processing
+
+```bash
+#!/bin/bash
+
+CHANNEL="C0ACZKTDDC0"
+MESSAGE_TS="1234567890.123456"
+
+# Get the exact message
+MSG=$(agent-slackbot message get "$CHANNEL" "$MESSAGE_TS")
+TEXT=$(echo "$MSG" | jq -r '.text // ""')
+USER=$(echo "$MSG" | jq -r '.user // ""')
+
+echo "Message from $USER: $TEXT"
+
+# Get thread replies for that message
+REPLIES=$(agent-slackbot message replies "$CHANNEL" "$MESSAGE_TS" --limit 50)
+REPLY_COUNT=$(echo "$REPLIES" | jq 'length')
+echo "Thread has $REPLY_COUNT replies"
+```
+
+**When to use**: Fetching specific messages for processing, reading full threads.
+
 ## Best Practices
 
 ### 1. Use Channel IDs, Not Names

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 1.14.0
+version: 2.0.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:
@@ -343,6 +343,54 @@ Common errors:
 
 Credentials stored in `~/.config/agent-messenger/teams-credentials.json` (0600 permissions). See [references/authentication.md](references/authentication.md) for format and security details.
 
+## SDK: Programmatic Usage
+
+`TeamsClient` is available as a TypeScript SDK for building scripts and automations.
+
+### Setup
+
+```typescript
+import { TeamsClient } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login()
+```
+
+Or with manual credential management:
+
+```typescript
+import { TeamsClient, TeamsCredentialManager } from 'agent-messenger/teams'
+
+const manager = new TeamsCredentialManager()
+const creds = await manager.getTokenWithExpiry()
+if (!creds) {
+  throw new Error('Teams token not found. Run auth extract first.')
+}
+const client = await new TeamsClient().login({ token: creds.token, tokenExpiresAt: creds.tokenExpiresAt })
+```
+
+### Example
+
+```typescript
+// List teams
+const teams = await client.listTeams()
+
+// List channels in a team
+const channels = await client.listChannels(teams[0].id)
+
+// Send a message
+const msg = await client.sendMessage(teams[0].id, channels[0].id, 'Hello from SDK!')
+
+// React to it
+await client.addReaction(teams[0].id, channels[0].id, msg.id, 'like')
+
+// Upload a file
+await client.uploadFile(teams[0].id, channels[0].id, './report.pdf')
+```
+
+### Full API Reference
+
+See the [Teams SDK documentation](https://agent-messenger.dev/docs/sdk/teams) for complete method signatures, types, schemas, and examples.
+
 ## Limitations
 
 - No real-time events / WebSocket connection

package/skills/agent-telegram/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: agent-telegram
+description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
+version: 2.0.0
+allowed-tools: Bash(agent-telegram:*)
+---
+
+# Agent Telegram
+
+A TDLib-backed Telegram CLI for AI agents. The CLI auto-provisions API credentials via my.telegram.org — users never need to know or provide api_id/api_hash.
+
+Use one of these entrypoints:
+- Global install: `agent-telegram ...`
+- One-off execution: `bunx --package agent-messenger agent-telegram ...`
+
+## Quick Start
+
+```bash
+# Login (CLI auto-provisions API credentials)
+agent-telegram auth login --phone +821012345678
+
+# List chats
+agent-telegram chat list
+
+# Send a message
+agent-telegram message send <chat-id-or-@username> "Hello from agent-telegram"
+```
+
+## Authentication Flow
+
+Telegram auth is stateful. TDLib persists authorization state locally, so each call picks up where the last one left off — no custom state management needed. The CLI automatically provisions API credentials via my.telegram.org during login — no manual credential setup required.
+
+### Agent Behavior (MANDATORY)
+
+When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands — the agent runs everything. Never mention api_id, api_hash, or my.telegram.org to the user — these are internal details handled by the CLI.
+
+**Step 1: Check for existing accounts**
+
+```bash
+agent-telegram auth list
+```
+
+If accounts exist → `agent-telegram auth use <account-id>` and retry the original command.
+
+**Step 2: If no accounts, ask for phone number**
+
+Ask the user for their Telegram phone number (international format, e.g. `+821012345678`). This is the ONLY thing the user needs to provide to start login.
+
+**Step 3: Start login — CLI auto-provisions API credentials**
+
+```bash
+agent-telegram auth login --phone <phone>
+# → {"next_action":"provide_provisioning_code","message":"A code was sent to your Telegram app. Provide it via --provisioning-code."}
+```
+
+The CLI sends a verification code to the user's Telegram app for credential provisioning. This is NOT the TDLib login code — it's for obtaining API credentials automatically.
+
+**Step 4: Ask user for the provisioning code, then provide it**
+
+```bash
+agent-telegram auth login --phone <phone> --provisioning-code <code>
+# → {"next_action":"provide_code","message":"Enter the code sent to your Telegram app via --code."}
+```
+
+After provisioning succeeds, the CLI continues to TDLib login and sends ANOTHER code to the user's Telegram app for actual authentication.
+
+**Step 5: Ask user for the TDLib login code, then provide it**
+
+```bash
+agent-telegram auth login --code <code>
+# → {"authenticated":true,...}
+# or if 2FA enabled:
+# → {"next_action":"provide_password","message":"2FA password required via --password."}
+```
+
+**Step 6: If 2FA required, ask user for password, then provide it**
+
+```bash
+agent-telegram auth login --password <password>
+```
+
+**Step 7: Retry the original command**
+
+After successful auth, immediately execute whatever the user originally asked for.
+
+**IMPORTANT: Two separate codes**
+
+The login flow may require TWO codes from the user:
+1. **Provisioning code** (via `--provisioning-code`) — for auto-obtaining API credentials from my.telegram.org
+2. **TDLib login code** (via `--code`) — for Telegram account authentication
+
+When asking the user for codes, be clear about which one you need. Say "I need the code sent to your Telegram app" for both — the user sees them as Telegram verification codes.
+
+### Common Auth Commands
+
+```bash
+agent-telegram auth status    # Check current state
+agent-telegram auth list      # List stored accounts
+agent-telegram auth use <id>  # Switch accounts
+agent-telegram auth logout    # Logout
+```
+
+## Common Commands
+
+```bash
+# Search chats by title or username
+agent-telegram chat search "project"
+
+# Get chat metadata
+agent-telegram chat get @durov
+
+# List recent messages
+agent-telegram message list @durov --limit 10
+
+# Logout
+agent-telegram auth logout
+```
+
+## Notes
+
+- Telegram phone numbers must be in international format, for example `+14155551234`.
+- TDLib persists local account state under `~/.config/agent-messenger/telegram/`.
+- `agent-telegram` returns JSON by default and `--pretty` for indented output.