agent-messenger 2.1.0 → 2.3.0

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.1.0
+version: 2.3.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:
@@ -16,12 +16,15 @@ metadata:
 
 # 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.
+A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex through a simple command interface. Supports browser token extraction (zero-config, sends as you) and OAuth Device Grant flow.
 
 ## Quick Start
 
 ```bash
-# Log in (opens browser automatically)
+# Extract token from browser (Chrome, Edge, Arc, Brave) — messages appear as you
+agent-webex auth extract
+
+# Or: Log in via OAuth Device Grant (opens browser, messages show "via agent-messenger")
 agent-webex auth login
 
 # Get workspace snapshot
@@ -36,10 +39,35 @@ 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.
+Webex supports two authentication methods:
+
+1. **Browser token extraction** (recommended): Extracts your first-party token from a Chromium browser where you're logged into web.webex.com. Messages appear as you — no "via" label.
+2. **OAuth Device Grant**: Opens a browser for you to authorize. Messages show "via agent-messenger" label.
+
+### Browser Token Extraction (Recommended)
+
+`agent-webex auth extract` reads your Webex session token from Chrome, Edge, Arc, or Brave. You must be logged into web.webex.com in one of these browsers. No configuration needed.
+
+```bash
+# Extract token from browser — messages appear as you
+agent-webex auth extract
+
+# With debug output
+agent-webex auth extract --debug
+```
+
+**Supported browsers**: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium
+
+**How it works**: The Webex web client stores its authentication token in the browser's localStorage. This CLI reads it directly from the browser's LevelDB files — no browser automation, no password prompts. The token is stored locally in `~/.config/agent-messenger/`.
+
+**When to re-extract**: Browser tokens expire. When your token expires, re-run `agent-webex auth extract` or let auto-extraction handle it (the CLI attempts extraction automatically on each run).
+
+### OAuth Device Grant (Fallback)
 
 `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.
 
+Note: Messages sent via OAuth Device Grant show "via agent-messenger" because the token is associated with a third-party Webex Integration.
+
 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.
@@ -61,22 +89,14 @@ agent-webex auth status
 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.
+- **Extracted (browser)**: First-party token from web.webex.com. Messages appear as you. Requires re-extraction when expired.
+- **OAuth Device Grant**: Zero-config login. Access token auto-refreshes. Messages show "via agent-messenger".
 - **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.
+**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 extract` or `agent-webex auth login` for authentication.
 
 For detailed token management, see [references/authentication.md](references/authentication.md).
 

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

@@ -2,17 +2,41 @@
 
 ## Overview
 
-agent-webex supports three authentication methods against the Webex REST API (`https://webexapis.com/v1`):
+agent-webex supports four 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.
+1. **Browser Token Extraction**: Extracts your first-party token and cached encryption keys from a Chromium browser where you're logged into web.webex.com. Supports all operations including encrypted messaging via the internal API. Zero-config.
+2. **OAuth Device Grant** (recommended for messaging): Zero-config. Run `auth login`, approve in browser, done. Tokens refresh automatically. Supports all operations including sending messages (shows "via agent-messenger").
+3. **Bot Token**: Pass via `auth login --token`. Never expires. Best for CI/CD.
+4. **Personal Access Token (PAT)**: Pass via `auth login --token`. Expires in 12 hours. For quick testing.
 
 ## Token Types
 
-### OAuth Device Grant (default)
+### Browser Token Extraction
 
-The primary authentication method. No credentials to copy, no developer portal setup required.
+Extracts your first-party Webex session token from a Chromium-based browser where you're logged into web.webex.com. Supports full messaging with end-to-end encryption. The extracted token uses Webex's internal conversation API for sending messages. Encryption keys are also extracted from the browser's cached KMS key store, enabling client-side JWE encryption so messages appear as encrypted in the Webex client.
+
+- **How it works**: Run `agent-webex auth extract`. The CLI scans Chromium browser profiles for Webex localStorage data (LevelDB files). It finds the `webex-storage` key containing `Credentials.@.supertoken` and extracts the access token. It also extracts `userId` from the Device namespace and cached KMS encryption keys from the unbounded storage — these keys enable end-to-end encrypted messaging via the internal API. No browser automation, no password prompts.
+- **Supported browsers**: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium
+- **Token lifetime**: Depends on Webex session policy (typically hours to days). Re-extract when expired.
+- **Auto-extraction**: The CLI attempts browser extraction automatically when no valid token is stored, so you often don't need to run `auth extract` manually.
+- **End-to-end encryption**: When encryption keys are found in the browser's cache, messages are encrypted client-side (JWE with AES-256-GCM) before sending via the internal conversation API. This ensures messages appear as encrypted in the Webex client. If no keys are found (e.g., the conversation hasn't been opened in the browser), messages fall back to plaintext.
+- **Best for**: Interactive use, sending messages as yourself without the "via" label
+
+```bash
+# Extract token from browser
+agent-webex auth extract
+
+# With debug output
+agent-webex auth extract --debug
+```
+
+**Requirements**: You must be logged into web.webex.com in a supported Chromium browser. The browser does not need to be running — the CLI reads directly from on-disk LevelDB files.
+
+**Limitations**: Direct messages (`message dm`) require an existing conversation with the recipient. The extracted token cannot create new 1:1 conversations — start one from the Webex app first, then use the CLI.
+
+### OAuth Device Grant
+
+The fallback authentication method when browser extraction is unavailable. 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
@@ -56,7 +80,10 @@ agent-webex auth login --token "YOUR_PAT_HERE"
 ## Logging In
 
 ```bash
-# Device Grant (default, zero-config)
+# Browser extraction (recommended — messages appear as you)
+agent-webex auth extract
+
+# Device Grant (fallback — messages show "via agent-messenger")
 agent-webex auth login
 
 # With custom Integration credentials
@@ -69,6 +96,8 @@ agent-webex auth login --token <bot-token>
 agent-webex auth login --token <pat>
 ```
 
+When using `auth extract`, the CLI reads your Webex session from the browser's LevelDB storage. No prompts, no browser automation.
+
 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).
@@ -118,6 +147,17 @@ This removes the stored credentials from disk.
 
 ### Format
 
+Extracted credentials (from `auth extract`):
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1234567890,
+  "tokenType": "extracted"
+}
+```
+
 OAuth credentials (from Device Grant):
 
 ```json
@@ -155,6 +195,19 @@ Manual credentials (from `--token`):
 
 ## Token Lifecycle
 
+### Browser Token Extraction
+
+```
+auth extract -> Scan browser LevelDB -> Extract supertoken -> Access token (session-based)
+                                                                     |
+                                                               Token expires
+                                                                     |
+                                                               Re-run "auth extract"
+                                                               (or auto-extraction on next CLI run)
+```
+
+Browser-extracted tokens have no refresh mechanism — when they expire, re-extract from the browser (where your active session keeps them fresh). The CLI attempts auto-extraction on each run, so manual re-extraction is rarely needed.
+
 ### OAuth Device Grant
 
 ```
@@ -274,8 +327,9 @@ With a valid token, agent-webex has the same permissions as the token owner:
 
 ### 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
+1. **Use browser extraction for interactive work**: Zero-config, messages appear as you, no "via" label
+2. **Use Device Grant as fallback**: When browser extraction isn't available (no Chromium browser, headless server)
+3. **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

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

@@ -8,14 +8,17 @@ This guide covers typical workflows for AI agents interacting with Cisco Webex u
 
 ## Auth Patterns
 
-### Pattern 1: Log In
+### Pattern 1: Authenticate
 
 **Use case**: First-time setup or token renewal
 
 ```bash
 #!/bin/bash
 
-# Default: Device Grant (zero-config, opens browser)
+# Recommended: Browser extraction (zero-config, sends as you, no "via" label)
+agent-webex auth extract
+
+# Fallback: Device Grant (zero-config, opens browser, shows "via agent-messenger")
 agent-webex auth login
 
 # With a bot token (never expires, for CI/CD)
@@ -25,7 +28,7 @@ agent-webex auth login --token "YOUR_BOT_TOKEN_HERE"
 agent-webex auth login --token "YOUR_PAT_HERE"
 ```
 
-**When to use**: Before any other command, if not already authenticated.
+**When to use**: Before any other command, if not already authenticated. Browser extraction is preferred — it auto-runs when no valid token is stored. It also extracts cached KMS encryption keys from the browser, enabling end-to-end encrypted messaging via the internal API.
 
 ### Pattern 2: Check Auth Status
 

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.1.0
+version: 2.3.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.1.0
+version: 2.3.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/platforms/channeltalk/commands/auth.test.ts

@@ -19,8 +19,8 @@ const mockListChannels = mock(() =>
     { id: 'ws-2', name: 'Workspace 2' },
   ]),
 )
-const mockExtract = mock<() => Promise<{ accountCookie: string; sessionCookie: string } | null>>(() =>
-  Promise.resolve({ accountCookie: 'fresh-account', sessionCookie: 'fresh-session' }),
+const mockExtract = mock(() =>
+  Promise.resolve([{ accountCookie: 'fresh-account', sessionCookie: 'fresh-session' }]),
 )
 
 import {
@@ -113,7 +113,7 @@ describe('channel auth commands', () => {
         { id: 'ws-2', name: 'Workspace 2' },
       ]),
     )
-    mockExtract.mockImplementation(() => Promise.resolve({ accountCookie: 'fresh-account', sessionCookie: 'fresh-session' }))
+    mockExtract.mockImplementation(() => Promise.resolve([{ accountCookie: 'fresh-account', sessionCookie: 'fresh-session' }]))
   })
 
   describe('extractAction', () => {
@@ -177,7 +177,7 @@ describe('channel auth commands', () => {
     })
 
     test('returns error when token extraction fails', async () => {
-      mockExtract.mockImplementation(() => Promise.resolve(null))
+      mockExtract.mockImplementation(() => Promise.resolve([]))
 
       const result = await extractAction()
 
@@ -192,7 +192,7 @@ describe('channel auth commands', () => {
       const result = await extractAction()
 
       expect(result).toEqual({
-        error: 'No workspaces found for this account.',
+        error: 'No valid credentials found. Make sure Channel Talk desktop app or browser is logged in.',
       })
     })
   })

package/src/platforms/channeltalk/commands/auth.ts

@@ -82,45 +82,51 @@ export async function extractAction(options: ActionOptions = {}): Promise<Extrac
     const extractor = createTokenExtractor()
     const extracted = await extractor.extract()
 
-    if (!extracted) {
+    if (extracted.length === 0) {
       return {
         error: 'No credentials. Make sure Channel Talk desktop app is installed and logged in.',
       }
     }
 
-    const client = await createChannelClient(extracted.accountCookie, extracted.sessionCookie)
-    const account = await client.getAccount()
-    const channels = await client.listChannels()
-
-    if (channels.length === 0) {
-      return { error: 'No workspaces found for this account.' }
-    }
-
-    const previousCurrent = await credManager.getCredentials()
-
-    for (const channel of channels) {
-      await credManager.setCredentials({
-        workspace_id: channel.id,
-        workspace_name: channel.name,
-        account_id: account.id,
-        account_name: account.name,
-        account_cookie: extracted.accountCookie,
-        session_cookie: extracted.sessionCookie,
-      })
+    for (const cookies of extracted) {
+      try {
+        const client = await createChannelClient(cookies.accountCookie, cookies.sessionCookie)
+        const account = await client.getAccount()
+        const channels = await client.listChannels()
+
+        if (channels.length === 0) continue
+
+        const previousCurrent = await credManager.getCredentials()
+
+        for (const channel of channels) {
+          await credManager.setCredentials({
+            workspace_id: channel.id,
+            workspace_name: channel.name,
+            account_id: account.id,
+            account_name: account.name,
+            account_cookie: cookies.accountCookie,
+            session_cookie: cookies.sessionCookie,
+          })
+        }
+
+        const previousStillExists = previousCurrent && channels.some((ch) => ch.id === previousCurrent.workspace_id)
+        const currentId = previousStillExists ? previousCurrent.workspace_id : channels[0].id
+        await credManager.setCurrent(currentId)
+
+        return {
+          success: true,
+          workspaces: channels.map((ch) => ({
+            workspace_id: ch.id,
+            workspace_name: ch.name,
+          })),
+          current_workspace_id: currentId,
+        }
+      } catch {
+        continue
+      }
     }
 
-    const previousStillExists = previousCurrent && channels.some((ch) => ch.id === previousCurrent.workspace_id)
-    const currentId = previousStillExists ? previousCurrent.workspace_id : channels[0].id
-    await credManager.setCurrent(currentId)
-
-    return {
-      success: true,
-      workspaces: channels.map((ch) => ({
-        workspace_id: ch.id,
-        workspace_name: ch.name,
-      })),
-      current_workspace_id: currentId,
-    }
+    return { error: 'No valid credentials found. Make sure Channel Talk desktop app or browser is logged in.' }
   } catch (error: unknown) {
     return { error: (error as Error).message }
   }

package/src/platforms/channeltalk/ensure-auth.test.ts

@@ -17,7 +17,7 @@ const mockGetCredentials = mock<() => Promise<
 >>(() => Promise.resolve(null))
 const mockSetCredentials = mock(() => Promise.resolve())
 const mockSetCurrent = mock(() => Promise.resolve(true))
-const mockExtract = mock(() => Promise.resolve(null))
+const mockExtract = mock(() => Promise.resolve([]))
 const mockGetAccount = mock(() => Promise.resolve({ id: 'acct-1', name: 'Alice' }))
 const mockListChannels = mock(() => Promise.resolve([{ id: 'ws-1', name: 'Workspace 1' }]))
 
@@ -58,17 +58,17 @@ describe('ensureChannelAuth', () => {
     mockGetCredentials.mockImplementation(() => Promise.resolve(null))
     mockSetCredentials.mockImplementation(() => Promise.resolve())
     mockSetCurrent.mockImplementation(() => Promise.resolve(true))
-    mockExtract.mockImplementation(() => Promise.resolve(null))
+    mockExtract.mockImplementation(() => Promise.resolve([]))
     mockGetAccount.mockImplementation(() => Promise.resolve({ id: 'acct-1', name: 'Alice' }))
     mockListChannels.mockImplementation(() => Promise.resolve([{ id: 'ws-1', name: 'Workspace 1' }]))
   })
 
   test('extracts and saves workspaces when no credentials exist', async () => {
     mockExtract.mockImplementation(() =>
-      Promise.resolve({
+      Promise.resolve([{
         accountCookie: 'account-cookie',
         sessionCookie: 'session-cookie',
-      }),
+      }]),
     )
     mockListChannels.mockImplementation(() =>
       Promise.resolve([
@@ -128,10 +128,10 @@ describe('ensureChannelAuth', () => {
     )
     mockGetAccount.mockImplementationOnce(() => Promise.reject(new Error('Unauthorized')))
     mockExtract.mockImplementation(() =>
-      Promise.resolve({
+      Promise.resolve([{
         accountCookie: 'fresh-account',
         sessionCookie: 'fresh-session',
-      }),
+      }]),
     )
 
     await ensureChannelAuth()

package/src/platforms/channeltalk/ensure-auth.ts

@@ -58,11 +58,11 @@ export async function ensureChannelAuth(): Promise<void> {
 
     const extractor = createTokenExtractor()
     const extracted = await extractor.extract()
-    if (!extracted) {
+    if (extracted.length === 0) {
       return
     }
 
-    const client = await createChannelClient(extracted.accountCookie, extracted.sessionCookie)
+    const client = await createChannelClient(extracted[0].accountCookie, extracted[0].sessionCookie)
     const account = await client.getAccount()
     const channels = await client.listChannels()
     if (channels.length === 0) {
@@ -76,8 +76,8 @@ export async function ensureChannelAuth(): Promise<void> {
       workspace_name: currentChannel.name,
       account_id: account.id,
       account_name: account.name,
-      account_cookie: extracted.accountCookie,
-      session_cookie: extracted.sessionCookie,
+      account_cookie: extracted[0].accountCookie,
+      session_cookie: extracted[0].sessionCookie,
     })
 
     for (const channel of otherChannels) {
@@ -86,8 +86,8 @@ export async function ensureChannelAuth(): Promise<void> {
         workspace_name: channel.name,
         account_id: account.id,
         account_name: account.name,
-        account_cookie: extracted.accountCookie,
-        session_cookie: extracted.sessionCookie,
+        account_cookie: extracted[0].accountCookie,
+        session_cookie: extracted[0].sessionCookie,
       })
     }