agent-messenger 2.23.1 → 2.23.3

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

@@ -1,9 +1,10 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
 
 import * as jose from 'node-jose'
 
 import { WebexClient } from './client'
 import { WebexEncryptionService } from './encryption'
+import { toRestId } from './id-normalizer'
 import { WebexError } from './types'
 
 describe('WebexClient', () => {
@@ -444,6 +445,92 @@ describe('WebexClient', () => {
     })
   })
 
+  describe('id ref resolution', () => {
+    const roomUuid = '12345678-1234-1234-1234-1234567890ab'
+    const personUuid = '22222222-2222-2222-2222-222222222222'
+    const messageUuid = '33333333-3333-3333-3333-333333333333'
+    const usRoomId = toRestId(roomUuid, 'ROOM')
+    const clusteredRoomId = Buffer.from(`ciscospark://urn:TEAM:us-west-2_r/ROOM/${roomUuid}`).toString('base64url')
+
+    const isRoomsList = (url: string) => new URL(url).pathname === '/v1/rooms'
+
+    it('resolves a bare room uuid to the real clustered id before sending', async () => {
+      mockResponse({ items: [{ id: clusteredRoomId, title: 'Team', type: 'group' }] })
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      await client.sendMessage(roomUuid, 'hello')
+
+      expect(isRoomsList(fetchCalls[0].url)).toBe(true)
+      expect(JSON.parse(fetchCalls[1].options?.body as string).roomId).toBe(clusteredRoomId)
+    })
+
+    it('rewrites a us-cluster room id to the real clustered id for memberships', async () => {
+      mockResponse({ items: [{ id: clusteredRoomId, title: 'Team', type: 'group' }] })
+      mockResponse({ items: [{ id: 'm1', roomId: clusteredRoomId, personId: 'p1' }] })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      await client.listMemberships(usRoomId)
+
+      const membershipsUrl = new URL(fetchCalls[1].url)
+      expect(membershipsUrl.pathname).toBe('/v1/memberships')
+      expect(membershipsUrl.searchParams.get('roomId')).toBe(clusteredRoomId)
+    })
+
+    it('passes an already-clustered room id through without a lookup', async () => {
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      await client.sendMessage(clusteredRoomId, 'hello')
+
+      expect(fetchCalls).toHaveLength(1)
+      expect(JSON.parse(fetchCalls[0].options?.body as string).roomId).toBe(clusteredRoomId)
+    })
+
+    it('fails open to the reconstructed room id and warns when no room matches', async () => {
+      const warnSpy = spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        mockResponse({ items: [] })
+        mockResponse({ id: 'msg-1', roomId: usRoomId, roomType: 'group' })
+
+        const client = await new WebexClient().login({ token: 'test-token' })
+        await client.sendMessage(roomUuid, 'hello')
+
+        expect(JSON.parse(fetchCalls[1].options?.body as string).roomId).toBe(usRoomId)
+        expect(warnSpy).toHaveBeenCalled()
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('resolves a person email through the people search endpoint', async () => {
+      const personId = toRestId(personUuid, 'PEOPLE')
+      mockResponse({ items: [{ id: personId, emails: ['alice@example.com'], displayName: 'Alice', type: 'person' }] })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      const person = await client.getPerson('alice@example.com')
+
+      expect(person.id).toBe(personId)
+      const url = new URL(fetchCalls[0].url)
+      expect(url.pathname).toBe('/v1/people')
+      expect(url.searchParams.get('email')).toBe('alice@example.com')
+    })
+
+    it('reconstructs bare person and message uuids for REST calls', async () => {
+      const personId = toRestId(personUuid, 'PEOPLE')
+      const messageId = toRestId(messageUuid, 'MESSAGE')
+      mockResponse({ id: personId, emails: ['alice@example.com'], displayName: 'Alice', type: 'person' })
+      mockResponse({ id: messageId, roomId: usRoomId, text: 'hi' })
+
+      const client = await new WebexClient().login({ token: 'test-token' })
+      await client.getPerson(personUuid)
+      await client.getMessage(messageUuid)
+
+      expect(fetchCalls[0].url).toBe(`https://webexapis.com/v1/people/${personId}`)
+      expect(fetchCalls[1].url).toBe(`https://webexapis.com/v1/messages/${messageId}`)
+    })
+  })
+
   describe('rate limiting', () => {
     it('retries on 429 with Retry-After header', async () => {
       mockResponse({ message: 'Rate limited' }, 429, { 'Retry-After': '0.1' })
@@ -519,6 +606,7 @@ describe('WebexClient', () => {
     const CONV_BASE = 'https://conv-r.wbx2.com/conversation/api/v1'
     const TEST_ROOM_ID = Buffer.from('ciscospark://urn:TEAM:us-west-2_r/ROOM/abc123-def456').toString('base64')
     const TEST_CONV_UUID = 'abc123-def456'
+    const TEST_ACTIVITY_ID = toRestId('activity-123', 'MESSAGE')
 
     const mockActivity = (text: string, overrides?: Partial<Record<string, unknown>>) => ({
       id: 'activity-123',
@@ -605,7 +693,7 @@ describe('WebexClient', () => {
         const client = await createExtractedClient()
         const message = await client.sendMessage(TEST_ROOM_ID, 'Hello world')
 
-        expect(message.id).toBe('activity-123')
+        expect(message.id).toBe(TEST_ACTIVITY_ID)
         expect(message.text).toBe('Hello world')
         expect(message.personEmail).toBe('test@example.com')
         expect(message.created).toBe('2026-01-01T00:00:00.000Z')
@@ -670,7 +758,7 @@ describe('WebexClient', () => {
         const client = await createExtractedClient()
         const messages = await client.listMessages(TEST_ROOM_ID)
 
-        expect(messages[0].id).toBe('activity-123')
+        expect(messages[0].id).toBe(TEST_ACTIVITY_ID)
         expect(messages[0].text).toBe('Hello')
         expect(messages[0].personEmail).toBe('test@example.com')
         expect(messages[0].created).toBe('2026-01-01T00:00:00.000Z')
@@ -713,7 +801,7 @@ describe('WebexClient', () => {
         const client = await createExtractedClient()
         const message = await client.getMessage('activity-123')
 
-        expect(message.id).toBe('activity-123')
+        expect(message.id).toBe(TEST_ACTIVITY_ID)
         expect(message.text).toBe('Hello')
         expect(message.personEmail).toBe('test@example.com')
       })
@@ -843,7 +931,7 @@ describe('WebexClient', () => {
 
         const client = await createExtractedClient()
         const message = await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
-        expect(message.id).toBe('activity-123')
+        expect(message.id).toBe(TEST_ACTIVITY_ID)
       })
 
       it('throws when server returns activity linked to a different parent', async () => {
@@ -916,7 +1004,7 @@ describe('WebexClient', () => {
         expect(fetchCalls[0].url).toContain('/rooms?type=direct&max=100')
         expect(fetchCalls[1].url).toContain('/memberships?roomId=')
         expect(fetchCalls[2].url).toBe(`${CONV_BASE}/activities`)
-        expect(message.id).toBe('activity-123')
+        expect(message.id).toBe(TEST_ACTIVITY_ID)
       })
 
       it('throws WebexError when no existing direct conversation found', async () => {

package/src/platforms/webex/client.ts

@@ -1,5 +1,12 @@
 import { WebexCredentialManager } from './credential-manager'
 import { WebexEncryptionService } from './encryption'
+import {
+  decodeWebexId,
+  normalizeSdkMembership,
+  normalizeSdkMessage,
+  normalizeSdkPerson,
+  toRestId,
+} from './id-normalizer'
 import { KmsKeyProvider } from './kms-key-provider'
 import { escapeHtml, markdownToHtml, stripMarkdown } from './markdown-to-html'
 import type { WebexConfig, WebexMembership, WebexMessage, WebexPerson, WebexSpace } from './types'
@@ -15,6 +22,10 @@ interface RateLimitBucket {
   resetAt: number
 }
 
+interface WebexClientOptions {
+  roomResolutionWarningPrefix?: string
+}
+
 export class WebexClient {
   private token: string | null = null
   private deviceUrl: string | null = null
@@ -22,6 +33,13 @@ export class WebexClient {
   private buckets: Map<string, RateLimitBucket> = new Map()
   private globalRateLimitUntil: number = 0
   private encryption: WebexEncryptionService | null = null
+  private clusteredRoomIds = new Map<string, string>()
+  private roomIdLookups = new Map<string, Promise<string>>()
+  private roomResolutionWarningPrefix: string
+
+  constructor(options: WebexClientOptions = {}) {
+    this.roomResolutionWarningPrefix = options.roomResolutionWarningPrefix ?? '[webex]'
+  }
 
   async login(credentials?: { token: string; deviceUrl?: string; tokenType?: string }): Promise<this> {
     if (credentials) {
@@ -204,15 +222,24 @@ export class WebexClient {
   async testAuth(): Promise<WebexPerson> {
     if (this.useInternalAPI) {
       try {
-        return await this.request<WebexPerson>('GET', '/people/me')
+        return normalizeSdkPerson(await this.request<WebexPerson>('GET', '/people/me'))
       } catch (err) {
         const isAuthError = err instanceof WebexError && (err.code === 'http_401' || err.code === 'http_403')
         if (!isAuthError) throw err
         await this.testAuthInternal()
-        return { id: '', emails: [], displayName: '', orgId: '', type: 'person', created: '' } as WebexPerson
+        return normalizeSdkPerson({
+          id: '',
+          ref: '',
+          emails: [],
+          displayName: '',
+          orgId: '',
+          orgRef: '',
+          type: 'person',
+          created: '',
+        })
       }
     }
-    return this.request<WebexPerson>('GET', '/people/me')
+    return normalizeSdkPerson(await this.request<WebexPerson>('GET', '/people/me'))
   }
 
   private async testAuthInternal(): Promise<void> {
@@ -245,8 +272,55 @@ export class WebexClient {
     }
   }
 
+  async resolveRoomId(roomId: string): Promise<string> {
+    const decoded = decodeWebexId(roomId)
+    let uuid: string
+    let fallback: string
+
+    if (decoded) {
+      if (decoded.type !== 'ROOM' || decoded.cluster.startsWith('urn:')) return roomId
+      uuid = decoded.uuid
+      fallback = roomId
+    } else if (looksLikeUuid(roomId)) {
+      uuid = roomId
+      fallback = toRestId(roomId, 'ROOM')
+    } else {
+      return roomId
+    }
+
+    const cached = this.clusteredRoomIds.get(uuid)
+    if (cached) return cached
+
+    const inFlight = this.roomIdLookups.get(uuid)
+    if (inFlight) return inFlight
+
+    const lookup = this.lookupRoomId(uuid, fallback)
+    this.roomIdLookups.set(uuid, lookup)
+    try {
+      return await lookup
+    } finally {
+      this.roomIdLookups.delete(uuid)
+    }
+  }
+
+  async resolvePersonId(personId: string): Promise<string> {
+    if (!personId || decodeWebexId(personId)) return personId
+
+    if (looksLikeEmail(personId)) {
+      const [person] = await this.listPeople({ email: personId, max: 1 })
+      if (!person) {
+        throw new WebexError(`Person not found for ref: ${personId}`, 'not_found')
+      }
+      return person.id
+    }
+
+    if (looksLikeUuid(personId)) return toRestId(personId, 'PEOPLE')
+    return personId
+  }
+
   async getSpace(spaceId: string): Promise<WebexSpace> {
-    return this.request<WebexSpace>('GET', `/rooms/${spaceId}`)
+    const resolvedSpaceId = await this.resolveRoomId(spaceId)
+    return this.request<WebexSpace>('GET', `/rooms/${resolvedSpaceId}`)
   }
 
   async sendMessage(
@@ -254,15 +328,18 @@ export class WebexClient {
     text: string,
     options?: { markdown?: boolean; parentId?: string; files?: string[] },
   ): Promise<WebexMessage> {
+    const resolvedRoomId = await this.resolveRoomId(roomId)
+    const resolvedOptions = this.resolveMessageOptions(options)
+
     if (this.useInternalAPI) {
-      return this.sendMessageInternal(roomId, text, options)
+      return this.sendMessageInternal(resolvedRoomId, text, resolvedOptions)
     }
-    const body: Record<string, unknown> = { roomId }
-    if (options?.markdown) body.markdown = text
+    const body: Record<string, unknown> = { roomId: resolvedRoomId }
+    if (resolvedOptions?.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)
+    if (resolvedOptions?.parentId) body.parentId = resolvedOptions.parentId
+    if (resolvedOptions?.files?.length) body.files = resolvedOptions.files
+    return normalizeSdkMessage(await this.request<WebexMessage>('POST', '/messages', body))
   }
 
   private get useInternalAPI(): boolean {
@@ -283,7 +360,7 @@ export class WebexClient {
   }
 
   private decodeConvUuid(roomId: string): string {
-    return Buffer.from(roomId, 'base64').toString('utf8').split('/').pop() ?? roomId
+    return decodeWebexId(roomId)?.uuid ?? roomId
   }
 
   private async internalRequest<T>(path: string, init?: RequestInit): Promise<T> {
@@ -314,15 +391,18 @@ export class WebexClient {
       }
     }
 
-    return {
-      id: a.id,
+    return normalizeSdkMessage({
+      id: this.normalizeMessageId(a.id),
+      ref: '',
       roomId,
+      roomRef: '',
       roomType: 'group' as const,
       text,
-      personId: a.actor?.entryUUID ?? a.actor?.id ?? '',
+      personId: this.normalizePersonId(a.actor?.entryUUID ?? a.actor?.id ?? ''),
+      personRef: '',
       personEmail: a.actor?.emailAddress ?? '',
       created: a.published,
-    }
+    })
   }
 
   private async buildEncryptedObject(
@@ -407,7 +487,7 @@ export class WebexClient {
     const body = options?.markdown
       ? { toPersonEmail: personEmail, markdown: text }
       : { toPersonEmail: personEmail, text }
-    return this.request<WebexMessage>('POST', '/messages', body)
+    return normalizeSdkMessage(await this.request<WebexMessage>('POST', '/messages', body))
   }
 
   private async findDirectRoomByEmail(email: string): Promise<string | null> {
@@ -425,27 +505,31 @@ export class WebexClient {
     roomId: string,
     options?: { max?: number; mentionedPeople?: string; parentId?: string },
   ): Promise<WebexMessage[]> {
+    const resolvedRoomId = await this.resolveRoomId(roomId)
+    const resolvedOptions = await this.resolveListMessageOptions(options)
+
     if (this.useInternalAPI) {
-      const convUuid = this.decodeConvUuid(roomId)
-      const max = options?.max ?? 50
+      const convUuid = this.decodeConvUuid(resolvedRoomId)
+      const max = resolvedOptions?.max ?? 50
       const conv = await this.internalRequest<InternalConversation>(
         `/conversations/${convUuid}?activitiesLimit=${max}&participantsLimit=0`,
       )
       const activities = (conv.activities?.items ?? []).filter((a) => a.verb === 'post')
-      return Promise.all(activities.map((a) => this.activityToMessage(a, roomId)))
+      return Promise.all(activities.map((a) => this.activityToMessage(a, resolvedRoomId)))
     }
     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)
+    params.set('roomId', resolvedRoomId)
+    params.set('max', String(resolvedOptions?.max ?? 50))
+    if (resolvedOptions?.mentionedPeople) params.set('mentionedPeople', resolvedOptions.mentionedPeople)
+    if (resolvedOptions?.parentId) params.set('parentId', resolvedOptions.parentId)
     const data = await this.request<{ items: WebexMessage[] }>('GET', `/messages?${params}`)
-    return data.items
+    return data.items.map(normalizeSdkMessage)
   }
 
   async getMessage(messageId: string): Promise<WebexMessage> {
     if (this.useInternalAPI) {
-      const activity = await this.internalRequest<InternalActivity>(`/activities/${messageId}`)
+      const activityId = this.toMessageRef(messageId)
+      const activity = await this.internalRequest<InternalActivity>(`/activities/${activityId}`)
       const convId = activity.target?.id ?? ''
       // Internal API responses don't carry the cluster shard (e.g. `us-west-2_r`) the
       // public roomId encoding requires. The `unknown` placeholder is a sentinel — it
@@ -455,25 +539,26 @@ export class WebexClient {
       const roomId = convId ? Buffer.from(`ciscospark://urn:TEAM:unknown/ROOM/${convId}`).toString('base64') : ''
       return this.activityToMessage(activity, roomId)
     }
-    return this.request<WebexMessage>('GET', `/messages/${messageId}`)
+    return normalizeSdkMessage(await this.request<WebexMessage>('GET', `/messages/${this.resolveMessageId(messageId)}`))
   }
 
   async deleteMessage(messageId: string): Promise<void> {
     if (this.useInternalAPI) {
-      const activity = await this.internalRequest<InternalActivity>(`/activities/${messageId}`)
+      const activityId = this.toMessageRef(messageId)
+      const activity = await this.internalRequest<InternalActivity>(`/activities/${activityId}`)
       const convId = activity.target?.id
       if (!convId) throw new WebexError('Cannot determine conversation for activity', 'internal_error')
       await this.internalRequest<unknown>('/activities', {
         method: 'POST',
         body: JSON.stringify({
           verb: 'delete',
-          object: { id: messageId, objectType: 'activity' },
+          object: { id: activityId, objectType: 'activity' },
           target: { id: convId, objectType: 'conversation' },
         }),
       })
       return
     }
-    return this.request<void>('DELETE', `/messages/${messageId}`)
+    return this.request<void>('DELETE', `/messages/${this.resolveMessageId(messageId)}`)
   }
 
   async editMessage(
@@ -482,8 +567,11 @@ export class WebexClient {
     text: string,
     options?: { markdown?: boolean },
   ): Promise<WebexMessage> {
+    const resolvedRoomId = await this.resolveRoomId(roomId)
+
     if (this.useInternalAPI) {
-      const convUuid = this.decodeConvUuid(roomId)
+      const activityId = this.toMessageRef(messageId)
+      const convUuid = this.decodeConvUuid(resolvedRoomId)
       const { object, encryptionKeyUrl } = await this.buildEncryptedObject(convUuid, text, {
         ...options,
         forEdit: true,
@@ -493,7 +581,7 @@ export class WebexClient {
         verb: 'post',
         object,
         target: { id: convUuid, objectType: 'conversation' },
-        parent: { id: messageId, type: 'edit' },
+        parent: { id: activityId, type: 'edit' },
         clientTempId: `tmp-${Date.now()}-edit`,
       }
 
@@ -508,17 +596,19 @@ export class WebexClient {
 
       // Tolerate responses that omit `parent` (server may return minimal shape) —
       // only fail on an explicit mismatch between the echoed parent and the edited id.
-      if (result.parent && result.parent.id !== messageId) {
+      if (result.parent && result.parent.id !== activityId) {
         throw new WebexError(
-          `Edit rejected: server linked the new activity ${result.id} to ${result.parent.id} instead of ${messageId}.`,
+          `Edit rejected: server linked the new activity ${result.id} to ${result.parent.id} instead of ${activityId}.`,
           'edit_failed',
         )
       }
 
-      return this.activityToMessage(result, roomId)
+      return this.activityToMessage(result, resolvedRoomId)
     }
-    const body = options?.markdown ? { roomId, markdown: text } : { roomId, text }
-    return this.request<WebexMessage>('PUT', `/messages/${messageId}`, body)
+    const body = options?.markdown ? { roomId: resolvedRoomId, markdown: text } : { roomId: resolvedRoomId, text }
+    return normalizeSdkMessage(
+      await this.request<WebexMessage>('PUT', `/messages/${this.resolveMessageId(messageId)}`, body),
+    )
   }
 
   async listPeople(options?: { email?: string; displayName?: string; max?: number }): Promise<WebexPerson[]> {
@@ -529,26 +619,34 @@ export class WebexClient {
     const query = params.toString()
     const path = query ? `/people?${query}` : '/people'
     const data = await this.request<{ items: WebexPerson[] }>('GET', path)
-    return data.items
+    return data.items.map(normalizeSdkPerson)
   }
 
   async getPerson(personId: string): Promise<WebexPerson> {
-    return this.request<WebexPerson>('GET', `/people/${personId}`)
+    if (!decodeWebexId(personId) && looksLikeEmail(personId)) {
+      const [person] = await this.listPeople({ email: personId, max: 1 })
+      if (!person) {
+        throw new WebexError(`Person not found for ref: ${personId}`, 'not_found')
+      }
+      return person
+    }
+    return normalizeSdkPerson(await this.request<WebexPerson>('GET', `/people/${await this.resolvePersonId(personId)}`))
   }
 
   async listMyMemberships(options?: { max?: number }): Promise<WebexMembership[]> {
     const params = new URLSearchParams()
     params.set('max', String(options?.max ?? 100))
     const data = await this.request<{ items: WebexMembership[] }>('GET', `/memberships?${params}`)
-    return data.items
+    return data.items.map(normalizeSdkMembership)
   }
 
   async listMemberships(roomId: string, options?: { max?: number }): Promise<WebexMembership[]> {
+    const resolvedRoomId = await this.resolveRoomId(roomId)
     const params = new URLSearchParams()
-    params.set('roomId', roomId)
+    params.set('roomId', resolvedRoomId)
     if (options?.max) params.set('max', String(options.max))
     const data = await this.request<{ items: WebexMembership[] }>('GET', `/memberships?${params}`)
-    return data.items
+    return data.items.map(normalizeSdkMembership)
   }
 
   async uploadFile(
@@ -556,12 +654,14 @@ export class WebexClient {
     file: { content: Blob; filename: string },
     options?: { text?: string; markdown?: boolean; parentId?: string },
   ): Promise<WebexMessage> {
+    const resolvedRoomId = await this.resolveRoomId(roomId)
+    const resolvedParentId = options?.parentId ? this.resolveMessageId(options.parentId) : undefined
     const form = new FormData()
-    form.set('roomId', roomId)
+    form.set('roomId', resolvedRoomId)
     if (options?.text) {
       form.set(options.markdown ? 'markdown' : 'text', options.text)
     }
-    if (options?.parentId) form.set('parentId', options.parentId)
+    if (resolvedParentId) form.set('parentId', resolvedParentId)
     form.set('files', file.content, file.filename)
 
     const response = await fetch(`${BASE_URL}/messages`, {
@@ -574,7 +674,81 @@ export class WebexClient {
       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>
+    return normalizeSdkMessage((await response.json()) as WebexMessage)
+  }
+
+  private async lookupRoomId(uuid: string, fallback: string): Promise<string> {
+    try {
+      // Page through every room the account belongs to, stopping as soon as the
+      // trailing UUID matches because room titles are not stable identifiers.
+      for await (const room of this.iterateSpaces({ max: 1000 })) {
+        if (decodeWebexId(room.id)?.uuid === uuid) {
+          this.clusteredRoomIds.set(uuid, room.id)
+          return room.id
+        }
+      }
+    } catch {
+      // Network/auth failure: fail open to the un-corrected id rather than block the call.
+      return fallback
+    }
+
+    console.warn(
+      `${this.roomResolutionWarningPrefix} Could not resolve clustered room id for ${uuid}; falling back to the un-clustered id. ` +
+        'Room-scoped calls may fail if this room lives on a non-default Webex cluster.',
+    )
+    return fallback
+  }
+
+  private resolveMessageOptions(options?: {
+    markdown?: boolean
+    parentId?: string
+    files?: string[]
+  }): { markdown?: boolean; parentId?: string; files?: string[] } | undefined {
+    if (!options?.parentId) return options
+    return { ...options, parentId: this.resolveMessageId(options.parentId) }
+  }
+
+  private async resolveListMessageOptions(options?: {
+    max?: number
+    mentionedPeople?: string
+    parentId?: string
+  }): Promise<{ max?: number; mentionedPeople?: string; parentId?: string } | undefined> {
+    if (!options) return undefined
+    const resolved = { ...options }
+    if (options.mentionedPeople) {
+      resolved.mentionedPeople = await this.resolveMentionedPeople(options.mentionedPeople)
+    }
+    if (options.parentId) {
+      resolved.parentId = this.resolveMessageId(options.parentId)
+    }
+    return resolved
+  }
+
+  private async resolveMentionedPeople(mentionedPeople: string): Promise<string> {
+    if (mentionedPeople === 'me') return mentionedPeople
+    return this.resolvePersonId(mentionedPeople)
+  }
+
+  private resolveMessageId(messageId: string): string {
+    if (!messageId || decodeWebexId(messageId)) return messageId
+    // A lone message UUID does not identify its room cluster, so cluster correction
+    // is not possible without the room context.
+    if (looksLikeUuid(messageId)) return toRestId(messageId, 'MESSAGE')
+    return messageId
+  }
+
+  private toMessageRef(messageId: string): string {
+    return decodeWebexId(messageId)?.uuid ?? messageId
+  }
+
+  private normalizeMessageId(messageId: string): string {
+    if (!messageId || decodeWebexId(messageId)) return messageId
+    return toRestId(messageId, 'MESSAGE')
+  }
+
+  private normalizePersonId(personId: string): string {
+    if (!personId || decodeWebexId(personId)) return personId
+    return toRestId(personId, 'PEOPLE')
   }
 
   async downloadContent(contentRef: string): Promise<{ data: ArrayBuffer; filename: string; contentType: string }> {
@@ -638,6 +812,14 @@ function sanitizeFilename(name: string | undefined): string | undefined {
   return base
 }
 
+function looksLikeUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+}
+
+function looksLikeEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+}
+
 interface InternalActivity {
   id: string
   verb: string

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

@@ -9,6 +9,8 @@ import { WebexTokenExtractor } from '../token-extractor'
 import { WebexError } from '../types'
 import { extractAction, loginAction, logoutAction, oauthAction, statusAction } from './auth'
 
+const personId = Buffer.from('ciscospark://us/PEOPLE/person-1').toString('base64url')
+
 let promptQueue: string[] = []
 mock.module('node:readline/promises', () => ({
   createInterface: () => ({
@@ -33,7 +35,7 @@ describe('auth commands', () => {
   let originalStdinTTY: boolean | undefined
   let originalStdoutTTY: boolean | undefined
   const mockPerson = {
-    id: 'person-1',
+    id: personId,
     displayName: 'Test User',
     emails: ['test@example.com'],
     orgId: 'org-1',