agent-messenger 2.21.0 → 2.23.0

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

@@ -220,6 +220,124 @@ MESSAGE_ID="Y2lzY29zcGFyazovL..."
 agent-webexbot message delete "$MESSAGE_ID"
 ```
 
+## Thread Patterns
+
+### Pattern 12a: Reply in a Thread
+
+**Use case**: Keep a conversation organized under a parent message
+
+```bash
+#!/bin/bash
+
+SPACE_ID="Y2lzY29zcGFyazovL..."
+
+# Send a parent message and capture its ID
+PARENT=$(agent-webexbot message send "$SPACE_ID" "Deploy started" | jq -r '.id')
+
+# Reply within the thread
+agent-webexbot message reply "$SPACE_ID" "$PARENT" "Step 1 complete"
+
+# Equivalent using send --parent
+agent-webexbot message send "$SPACE_ID" "Step 2 complete" --parent "$PARENT"
+```
+
+### Pattern 12b: Read Thread Replies
+
+**Use case**: Fetch all replies under a parent message
+
+```bash
+#!/bin/bash
+
+SPACE_ID="Y2lzY29zcGFyazovL..."
+PARENT_ID="Y2lzY29zcGFyazovL..."
+
+agent-webexbot message replies "$SPACE_ID" "$PARENT_ID" --max 20 \
+  | jq -r '.messages[] | "[\(.created)] \(.personEmail): \(.text)"'
+```
+
+## File Patterns
+
+### Pattern 12c: Upload a File
+
+**Use case**: Attach a local file (report, log, image) to a space
+
+```bash
+#!/bin/bash
+
+SPACE_ID="Y2lzY29zcGFyazovL..."
+
+# Upload with an accompanying message
+agent-webexbot file upload "$SPACE_ID" ./coverage.html --text "Latest coverage report"
+
+# Upload as a threaded reply
+agent-webexbot file upload "$SPACE_ID" ./build.log --parent "$PARENT_ID"
+```
+
+**Note**: Max file size is 100 MB, one file per message.
+
+### Pattern 12d: Download an Attachment
+
+**Use case**: Save a file someone shared in a space
+
+```bash
+#!/bin/bash
+
+SPACE_ID="Y2lzY29zcGFyazovL..."
+
+# Get the content URL from a message's "files" array
+CONTENT_URL=$(agent-webexbot message list "$SPACE_ID" --max 20 \
+  | jq -r 'first(.messages[].files[]? // empty)')
+
+# Download (defaults to the original filename in the current directory)
+agent-webexbot file download "$CONTENT_URL"
+
+# Or choose an output path explicitly
+agent-webexbot file download "$CONTENT_URL" ./downloaded-report.html
+```
+
+**Security note**: Downloads are restricted to `https://webexapis.com/v1/contents/*` URLs — the bot token is never sent to other hosts. Server-provided filenames are reduced to their base name, so the default output always stays in the current directory.
+
+## People Patterns
+
+### Pattern 12e: Look Up a Person by Email
+
+**Use case**: Resolve a person ID or display name from an email address
+
+```bash
+#!/bin/bash
+
+agent-webexbot user list --email alice@example.com \
+  | jq -r '.users[] | "\(.displayName) — \(.id)"'
+```
+
+### Pattern 12f: Get Person Details
+
+**Use case**: Fetch full profile details for a known person ID
+
+```bash
+#!/bin/bash
+
+PERSON_ID="Y2lzY29zcGFyazovL..."
+
+agent-webexbot user info "$PERSON_ID" | jq '{displayName, emails, type}'
+```
+
+## Snapshot Patterns
+
+### Pattern 12g: Workspace Overview
+
+**Use case**: Give an AI agent a quick picture of the bot's workspace
+
+```bash
+#!/bin/bash
+
+# Brief: bot identity + space IDs/titles
+agent-webexbot snapshot
+
+# Full: includes space type and last activity
+agent-webexbot snapshot --full --max 50
+```
+
 ## Member Patterns
 
 ### Pattern 13: List Space Members

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

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.21.0
+version: 2.23.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.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/platforms/webex/cli.test.ts

@@ -20,6 +20,21 @@ describe('Webex CLI program structure', () => {
     expect(output).toContain('space')
   })
 
+  it('auth --help lists login and oauth subcommands', async () => {
+    const proc = spawn(['bun', 'run', './src/platforms/webex/cli.ts', 'auth', '--help'], {
+      cwd: process.cwd(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    const output = await new Response(proc.stdout).text()
+
+    expect(output).toContain('login')
+    expect(output).toContain('oauth')
+    expect(output).toContain('extract')
+    expect(output).toContain('status')
+    expect(output).toContain('logout')
+  })
+
   it('--version shows package version', async () => {
     const proc = spawn(['bun', 'run', './src/platforms/webex/cli.ts', '--version'], {
       cwd: process.cwd(),
@@ -30,7 +45,7 @@ describe('Webex CLI program structure', () => {
     expect(output.trim()).toBe(pkg.version)
   })
 
-  it('auth login --help shows Device Grant options', async () => {
+  it('auth login --help shows email/password options', async () => {
     const proc = spawn(['bun', 'run', './src/platforms/webex/cli.ts', 'auth', 'login', '--help'], {
       cwd: process.cwd(),
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -38,7 +53,22 @@ describe('Webex CLI program structure', () => {
 
     const output = await new Response(proc.stdout).text()
 
+    expect(output).toContain('--email')
+    expect(output).toContain('--password')
+    expect(output).toContain('--password-stdin')
     expect(output).toContain('--token')
+    expect(output).toContain('--pretty')
+  })
+
+  it('auth oauth --help shows Device Grant options', async () => {
+    const proc = spawn(['bun', 'run', './src/platforms/webex/cli.ts', 'auth', 'oauth', '--help'], {
+      cwd: process.cwd(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    const output = await new Response(proc.stdout).text()
+
+    expect(output).toContain('--device-code')
     expect(output).toContain('--client-id')
     expect(output).toContain('--client-secret')
     expect(output).toContain('--pretty')

package/src/platforms/webex/client.test.ts

@@ -60,6 +60,16 @@ describe('WebexClient', () => {
       await expect(new WebexClient().login({ token: '' })).rejects.toThrow('Token is required')
     })
 
+    it('returns the authenticated token', async () => {
+      const client = await new WebexClient().login({ token: 'test-token' })
+
+      expect(client.getToken()).toBe('test-token')
+    })
+
+    it('throws when reading token before login', () => {
+      expect(() => new WebexClient().getToken()).toThrow('Not authenticated. Call .login() first.')
+    })
+
     it('accepts deviceUrl and tokenType', async () => {
       const client = await new WebexClient().login({
         token: 'test-token',
@@ -191,6 +201,53 @@ describe('WebexClient', () => {
     })
   })
 
+  describe('iterateSpaces', () => {
+    it('follows the Link header across pages and yields every room', async () => {
+      // given two pages chained by a rel="next" Link header
+      mockResponse({ items: [{ id: 'room1', title: 'One', type: 'group' }] }, 200, {
+        Link: '<https://webexapis.com/v1/rooms?max=1000&before=cursor1>; rel="next"',
+      })
+      mockResponse({ items: [{ id: 'room2', title: 'Two', type: 'group' }] })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      const ids: string[] = []
+      for await (const room of client.iterateSpaces({ max: 1000 })) {
+        ids.push(room.id)
+      }
+
+      expect(ids).toEqual(['room1', 'room2'])
+      expect(fetchCalls[0].url).toContain('/rooms?max=1000')
+      expect(fetchCalls[1].url).toContain('before=cursor1')
+    })
+
+    it('stops after a single page when no next Link is present', async () => {
+      mockResponse({ items: [{ id: 'room1', title: 'One', type: 'group' }] })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      const ids: string[] = []
+      for await (const room of client.iterateSpaces()) {
+        ids.push(room.id)
+      }
+
+      expect(ids).toEqual(['room1'])
+      expect(fetchCalls).toHaveLength(1)
+    })
+
+    it('stops consuming the generator early without fetching the next page', async () => {
+      mockResponse({ items: [{ id: 'room1', title: 'One', type: 'group' }] }, 200, {
+        Link: '<https://webexapis.com/v1/rooms?max=1000&before=cursor1>; rel="next"',
+      })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      for await (const room of client.iterateSpaces({ max: 1000 })) {
+        expect(room.id).toBe('room1')
+        break
+      }
+
+      expect(fetchCalls).toHaveLength(1)
+    })
+  })
+
   describe('getSpace', () => {
     it('calls GET /rooms/{spaceId}', async () => {
       mockResponse({ id: 'room1', title: 'Test Room', type: 'group' })
@@ -274,6 +331,16 @@ describe('WebexClient', () => {
 
       expect(fetchCalls[0].url).toContain('max=10')
     })
+
+    it('passes mentionedPeople when requested', async () => {
+      mockResponse({ items: [] })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      await client.listMessages('room1', { max: 10, mentionedPeople: 'me' })
+
+      const url = new URL(fetchCalls[0].url)
+      expect(url.searchParams.get('mentionedPeople')).toBe('me')
+    })
   })
 
   describe('getMessage', () => {

package/src/platforms/webex/client.ts

@@ -6,6 +6,7 @@ import type { WebexConfig, WebexMembership, WebexMessage, WebexPerson, WebexSpac
 import { WebexError } from './types'
 
 const BASE_URL = 'https://webexapis.com/v1'
+const CONTENT_HOST = 'webexapis.com'
 const MAX_RETRIES = 3
 const BASE_BACKOFF_MS = 100
 
@@ -45,7 +46,7 @@ export class WebexClient {
     this.tokenType = config?.tokenType ?? null
     await this.login({ token })
 
-    if (this.tokenType === 'extracted') {
+    if (this.tokenType === 'extracted' || this.tokenType === 'password') {
       const keysMap = new Map(Object.entries(config?.encryptionKeys ?? {}))
       this.encryption = new WebexEncryptionService(keysMap)
       const kmsProvider = new KmsKeyProvider({ token })
@@ -68,6 +69,10 @@ export class WebexClient {
     await this.encryption?.close()
   }
 
+  getToken(): string {
+    return this.ensureAuth()
+  }
+
   private async persistEncryptionKey(
     credManager: WebexCredentialManager,
     keyUri: string,
@@ -130,6 +135,14 @@ export class WebexClient {
   }
 
   private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    return (await this.requestWithLink<T>(method, path, body)).data
+  }
+
+  private async requestWithLink<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<{ data: T; nextPath: string | null }> {
     const url = `${BASE_URL}${path}`
     const bucketKey = this.getBucketKey(method, path)
 
@@ -178,10 +191,11 @@ export class WebexClient {
       }
 
       if (response.status === 204) {
-        return undefined as T
+        return { data: undefined as T, nextPath: null }
       }
 
-      return response.json() as Promise<T>
+      const data = (await response.json()) as T
+      return { data, nextPath: parseNextPath(response.headers.get('Link')) }
     }
 
     throw new WebexError('Request failed after retries', 'max_retries')
@@ -219,20 +233,40 @@ export class WebexClient {
     return data.items
   }
 
+  async *iterateSpaces(options?: { type?: string; max?: number }): AsyncGenerator<WebexSpace> {
+    const params = new URLSearchParams()
+    if (options?.type) params.set('type', options.type)
+    params.set('max', String(options?.max ?? 100))
+    let path: string | null = `/rooms?${params.toString()}`
+    while (path) {
+      const page: { data: { items: WebexSpace[] }; nextPath: string | null } = await this.requestWithLink('GET', path)
+      yield* page.data.items
+      path = page.nextPath
+    }
+  }
+
   async getSpace(spaceId: string): Promise<WebexSpace> {
     return this.request<WebexSpace>('GET', `/rooms/${spaceId}`)
   }
 
-  async sendMessage(roomId: string, text: string, options?: { markdown?: boolean }): Promise<WebexMessage> {
+  async sendMessage(
+    roomId: string,
+    text: string,
+    options?: { markdown?: boolean; parentId?: string; files?: string[] },
+  ): Promise<WebexMessage> {
     if (this.useInternalAPI) {
       return this.sendMessageInternal(roomId, text, options)
     }
-    const body = options?.markdown ? { roomId, markdown: text } : { roomId, text }
+    const body: Record<string, unknown> = { roomId }
+    if (options?.markdown) body.markdown = text
+    else body.text = text
+    if (options?.parentId) body.parentId = options.parentId
+    if (options?.files?.length) body.files = options.files
     return this.request<WebexMessage>('POST', '/messages', body)
   }
 
   private get useInternalAPI(): boolean {
-    return this.tokenType === 'extracted' && this.deviceUrl !== null
+    return (this.tokenType === 'extracted' || this.tokenType === 'password') && this.deviceUrl !== null
   }
 
   private get convBaseUrl(): string {
@@ -387,7 +421,10 @@ export class WebexClient {
     return null
   }
 
-  async listMessages(roomId: string, options?: { max?: number }): Promise<WebexMessage[]> {
+  async listMessages(
+    roomId: string,
+    options?: { max?: number; mentionedPeople?: string; parentId?: string },
+  ): Promise<WebexMessage[]> {
     if (this.useInternalAPI) {
       const convUuid = this.decodeConvUuid(roomId)
       const max = options?.max ?? 50
@@ -400,6 +437,8 @@ export class WebexClient {
     const params = new URLSearchParams()
     params.set('roomId', roomId)
     params.set('max', String(options?.max ?? 50))
+    if (options?.mentionedPeople) params.set('mentionedPeople', options.mentionedPeople)
+    if (options?.parentId) params.set('parentId', options.parentId)
     const data = await this.request<{ items: WebexMessage[] }>('GET', `/messages?${params}`)
     return data.items
   }
@@ -493,6 +532,10 @@ export class WebexClient {
     return data.items
   }
 
+  async getPerson(personId: string): Promise<WebexPerson> {
+    return this.request<WebexPerson>('GET', `/people/${personId}`)
+  }
+
   async listMyMemberships(options?: { max?: number }): Promise<WebexMembership[]> {
     const params = new URLSearchParams()
     params.set('max', String(options?.max ?? 100))
@@ -507,6 +550,92 @@ export class WebexClient {
     const data = await this.request<{ items: WebexMembership[] }>('GET', `/memberships?${params}`)
     return data.items
   }
+
+  async uploadFile(
+    roomId: string,
+    file: { content: Blob; filename: string },
+    options?: { text?: string; markdown?: boolean; parentId?: string },
+  ): Promise<WebexMessage> {
+    const form = new FormData()
+    form.set('roomId', roomId)
+    if (options?.text) {
+      form.set(options.markdown ? 'markdown' : 'text', options.text)
+    }
+    if (options?.parentId) form.set('parentId', options.parentId)
+    form.set('files', file.content, file.filename)
+
+    const response = await fetch(`${BASE_URL}/messages`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.ensureAuth()}` },
+      body: form,
+    })
+
+    if (!response.ok) {
+      const errorBody = (await response.json().catch(() => null)) as { message?: string } | null
+      throw new WebexError(errorBody?.message ?? `HTTP ${response.status}`, `http_${response.status}`)
+    }
+    return response.json() as Promise<WebexMessage>
+  }
+
+  async downloadContent(contentRef: string): Promise<{ data: ArrayBuffer; filename: string; contentType: string }> {
+    const url = this.resolveContentUrl(contentRef)
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.ensureAuth()}` },
+    })
+
+    if (!response.ok) {
+      const errorBody = (await response.json().catch(() => null)) as { message?: string } | null
+      throw new WebexError(errorBody?.message ?? `HTTP ${response.status}`, `http_${response.status}`)
+    }
+
+    const disposition = response.headers.get('Content-Disposition') ?? ''
+    const match = disposition.match(/filename="?([^"]+)"?/)
+    const filename = sanitizeFilename(match?.[1]) ?? sanitizeFilename(contentRef.split('/').pop()) ?? 'download'
+    const contentType = response.headers.get('Content-Type') ?? 'application/octet-stream'
+    const data = await response.arrayBuffer()
+    return { data, filename, contentType }
+  }
+
+  private resolveContentUrl(contentRef: string): string {
+    // A bare content id never contains a scheme or path separators.
+    if (!contentRef.includes('://') && !contentRef.includes('/')) {
+      return `${BASE_URL}/contents/${encodeURIComponent(contentRef)}`
+    }
+
+    // Only attach the bearer token to HTTPS Webex content URLs to avoid
+    // leaking credentials to attacker-controlled hosts (SSRF/token exfiltration).
+    let parsed: URL
+    try {
+      parsed = new URL(contentRef)
+    } catch {
+      throw new WebexError(`Invalid content reference: ${contentRef}`, 'invalid_content_ref')
+    }
+    if (parsed.protocol !== 'https:' || parsed.host !== CONTENT_HOST || !parsed.pathname.startsWith('/v1/contents/')) {
+      throw new WebexError(
+        `Refusing to download from untrusted location: ${parsed.origin}${parsed.pathname}`,
+        'untrusted_content_url',
+      )
+    }
+    return parsed.toString()
+  }
+}
+
+// Webex paginates List endpoints via an RFC 5988 `Link` header
+// (`<https://webexapis.com/v1/rooms?...&before=cursor>; rel="next"`). Return the
+// next page as a BASE_URL-relative path, or null when there is no next page.
+function parseNextPath(linkHeader: string | null): string | null {
+  if (!linkHeader) return null
+  const next = linkHeader.match(/<([^>]+)>\s*;\s*rel="next"/i)
+  if (!next) return null
+  return next[1].startsWith(BASE_URL) ? next[1].slice(BASE_URL.length) : null
+}
+
+function sanitizeFilename(name: string | undefined): string | undefined {
+  if (!name) return undefined
+  // Strip any path components so a server-supplied name cannot escape the target directory.
+  const base = name.replace(/\\/g, '/').split('/').pop()
+  if (!base || base === '.' || base === '..') return undefined
+  return base
 }
 
 interface InternalActivity {