agent-messenger 2.20.5 → 2.22.0

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

package/src/cli.ts

@@ -76,6 +76,10 @@ program.command('webex', 'Interact with Cisco Webex', {
   executableFile: join(__dirname, 'platforms', 'webex', `cli${ext}`),
 })
 
+program.command('webexbot', 'Interact with Cisco Webex using bot tokens', {
+  executableFile: join(__dirname, 'platforms', 'webexbot', `cli${ext}`),
+})
+
 program.command('tui', 'Launch unified messenger TUI', {
   executableFile: join(__dirname, 'tui', `cli${ext}`),
 })

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/webex/typings/webex-message-handler.d.ts

@@ -1,45 +1,376 @@
 export {}
 
 declare module 'webex-message-handler' {
-  import type * as jose from 'node-jose'
+  import { EventEmitter } from 'events'
 
-  type Logger = Record<string, (...args: unknown[]) => void>
-  type HttpRequest = { url: string; method: string; headers: Record<string, string>; body?: string }
-  type HttpResponse = { status: number; ok: boolean; json(): Promise<unknown>; text(): Promise<string> }
-  type HttpDo = (req: HttpRequest) => Promise<HttpResponse>
+  import type { JWK } from 'node-jose'
+
+  export interface Logger {
+    debug(message: string, ...args: unknown[]): void
+    info(message: string, ...args: unknown[]): void
+    warn(message: string, ...args: unknown[]): void
+    error(message: string, ...args: unknown[]): void
+  }
 
   export const noopLogger: Logger
   export const consoleLogger: Logger
 
+  export type NetworkMode = 'native' | 'injected'
+
+  export interface FetchRequest {
+    url: string
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE'
+    headers: Record<string, string>
+    body?: string
+  }
+
+  export interface FetchResponse {
+    status: number
+    ok: boolean
+    json(): Promise<unknown>
+    text(): Promise<string>
+  }
+
+  export type FetchFunction = (request: FetchRequest) => Promise<FetchResponse>
+
+  export interface InjectedWebSocket {
+    send(data: string): void
+    close(code?: number): void
+    readonly readyState: number
+    on(event: 'message', listener: (data: string) => void): void
+    on(event: 'open', listener: () => void): void
+    on(event: 'close', listener: (code: number, reason: string) => void): void
+    on(event: 'error', listener: (error: Error) => void): void
+  }
+
+  export type WebSocketFactory = (url: string) => InjectedWebSocket
+
+  export interface WebexMessageHandlerConfig {
+    token: string
+    logger?: Logger
+    /** Networking mode: 'native' uses built-in fetch/WebSocket, 'injected' uses provided functions */
+    mode?: NetworkMode
+    /**
+     * Optional undici Dispatcher for native mode proxy support (HTTP + WebSocket).
+     * A single `ProxyAgent` proxies both `fetch()` and the native `WebSocket`.
+     * Example: `new ProxyAgent('http://proxy:8080')`
+     */
+    dispatcher?: object
+    /** Custom fetch function for all HTTP requests (injected mode) */
+    fetch?: FetchFunction
+    /** Custom WebSocket factory (injected mode) */
+    webSocketFactory?: WebSocketFactory
+    /** Automatically filter out messages sent by this bot to prevent loops (default: true) */
+    ignoreSelfMessages?: boolean
+    /** Ping interval in ms (default: 15000) */
+    pingInterval?: number
+    /** Pong timeout in ms (default: 14000) */
+    pongTimeout?: number
+    /** Max reconnect backoff in ms (default: 32000) */
+    reconnectBackoffMax?: number
+    /** Max reconnect attempts before giving up (default: 10) */
+    maxReconnectAttempts?: number
+    /** Optional metrics callback for timing events (no overhead if not set) */
+    metricsCallback?: MetricsCallback
+  }
+
+  export interface PersonInfo {
+    /** Person's unique ID */
+    id: string
+    /** Person's email address */
+    emails: string[]
+    /** Person's display name */
+    displayName: string
+    /** Person type (person or bot) */
+    type: 'person' | 'bot'
+  }
+
+  export interface DeviceRegistration {
+    /** The Mercury WebSocket URL */
+    webSocketUrl: string
+    /** The device URL (used as clientId for KMS) */
+    deviceUrl: string
+    /** The bot's user ID */
+    userId: string
+    /** Service catalog from WDM */
+    services: Record<string, string>
+    /** Encryption service URL extracted from services */
+    encryptionServiceUrl: string
+  }
+
+  export interface MercuryActor {
+    id: string
+    objectType: string
+    emailAddress?: string
+  }
+
+  export interface MercuryObject {
+    id: string
+    objectType: string
+    displayName?: string
+    content?: string
+    encryptionKeyUrl?: string
+    /** Card form input values (present on cardAction/submit activities). */
+    inputs?: Record<string, unknown>
+    /** File URLs attached to the message (present on file-share messages). */
+    files?: string[]
+  }
+
+  export interface MercuryTarget {
+    id: string
+    objectType: string
+    encryptionKeyUrl?: string
+    tags?: string[]
+  }
+
+  export interface MercuryParent {
+    id: string
+    type: string
+  }
+
+  export interface MercuryActivity {
+    id: string
+    /** Full Conversation-service activity URL, when present on the raw activity. */
+    url?: string
+    verb: string
+    actor: MercuryActor
+    object: MercuryObject
+    target: MercuryTarget
+    published: string
+    encryptionKeyUrl?: string
+    parent?: MercuryParent
+  }
+
+  export interface MercuryEnvelope {
+    id: string
+    data: {
+      eventType: string
+      activity: MercuryActivity
+    }
+    timestamp: number
+    trackingId: string
+    sequenceNumber?: number
+  }
+
+  export interface DecryptedMessage {
+    /** Mercury activity UUID. Works as parentId for threaded replies. */
+    id: string
+    /**
+     * Full Conversation-service activity URL, when present on the raw Mercury
+     * activity (e.g. for an outbound "acknowledge" read-receipt). Undefined if
+     * Mercury did not include it.
+     */
+    url?: string
+    /** Parent activity UUID for threaded replies. Undefined if not a thread reply. */
+    parentId?: string
+    roomId: string
+    personId: string
+    personEmail: string
+    text: string
+    html?: string
+    created: string
+    roomType?: string
+    /** Person UUIDs mentioned via @mention in the message. */
+    mentionedPeople: string[]
+    /** Group mention types (e.g. "all") in the message. */
+    mentionedGroups: string[]
+    /** File URLs attached to the message. Empty if no files. */
+    files: string[]
+    raw: MercuryActivity
+  }
+
+  export interface DeletedMessage {
+    messageId: string
+    roomId: string
+    personId: string
+  }
+
+  export interface MembershipActivity {
+    /** Activity ID. */
+    id: string
+    /** ID of the person who performed the action. */
+    actorId: string
+    /** ID of the member affected. */
+    personId: string
+    /** Conversation/space ID. */
+    roomId: string
+    /** Membership action: "add", "leave", "assignModerator", or "unassignModerator". */
+    action: string
+    /** ISO 8601 timestamp. */
+    created: string
+    /** "direct", "group", or undefined. */
+    roomType?: string
+    /** Full raw activity for advanced use. */
+    raw: MercuryActivity
+  }
+
+  export interface AttachmentAction {
+    /** Activity ID. */
+    id: string
+    /** ID of the message the card was attached to. */
+    messageId: string
+    /** ID of the person who submitted the card. */
+    personId: string
+    /** Email of the person who submitted the card. */
+    personEmail: string
+    /** Conversation/space ID. */
+    roomId: string
+    /** Card form input values. */
+    inputs: Record<string, unknown>
+    /** ISO 8601 timestamp. */
+    created: string
+    /** Full raw activity for advanced use. */
+    raw: MercuryActivity
+  }
+
+  export interface RoomActivity {
+    /** Activity ID. */
+    id: string
+    /** Conversation/space ID. */
+    roomId: string
+    /** ID of the person who performed the action. */
+    actorId: string
+    /** Room action: "created" or "updated". */
+    action: string
+    /** ISO 8601 timestamp. */
+    created: string
+    /** Full raw activity for advanced use. */
+    raw: MercuryActivity
+  }
+
+  export type ConnectionStatus = 'connected' | 'connecting' | 'reconnecting' | 'disconnected'
+
+  export interface HandlerStatus {
+    /** Overall connection state. */
+    status: ConnectionStatus
+    /** Whether the WebSocket is currently open. */
+    webSocketOpen: boolean
+    /** Whether the KMS encryption context is initialized. */
+    kmsInitialized: boolean
+    /** Whether the device is registered with WDM. */
+    deviceRegistered: boolean
+    /** Current auto-reconnect attempt number (0 if not reconnecting). */
+    reconnectAttempt: number
+  }
+
+  export interface MetricsEvent {
+    /** Metric name: "connect", "kms_fetch", or "decrypt". */
+    name: string
+    /** Duration in milliseconds. */
+    durationMs: number
+    /** Whether the operation succeeded. */
+    success: boolean
+    /** Optional context metadata (e.g., key URI for kms_fetch). */
+    metadata?: Record<string, string>
+  }
+
+  export type MetricsCallback = (event: MetricsEvent) => void
+
+  export interface WebexMessageHandlerEvents {
+    'message:created': (msg: DecryptedMessage) => void
+    'message:updated': (msg: DecryptedMessage) => void
+    'message:deleted': (data: DeletedMessage) => void
+    'membership:created': (activity: MembershipActivity) => void
+    'attachmentAction:created': (action: AttachmentAction) => void
+    'room:created': (activity: RoomActivity) => void
+    'room:updated': (activity: RoomActivity) => void
+    connected: () => void
+    disconnected: (reason: string) => void
+    reconnecting: (attempt: number) => void
+    error: (err: Error) => void
+  }
+
+  interface TypedEventEmitter<T> {
+    on<K extends keyof T>(event: K, listener: T[K]): this
+    emit<K extends keyof T>(
+      event: K,
+      ...args: Parameters<T[K] extends (...a: infer P) => unknown ? (...a: P) => unknown : never>
+    ): boolean
+    off<K extends keyof T>(event: K, listener: T[K]): this
+    once<K extends keyof T>(event: K, listener: T[K]): this
+    removeAllListeners<K extends keyof T>(event?: K): this
+  }
+
+  export class WebexMessageHandler extends EventEmitter implements TypedEventEmitter<WebexMessageHandlerEvents> {
+    constructor(config: WebexMessageHandlerConfig)
+    connect(): Promise<void>
+    disconnect(): Promise<void>
+    reconnect(newToken: string): Promise<void>
+    get connected(): boolean
+    status(): HandlerStatus
+    deviceRegistration(): DeviceRegistration | null
+    serviceUrl(name: string): string | undefined
+    on<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+    emit<K extends keyof WebexMessageHandlerEvents>(
+      event: K,
+      ...args: Parameters<
+        WebexMessageHandlerEvents[K] extends (...a: infer P) => unknown ? (...a: P) => unknown : never
+      >
+    ): boolean
+    off<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+    once<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this
+    removeAllListeners<K extends keyof WebexMessageHandlerEvents>(event?: K): this
+  }
+
+  type HttpDoFn = (request: FetchRequest) => Promise<FetchResponse>
+
+  export interface DeviceManagerOptions {
+    logger?: Logger
+    httpDo: HttpDoFn
+  }
+
   export class DeviceManager {
-    constructor(options: { logger: Logger; httpDo: HttpDo })
-    register(token: string): Promise<{
-      webSocketUrl: string
-      deviceUrl: string
-      userId: string
-      services: unknown
-      encryptionServiceUrl: string
-    }>
-  }
-
-  export class MercurySocket {
-    constructor(options: { logger: Logger; wsFactory: (url: string) => unknown })
-    on(event: 'kms:response', handler: (data: unknown) => void): void
-    connect(webSocketUrl: string, token: string): Promise<void>
+    constructor(options: DeviceManagerOptions)
+    register(token: string): Promise<DeviceRegistration>
+    refresh(token: string): Promise<DeviceRegistration>
+    unregister(token: string): Promise<void>
+  }
+
+  export interface MercurySocketOptions {
+    logger?: Logger
+    wsFactory: WebSocketFactory
+    pingInterval?: number
+    pongTimeout?: number
+    reconnectBackoffMax?: number
+    maxReconnectAttempts?: number
+  }
+
+  export class MercurySocket extends EventEmitter {
+    constructor(options: MercurySocketOptions)
+    connect(url: string, token: string): Promise<void>
     disconnect(): Promise<void>
+    get connected(): boolean
+    get currentReconnectAttempts(): number
+    on(event: 'kms:response', handler: (data: unknown) => void): this
+  }
+
+  export interface KmsClientConfig {
+    token: string
+    deviceUrl: string
+    userId: string
+    encryptionServiceUrl: string
+    logger?: Logger
+    httpDo: HttpDoFn
   }
 
   export class KmsClient {
-    constructor(options: {
-      token: string
-      deviceUrl: string
-      userId: string
-      encryptionServiceUrl: string
-      logger: Logger
-      httpDo: HttpDo
-    })
-    initialize(): Promise<void>
-    getKey(keyUri: string): Promise<jose.JWK.Key | null>
+    constructor(config: KmsClientConfig)
     handleKmsMessage(data: unknown): void
+    initialize(): Promise<void>
+    getKey(keyUri: string): Promise<JWK.Key>
+  }
+
+  export class MessageDecryptor {
+    constructor({ kmsClient, logger }: { kmsClient: KmsClient; logger?: Logger })
+    decryptActivity(activity: MercuryActivity): Promise<MercuryActivity>
+  }
+
+  export interface ParsedMentions {
+    mentionedPeople: string[]
+    mentionedGroups: string[]
   }
+
+  export function parseMentions(html: string | undefined | null): ParsedMentions
+  export function toRestId(uuid: string, type: 'MESSAGE' | 'PEOPLE' | 'ROOM'): string
+  export function fromRestId(restId: string): string
 }

package/src/platforms/webexbot/cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env bun
+
+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'
+
+const program = new Command()
+
+program
+  .name('agent-webexbot')
+  .description('CLI tool for Webex bot integration using bot tokens')
+  .version(pkg.version)
+  .option('--pretty', 'Pretty-print JSON output')
+  .option('--bot <id>', 'Bot ID to use')
+  .hook('preAction', (thisCmd, actionCmd) => {
+    for (const [key, value] of Object.entries(thisCmd.opts())) {
+      if (value === undefined) continue
+      const source = actionCmd.getOptionValueSource(key)
+      if (source === undefined || source === 'default') {
+        actionCmd.setOptionValue(key, value)
+      }
+    }
+  })
+
+program.addCommand(authCommand)
+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)
+
+export default program