agent-messenger 2.21.0 → 2.22.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.22.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.22.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.22.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

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

@@ -274,6 +274,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
 
@@ -223,11 +224,19 @@ export class WebexClient {
     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)
   }
 
@@ -387,7 +396,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 +412,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 +507,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 +525,82 @@ 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()
+  }
+}
+
+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 {

package/src/platforms/webexbot/cli.ts

@@ -5,10 +5,13 @@ import { Command } from 'commander'
 import pkg from '../../../package.json' with { type: 'json' }
 import {
   authCommand,
+  fileCommand,
   listenCommand,
   memberCommand,
   messageCommand,
+  snapshotCommand,
   spaceCommand,
+  userCommand,
   whoamiCommand,
 } from './commands/index'
 
@@ -35,6 +38,9 @@ program.addCommand(whoamiCommand)
 program.addCommand(messageCommand)
 program.addCommand(spaceCommand)
 program.addCommand(memberCommand)
+program.addCommand(userCommand)
+program.addCommand(fileCommand)
+program.addCommand(snapshotCommand)
 program.addCommand(listenCommand)
 
 program.parseAsync(process.argv)

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

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+
+import { WebexBotClient } from './client'
+
+describe('WebexBotClient', () => {
+  const originalFetch = globalThis.fetch
+  let fetchCalls: Array<{ url: string; options?: RequestInit }> = []
+  let fetchResponses: Response[] = []
+  let fetchIndex = 0
+
+  beforeEach(() => {
+    fetchCalls = []
+    fetchResponses = []
+    fetchIndex = 0
+    ;(globalThis as { fetch: unknown }).fetch = async (
+      url: string | URL | Request,
+      options?: RequestInit,
+    ): Promise<Response> => {
+      fetchCalls.push({ url: url.toString(), options })
+      const response = fetchResponses[fetchIndex]
+      fetchIndex++
+      if (!response) {
+        throw new Error('No mock response configured')
+      }
+      return response
+    }
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  const mockResponse = (body: unknown, status = 200) => {
+    fetchResponses.push(
+      new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    )
+  }
+
+  describe('listMessages', () => {
+    it('limits group-space history to messages that mention the bot', async () => {
+      mockResponse({ id: 'group-room', title: 'Team', type: 'group' })
+      mockResponse({ items: [{ id: 'msg-1', roomId: 'group-room', roomType: 'group' }] })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const messages = await client.listMessages('group-room', { max: 5 })
+
+      expect(messages).toHaveLength(1)
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/rooms/group-room')
+
+      const messagesUrl = new URL(fetchCalls[1].url)
+      expect(messagesUrl.origin + messagesUrl.pathname).toBe('https://webexapis.com/v1/messages')
+      expect(messagesUrl.searchParams.get('roomId')).toBe('group-room')
+      expect(messagesUrl.searchParams.get('max')).toBe('5')
+      expect(messagesUrl.searchParams.get('mentionedPeople')).toBe('me')
+    })
+
+    it('does not add mentionedPeople for direct spaces', async () => {
+      mockResponse({ id: 'direct-room', title: 'DM', type: 'direct' })
+      mockResponse({ items: [{ id: 'msg-1', roomId: 'direct-room', roomType: 'direct' }] })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.listMessages('direct-room', { max: 5 })
+
+      const messagesUrl = new URL(fetchCalls[1].url)
+      expect(messagesUrl.searchParams.get('roomId')).toBe('direct-room')
+      expect(messagesUrl.searchParams.get('mentionedPeople')).toBeNull()
+    })
+  })
+
+  describe('sendMessage threading', () => {
+    it('includes parentId in the request body when threading', async () => {
+      mockResponse({ id: 'msg-1', roomId: 'room-1', roomType: 'group' })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage('room-1', 'reply text', { parentId: 'parent-1' })
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body.roomId).toBe('room-1')
+      expect(body.text).toBe('reply text')
+      expect(body.parentId).toBe('parent-1')
+    })
+  })
+
+  describe('listReplies', () => {
+    it('queries messages filtered by parentId', async () => {
+      mockResponse({ items: [{ id: 'reply-1', roomId: 'room-1', roomType: 'group', parentId: 'parent-1' }] })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const replies = await client.listReplies('room-1', 'parent-1', { max: 10 })
+
+      expect(replies).toHaveLength(1)
+      const url = new URL(fetchCalls[0].url)
+      expect(url.searchParams.get('roomId')).toBe('room-1')
+      expect(url.searchParams.get('parentId')).toBe('parent-1')
+      expect(url.searchParams.get('max')).toBe('10')
+    })
+  })
+
+  describe('getPerson', () => {
+    it('fetches a person by id', async () => {
+      mockResponse({ id: 'person-1', emails: ['a@b.com'], displayName: 'Alice', type: 'person' })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const person = await client.getPerson('person-1')
+
+      expect(person.displayName).toBe('Alice')
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/people/person-1')
+    })
+  })
+
+  describe('uploadFile', () => {
+    it('posts multipart form data to messages', async () => {
+      mockResponse({
+        id: 'msg-1',
+        roomId: 'room-1',
+        roomType: 'group',
+        files: ['https://webexapis.com/v1/contents/c1'],
+      })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const message = await client.uploadFile(
+        'room-1',
+        { content: new Blob(['hello']), filename: 'note.txt' },
+        { text: 'see attached' },
+      )
+
+      expect(message.files).toEqual(['https://webexapis.com/v1/contents/c1'])
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/messages')
+      expect(fetchCalls[0].options?.method).toBe('POST')
+      const body = fetchCalls[0].options?.body as FormData
+      expect(body).toBeInstanceOf(FormData)
+      expect(body.get('roomId')).toBe('room-1')
+      expect(body.get('text')).toBe('see attached')
+    })
+  })
+
+  describe('downloadContent', () => {
+    it('returns binary data with filename parsed from Content-Disposition', async () => {
+      fetchResponses.push(
+        new Response('binary-bytes', {
+          status: 200,
+          headers: {
+            'Content-Disposition': 'attachment; filename="report.pdf"',
+            'Content-Type': 'application/pdf',
+          },
+        }),
+      )
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const result = await client.downloadContent('https://webexapis.com/v1/contents/c1')
+
+      expect(result.filename).toBe('report.pdf')
+      expect(result.contentType).toBe('application/pdf')
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/contents/c1')
+    })
+
+    it('builds the contents URL from a bare content id', async () => {
+      fetchResponses.push(new Response('data', { status: 200, headers: {} }))
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const result = await client.downloadContent('abc123')
+
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/contents/abc123')
+      expect(result.filename).toBe('abc123')
+    })
+
+    it('refuses to download from a non-Webex host', async () => {
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+
+      await expect(client.downloadContent('https://attacker.example/file')).rejects.toThrow(/untrusted/i)
+      expect(fetchCalls).toHaveLength(0)
+    })
+
+    it('refuses to download over plain http from the Webex host', async () => {
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+
+      await expect(client.downloadContent('http://webexapis.com/v1/contents/c1')).rejects.toThrow(/untrusted/i)
+      expect(fetchCalls).toHaveLength(0)
+    })
+
+    it('sanitizes a path-traversal filename from Content-Disposition', async () => {
+      fetchResponses.push(
+        new Response('data', {
+          status: 200,
+          headers: { 'Content-Disposition': 'attachment; filename="../../etc/passwd"' },
+        }),
+      )
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      const result = await client.downloadContent('https://webexapis.com/v1/contents/c1')
+
+      expect(result.filename).toBe('passwd')
+    })
+  })
+})

package/src/platforms/webexbot/client.ts

@@ -44,7 +44,11 @@ export class WebexBotClient {
     return this.client.getSpace(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> {
     return this.client.sendMessage(roomId, text, options)
   }
 
@@ -52,8 +56,14 @@ export class WebexBotClient {
     return this.client.sendDirectMessage(personEmail, text, options)
   }
 
-  async listMessages(roomId: string, options?: { max?: number }): Promise<WebexMessage[]> {
-    return this.client.listMessages(roomId, options)
+  async listMessages(roomId: string, options?: { max?: number; parentId?: string }): Promise<WebexMessage[]> {
+    const space = await this.client.getSpace(roomId)
+    const messageOptions = space.type === 'group' ? { ...options, mentionedPeople: 'me' } : options
+    return this.client.listMessages(roomId, messageOptions)
+  }
+
+  async listReplies(roomId: string, parentId: string, options?: { max?: number }): Promise<WebexMessage[]> {
+    return this.client.listMessages(roomId, { ...options, parentId })
   }
 
   async getMessage(messageId: string): Promise<WebexMessage> {
@@ -77,6 +87,10 @@ export class WebexBotClient {
     return this.client.listPeople(options)
   }
 
+  async getPerson(personId: string): Promise<WebexPerson> {
+    return this.client.getPerson(personId)
+  }
+
   async listMyMemberships(options?: { max?: number }): Promise<WebexMembership[]> {
     return this.client.listMyMemberships(options)
   }
@@ -84,4 +98,16 @@ export class WebexBotClient {
   async listMemberships(roomId: string, options?: { max?: number }): Promise<WebexMembership[]> {
     return this.client.listMemberships(roomId, options)
   }
+
+  async uploadFile(
+    roomId: string,
+    file: { content: Blob; filename: string },
+    options?: { text?: string; markdown?: boolean; parentId?: string },
+  ): Promise<WebexMessage> {
+    return this.client.uploadFile(roomId, file, options)
+  }
+
+  async downloadContent(contentRef: string): Promise<{ data: ArrayBuffer; filename: string; contentType: string }> {
+    return this.client.downloadContent(contentRef)
+  }
 }