agent-messenger 1.15.0 → 2.1.0

package/skills/agent-webex/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: agent-webex
+description: Interact with Cisco Webex - send messages, read spaces, manage memberships
+version: 2.1.0
+allowed-tools: Bash(agent-webex:*)
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - agent-webex
+    install:
+      - kind: node
+        package: agent-messenger
+        bins: [agent-webex]
+---
+
+# Agent Webex
+
+A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex through a simple command interface. Uses OAuth Device Grant flow, zero configuration required.
+
+## Quick Start
+
+```bash
+# Log in (opens browser automatically)
+agent-webex auth login
+
+# Get workspace snapshot
+agent-webex snapshot
+
+# Send a message
+agent-webex message send <space-id> "Hello from AI agent!"
+
+# List spaces
+agent-webex space list
+```
+
+## Authentication
+
+Webex uses OAuth Device Grant flow with built-in Integration credentials. No tokens to copy, no developer portal setup needed.
+
+`agent-webex auth login` starts the Device Grant flow: it displays a verification URL and user code, then opens the browser. You enter the code at the verification page and approve access. The CLI polls for the token automatically. Access and refresh tokens are stored locally, and the access token auto-refreshes via the refresh token.
+
+Optionally, pass `--token <bot-token>` for bot token auth. Or pass `--client-id <id> --client-secret <secret>` to use your own Webex Integration credentials instead of the built-in ones.
+
+Env vars `AGENT_WEBEX_CLIENT_ID` / `AGENT_WEBEX_CLIENT_SECRET` can also override the built-in credentials.
+
+```bash
+# Log in (Device Grant flow, opens browser)
+agent-webex auth login
+
+# Log in with custom Integration credentials
+agent-webex auth login --client-id <id> --client-secret <secret>
+
+# Log in with a bot token
+agent-webex auth login --token <token>
+
+# Check auth status
+agent-webex auth status
+
+# Log out
+agent-webex auth logout
+```
+
+### How Login Works
+
+1. Run `agent-webex auth login`
+2. CLI requests a device code from Webex
+3. Browser opens to Webex verification page
+4. Enter the displayed code and sign in
+5. CLI automatically detects approval and stores tokens
+6. Access token auto-refreshes via refresh token
+
+### Token Types
+
+- **OAuth Device Grant (default)**: Zero-config login. Access token auto-refreshes. Built-in Integration credentials used unless overridden.
+- **Bot Token**: Pass via `--token` flag. Never expires. Best for CI/CD.
+- **Custom Integration**: Pass `--client-id` + `--client-secret` or set env vars for your own Webex Integration.
+
+**IMPORTANT**: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser's network inspector. Always use `agent-webex auth login` for interactive authentication.
+
+For detailed token management, see [references/authentication.md](references/authentication.md).
+
+## Memory
+
+The agent maintains a `~/.config/agent-messenger/MEMORY.md` file as persistent memory across sessions. This is agent-managed, the CLI does not read or write this file. Use the `Read` and `Write` tools to manage your memory file.
+
+### Reading Memory
+
+At the **start of every task**, read `~/.config/agent-messenger/MEMORY.md` using the `Read` tool to load any previously discovered space IDs, member info, and preferences.
+
+- If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
+- If the file can't be read (permissions, missing directory), proceed without memory. Don't error out.
+
+### Writing Memory
+
+After discovering useful information, update `~/.config/agent-messenger/MEMORY.md` using the `Write` tool. Write triggers include:
+
+- After discovering space IDs and titles (from `space list`, `snapshot`, etc.)
+- After discovering member IDs and names (from `member list`, `snapshot`, etc.)
+- After the user gives you an alias or preference ("call this the standup space", "my main space is X")
+- After discovering space structure (group vs direct spaces)
+
+When writing, include the **complete file content**. The `Write` tool overwrites the entire file.
+
+### What to Store
+
+- Space IDs with titles
+- Member IDs with display names and space context
+- User-given aliases ("standup space", "engineering space")
+- Token type in use (PAT vs bot)
+- Any user preference expressed during interaction
+
+### What NOT to Store
+
+Never store tokens, credentials, or any sensitive data. Never store full message content (just IDs and space context).
+
+### Handling Stale Data
+
+If a memorized ID returns an error (space not found, member not found), remove it from `MEMORY.md`. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.
+
+### Format / Example
+
+```markdown
+# Agent Messenger Memory
+
+## Spaces
+
+- `space-id-1` — Engineering (group)
+- `space-id-2` — Alice / Bob (direct)
+- `space-id-3` — Standups (group)
+
+## Members (Engineering)
+
+- `person-id-1` — Alice Chen (engineering lead)
+- `person-id-2` — Bob Park (backend)
+
+## Aliases
+
+- "standup" -> `space-id-3` (Standups)
+- "eng" -> `space-id-1` (Engineering)
+
+## Notes
+
+- Using bot token (no expiry)
+- Main space is "Engineering"
+```
+
+> Memory lets you skip repeated `space list` and `member list` calls. When you already know an ID from a previous session, use it directly.
+
+## Commands
+
+### Auth Commands
+
+```bash
+# Log in (Device Grant flow, opens browser)
+agent-webex auth login
+
+# Log in with custom Integration credentials
+agent-webex auth login --client-id <id> --client-secret <secret>
+
+# Log in with a bot token
+agent-webex auth login --token <token>
+
+# Check auth status
+agent-webex auth status
+
+# Log out
+agent-webex auth logout
+```
+
+### Space Commands
+
+```bash
+# List spaces
+agent-webex space list
+agent-webex space list --type group
+agent-webex space list --type direct
+agent-webex space list --limit 20
+
+# Get space info
+agent-webex space info <space-id>
+```
+
+### Message Commands
+
+```bash
+# Send a message
+agent-webex message send <space-id> <text>
+agent-webex message send <space-id> "Hello world"
+
+# Send a markdown message
+agent-webex message send <space-id> "**Bold** and _italic_" --markdown
+
+# List messages in a space
+agent-webex message list <space-id>
+agent-webex message list <space-id> --limit 50
+
+# Get a single message by ID
+agent-webex message get <message-id>
+
+# Delete a message
+agent-webex message delete <message-id>
+agent-webex message delete <message-id> --force
+
+# Edit a message
+agent-webex message edit <message-id> <space-id> <text>
+agent-webex message edit <message-id> <space-id> "Updated text" --markdown
+```
+
+### Member Commands
+
+```bash
+# List members of a space
+agent-webex member list <space-id>
+agent-webex member list <space-id> --limit 100
+```
+
+### Snapshot Command
+
+Get comprehensive workspace state for AI agents:
+
+```bash
+# Full snapshot
+agent-webex snapshot
+
+# Filtered snapshots
+agent-webex snapshot --spaces-only
+agent-webex snapshot --members-only
+
+# Limit messages per space
+agent-webex snapshot --limit 10
+```
+
+Returns JSON with:
+
+- Spaces (id, title, type, created)
+- Recent messages (id, text, personEmail, created)
+- Members (id, personDisplayName, personEmail)
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "id": "Y2lzY29zcGFyazovL...",
+  "text": "Hello world",
+  "personEmail": "alice@example.com",
+  "created": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-webex space list --pretty
+```
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "Not authenticated. Run \"auth login\" first."
+}
+```
+
+Common errors:
+
+- `Not authenticated`: No valid token. Run `auth login` first
+- `Device authorization timed out`: User didn't complete verification in time. Run `auth login` again.
+- `401 Unauthorized`: Token expired or invalid. Re-run `auth login`
+- `429 Too Many Requests`: Rate limited. Wait and retry (Webex allows ~600 requests per minute)
+- `404 Not Found`: Invalid space ID, message ID, or resource
+- `Space not found`: Invalid space ID
+- `Message not found`: Invalid message ID
+
+## Configuration
+
+Credentials stored in `~/.config/agent-messenger/webex-credentials.json` (0600 permissions):
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1234567890,
+  "clientId": "...",
+  "clientSecret": "..."
+}
+```
+
+See [references/authentication.md](references/authentication.md) for format and security details.
+
+## SDK: Programmatic Usage
+
+`WebexClient` is available as a TypeScript SDK for building scripts and automations.
+
+### Setup
+
+```typescript
+import { WebexClient } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login()
+```
+
+### Example
+
+```typescript
+// List spaces
+const spaces = await client.listSpaces()
+
+// List members in a space
+const members = await client.listMembers(spaces[0].id)
+
+// Send a message
+const msg = await client.sendMessage(spaces[0].id, 'Hello from SDK!')
+
+// Send markdown
+await client.sendMessage(spaces[0].id, '**Status**: All systems go', { markdown: true })
+```
+
+### Full API Reference
+
+See the [Webex SDK documentation](https://agent-messenger.dev/docs/sdk/webex) for complete method signatures, types, schemas, and examples.
+
+## Limitations
+
+- No real-time events / WebSocket connection
+- No file upload or download
+- No reactions / emoji support
+- No thread support
+- No message search
+- No voice/video or meeting support
+- No space management (create/delete spaces, roles)
+
+## Troubleshooting
+
+### Token refresh failed
+
+OAuth tokens auto-refresh, so expiration is handled automatically. If a refresh fails (revoked access, network issues), re-run:
+
+```bash
+agent-webex auth login
+```
+
+Bot tokens never expire and don't need refreshing.
+
+### `agent-webex: command not found`
+
+**`agent-webex` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+If the package is installed globally, use `agent-webex` directly:
+
+```bash
+agent-webex space list
+```
+
+If the package is NOT installed, use `npx -y` by default. **Do NOT ask the user which package runner to use.** Just run it:
+
+```bash
+npx -y agent-messenger webex space list
+bunx agent-messenger webex space list
+pnpm dlx agent-messenger webex space list
+```
+
+> If you already know the user's preferred package runner (e.g., `bunx`, `pnpm dlx`), use that instead.
+
+**NEVER run `npx agent-webex`, `bunx agent-webex`, or `pnpm dlx agent-webex`**. It will fail or install a wrong package since `agent-webex` is not the npm package name.
+
+### Rate limiting (429)
+
+Webex allows roughly 600 API calls per minute. If you hit a 429, wait a few seconds and retry. For bulk operations, add a `sleep 1` between requests.
+
+### Other errors
+
+For auth troubleshooting (token types, storage, permissions), see [references/authentication.md](references/authentication.md).
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)

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

@@ -0,0 +1,318 @@
+# Authentication Guide
+
+## Overview
+
+agent-webex supports three authentication methods against the Webex REST API (`https://webexapis.com/v1`):
+
+1. **OAuth Device Grant** (default): Zero-config. Run `auth login`, approve in browser, done. Tokens refresh automatically.
+2. **Bot Token**: Pass via `auth login --token`. Never expires. Best for CI/CD.
+3. **Personal Access Token (PAT)**: Pass via `auth login --token`. Expires in 12 hours. For quick testing.
+
+## Token Types
+
+### OAuth Device Grant (default)
+
+The primary authentication method. No credentials to copy, no developer portal setup required.
+
+- **How it works**: Run `agent-webex auth login`. The CLI requests a device code from Webex, opens your browser, and waits for you to approve. Once approved, access and refresh tokens are stored automatically.
+- **Access token lifetime**: 14 days
+- **Refresh token lifetime**: 90 days
+- **Auto-refresh**: The CLI refreshes expired access tokens automatically using the stored refresh token. No manual intervention needed until the refresh token itself expires (90 days).
+- **Permissions**: `spark:all` scope (full access to your Webex account)
+- **Best for**: Interactive use, development, any scenario where a human can approve via browser
+
+```bash
+agent-webex auth login
+```
+
+The CLI ships with built-in Integration credentials so this works out of the box. You can override them with your own (see [Environment Variables](#environment-variables)).
+
+### Bot Token
+
+A permanent token tied to a Webex bot identity.
+
+- **Lifetime**: Never expires (unless you regenerate it)
+- **How to get one**: Create a bot at https://developer.webex.com/my-apps/new/bot. The token is shown once at creation time. Save it immediately.
+- **Permissions**: The bot can only interact with spaces it has been added to
+- **Best for**: Long-running automations, CI/CD pipelines, production scripts
+
+```bash
+agent-webex auth login --token "YOUR_BOT_TOKEN_HERE"
+```
+
+### Personal Access Token (PAT)
+
+A short-lived token for development and testing.
+
+- **Lifetime**: 12 hours from generation
+- **How to get one**: Visit https://developer.webex.com/docs/getting-started and copy the token shown on the page
+- **Permissions**: Full access to everything your Webex account can do
+- **Best for**: Quick testing, one-off scripts
+
+```bash
+agent-webex auth login --token "YOUR_PAT_HERE"
+```
+
+## Logging In
+
+```bash
+# Device Grant (default, zero-config)
+agent-webex auth login
+
+# With custom Integration credentials
+agent-webex auth login --client-id <id> --client-secret <secret>
+
+# Bot token
+agent-webex auth login --token <bot-token>
+
+# PAT
+agent-webex auth login --token <pat>
+```
+
+When using `--token`, the CLI validates the token against the Webex API before saving. If validation fails, you'll see an error and the token won't be stored.
+
+When using Device Grant, the CLI prints a URL and code, opens your browser, then polls until you approve (or the code expires).
+
+## Checking Status
+
+```bash
+agent-webex auth status
+```
+
+Output when authenticated:
+
+```json
+{
+  "authenticated": true,
+  "user": {
+    "id": "Y2lz...",
+    "displayName": "Alice Chen",
+    "emails": ["alice@example.com"]
+  }
+}
+```
+
+Output when not authenticated:
+
+```json
+{
+  "error": "Not authenticated. Run \"auth login\" first."
+}
+```
+
+## Logging Out
+
+```bash
+agent-webex auth logout
+```
+
+This removes the stored credentials from disk.
+
+## Credential Storage
+
+### Location
+
+```
+~/.config/agent-messenger/webex-credentials.json
+```
+
+### Format
+
+OAuth credentials (from Device Grant):
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1234567890,
+  "clientId": "...",
+  "clientSecret": "...",
+  "tokenType": "oauth"
+}
+```
+
+Manual credentials (from `--token`):
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "",
+  "expiresAt": 0,
+  "tokenType": "manual"
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Credentials are stored in plaintext (same approach as other agent-messenger platforms)
+- Writes are atomic (tmp file + rename) to prevent corruption
+- Keep this file secure. It grants access to your Webex account
+- Built-in OAuth credentials are public bootstrap credentials, not secrets
+- Custom client secrets (from `--client-id`/`--client-secret` or env vars) are stored in plaintext alongside tokens
+- Bot tokens never expire. Treat them like passwords
+- PATs auto-expire in 12 hours, which limits exposure
+
+## Token Lifecycle
+
+### OAuth Device Grant
+
+```
+auth login -> Device code -> Browser approval -> Access token (14 days) + Refresh token (90 days)
+                                                        |
+                                                  Token expires
+                                                        |
+                                                  Auto-refresh via refresh token
+                                                        |
+                                                  Refresh token expires (90 days)
+                                                        |
+                                                  Re-run "auth login"
+```
+
+The CLI checks token expiry before each API call and refreshes automatically when needed. You won't notice this happening.
+
+### Bot Tokens
+
+```
+Created with bot registration -> Valid forever -> Only invalidated if you regenerate
+```
+
+Bot tokens are ideal for automation. The bot must be added to each space it needs to interact with.
+
+### Personal Access Tokens
+
+```
+Generated at developer.webex.com -> Valid for 12 hours -> Expires -> Generate a new one
+```
+
+PATs are the quickest way to get started but require manual renewal. For scripts that run longer than 12 hours, use a bot token or Device Grant.
+
+## Environment Variables
+
+Override the built-in Integration credentials with your own:
+
+| Variable | Description |
+|---|---|
+| `AGENT_WEBEX_CLIENT_ID` | Webex Integration client ID |
+| `AGENT_WEBEX_CLIENT_SECRET` | Webex Integration client secret |
+
+Both must be set together. When set, `auth login` (without `--token`) uses these instead of the built-in credentials.
+
+Legacy aliases `AGENT_MESSENGER_WEBEX_CLIENT_ID` and `AGENT_MESSENGER_WEBEX_CLIENT_SECRET` are also supported.
+
+## Troubleshooting
+
+### "Not authenticated"
+
+No credentials stored. Log in first:
+
+```bash
+agent-webex auth login
+```
+
+### "401 Unauthorized"
+
+Token is expired or invalid.
+
+**If using Device Grant**: The CLI auto-refreshes tokens, so this usually means the refresh token has expired (after 90 days). Run `agent-webex auth login` again.
+
+**If using a PAT**: Generate a new one at https://developer.webex.com/docs/getting-started
+
+```bash
+agent-webex auth login --token <new-pat>
+```
+
+**If using a bot token**: Bot tokens don't expire. Double-check you copied the full token. If you lost it, regenerate at https://developer.webex.com/my-apps.
+
+### "Device authorization failed"
+
+The device code request was rejected. Possible causes:
+
+- Network connectivity issues
+- Custom client ID is invalid or revoked
+- Webex API is temporarily unavailable
+
+### "Device authorization timed out"
+
+You didn't approve the request in the browser before the code expired. Run `auth login` again.
+
+### "Token validation failed"
+
+The token was rejected by the Webex API during login. Common causes:
+
+- Token was copied incorrectly (missing characters, extra whitespace)
+- Token has already expired (PATs last 12 hours)
+- Token was revoked or regenerated
+
+### Permission errors on credentials file
+
+```bash
+# Fix permissions
+chmod 600 ~/.config/agent-messenger/webex-credentials.json
+```
+
+### Token works in browser but not in CLI
+
+Make sure you're using the actual API token, not a session cookie or CSRF token from the browser. The correct token comes from the Developer Portal's "Getting Started" page or from bot/integration creation.
+
+## Security Considerations
+
+### What agent-webex Can Access
+
+With a valid token, agent-webex has the same permissions as the token owner:
+
+- **OAuth Device Grant**: `spark:all` scope, full access to your Webex account
+- **PAT**: Read and write to all spaces you belong to, list members, send messages
+- **Bot**: Read and write only in spaces the bot has been added to
+
+### What agent-webex Cannot Do
+
+- Access spaces you (or the bot) haven't been added to
+- Perform admin operations (unless the token owner is an admin)
+- Create or delete spaces (not implemented in the CLI)
+- Upload or download files (not implemented in the CLI)
+
+### Best Practices
+
+1. **Use Device Grant for interactive work**: Zero-config, auto-refreshing, scoped access
+2. **Use bot tokens for automation**: They don't expire and have scoped access
+3. **Protect credentials.json**: Never commit to version control
+4. **Rotate PATs regularly**: Don't reuse expired tokens. Generate fresh ones
+5. **Revoke compromised tokens**: Regenerate bot tokens at https://developer.webex.com/my-apps if compromised
+6. **Use custom Integration credentials for production**: Set `AGENT_WEBEX_CLIENT_ID` and `AGENT_WEBEX_CLIENT_SECRET` instead of relying on built-in bootstrap credentials
+
+## Manual Credential Setup (Advanced)
+
+If you need to create the credentials file manually:
+
+```bash
+# Create config directory
+mkdir -p ~/.config/agent-messenger
+
+# OAuth credentials
+cat > ~/.config/agent-messenger/webex-credentials.json << 'EOF'
+{
+  "accessToken": "YOUR_ACCESS_TOKEN",
+  "refreshToken": "YOUR_REFRESH_TOKEN",
+  "expiresAt": 1234567890000,
+  "clientId": "YOUR_CLIENT_ID",
+  "clientSecret": "YOUR_CLIENT_SECRET",
+  "tokenType": "oauth"
+}
+EOF
+
+# Or manual token
+cat > ~/.config/agent-messenger/webex-credentials.json << 'EOF'
+{
+  "accessToken": "YOUR_TOKEN_HERE",
+  "refreshToken": "",
+  "expiresAt": 0,
+  "tokenType": "manual"
+}
+EOF
+
+# Set secure permissions
+chmod 600 ~/.config/agent-messenger/webex-credentials.json
+```
+
+Always prefer `agent-webex auth login` over manual file creation. The login command validates tokens and handles the OAuth flow correctly.