agent-messenger 2.23.1 → 2.23.3

package/src/platforms/webex/types.ts

@@ -13,21 +13,27 @@ export interface WebexSpace {
 
 export interface WebexMessage {
   id: string
+  ref: string
   roomId: string
+  roomRef: string
   roomType: 'group' | 'direct'
   text?: string
   markdown?: string
   html?: string
   files?: string[]
   personId: string
+  personRef: string
   personEmail: string
   created: string
   parentId?: string
+  parentRef?: string
   mentionedPeople?: string[]
+  mentionedPeopleRefs?: string[]
 }
 
 export interface WebexPerson {
   id: string
+  ref: string
   emails: string[]
   displayName: string
   nickName?: string
@@ -35,14 +41,18 @@ export interface WebexPerson {
   lastName?: string
   avatar?: string
   orgId: string
+  orgRef: string
   type: 'person' | 'bot'
   created: string
 }
 
 export interface WebexMembership {
   id: string
+  ref: string
   roomId: string
+  roomRef: string
   personId: string
+  personRef: string
   personEmail: string
   personDisplayName: string
   isModerator: boolean
@@ -84,21 +94,27 @@ export const WebexSpaceSchema = z.object({
 
 export const WebexMessageSchema = z.object({
   id: z.string(),
+  ref: z.string(),
   roomId: z.string(),
+  roomRef: z.string(),
   roomType: z.enum(['group', 'direct']),
   text: z.string().optional(),
   markdown: z.string().optional(),
   html: z.string().optional(),
   files: z.array(z.string()).optional(),
   personId: z.string(),
+  personRef: z.string(),
   personEmail: z.string(),
   created: z.string(),
   parentId: z.string().optional(),
+  parentRef: z.string().optional(),
   mentionedPeople: z.array(z.string()).optional(),
+  mentionedPeopleRefs: z.array(z.string()).optional(),
 })
 
 export const WebexPersonSchema = z.object({
   id: z.string(),
+  ref: z.string(),
   emails: z.array(z.string()),
   displayName: z.string(),
   nickName: z.string().optional(),
@@ -106,14 +122,18 @@ export const WebexPersonSchema = z.object({
   lastName: z.string().optional(),
   avatar: z.string().optional(),
   orgId: z.string(),
+  orgRef: z.string(),
   type: z.enum(['person', 'bot']),
   created: z.string(),
 })
 
 export const WebexMembershipSchema = z.object({
   id: z.string(),
+  ref: z.string(),
   roomId: z.string(),
+  roomRef: z.string(),
   personId: z.string(),
+  personRef: z.string(),
   personEmail: z.string(),
   personDisplayName: z.string(),
   isModerator: z.boolean(),

package/src/platforms/webex/typings/webex-message-handler.d.ts

@@ -155,6 +155,8 @@ declare module 'webex-message-handler' {
   export interface DecryptedMessage {
     /** Mercury activity UUID. Works as parentId for threaded replies. */
     id: string
+    /** Raw UUID ref for `id`. */
+    ref: string
     /**
      * Full Conversation-service activity URL, when present on the raw Mercury
      * activity (e.g. for an outbound "acknowledge" read-receipt). Undefined if
@@ -163,8 +165,14 @@ declare module 'webex-message-handler' {
     url?: string
     /** Parent activity UUID for threaded replies. Undefined if not a thread reply. */
     parentId?: string
+    /** Raw UUID ref for `parentId`. Undefined when `parentId` is absent. */
+    parentRef?: string
     roomId: string
+    /** Raw UUID ref for `roomId`. */
+    roomRef: string
     personId: string
+    /** Raw UUID ref for `personId`. */
+    personRef: string
     personEmail: string
     text: string
     html?: string
@@ -172,6 +180,8 @@ declare module 'webex-message-handler' {
     roomType?: string
     /** Person UUIDs mentioned via @mention in the message. */
     mentionedPeople: string[]
+    /** Raw UUID refs for `mentionedPeople`, index-aligned. */
+    mentionedPeopleRefs: string[]
     /** Group mention types (e.g. "all") in the message. */
     mentionedGroups: string[]
     /** File URLs attached to the message. Empty if no files. */
@@ -181,19 +191,33 @@ declare module 'webex-message-handler' {
 
   export interface DeletedMessage {
     messageId: string
+    /** Raw UUID ref for `messageId`. */
+    messageRef: string
     roomId: string
+    /** Raw UUID ref for `roomId`. */
+    roomRef: string
     personId: string
+    /** Raw UUID ref for `personId`. */
+    personRef: string
   }
 
   export interface MembershipActivity {
-    /** Activity ID. */
+    /** Activity ID (raw Mercury activity UUID). */
     id: string
+    /** Raw UUID ref for `id`. Equal to `id` since the activity id is already raw. */
+    ref: string
     /** ID of the person who performed the action. */
     actorId: string
+    /** Raw UUID ref for `actorId`. */
+    actorRef: string
     /** ID of the member affected. */
     personId: string
+    /** Raw UUID ref for `personId`. */
+    personRef: string
     /** Conversation/space ID. */
     roomId: string
+    /** Raw UUID ref for `roomId`. */
+    roomRef: string
     /** Membership action: "add", "leave", "assignModerator", or "unassignModerator". */
     action: string
     /** ISO 8601 timestamp. */
@@ -207,14 +231,22 @@ declare module 'webex-message-handler' {
   export interface AttachmentAction {
     /** Activity ID. */
     id: string
+    /** Raw UUID ref for `id`. */
+    ref: string
     /** ID of the message the card was attached to. */
     messageId: string
+    /** Raw UUID ref for `messageId`. Empty when `messageId` is empty. */
+    messageRef: string
     /** ID of the person who submitted the card. */
     personId: string
+    /** Raw UUID ref for `personId`. */
+    personRef: string
     /** Email of the person who submitted the card. */
     personEmail: string
     /** Conversation/space ID. */
     roomId: string
+    /** Raw UUID ref for `roomId`. */
+    roomRef: string
     /** Card form input values. */
     inputs: Record<string, unknown>
     /** ISO 8601 timestamp. */
@@ -224,12 +256,18 @@ declare module 'webex-message-handler' {
   }
 
   export interface RoomActivity {
-    /** Activity ID. */
+    /** Activity ID (raw Mercury activity UUID). */
     id: string
+    /** Raw UUID ref for `id`. Equal to `id` since the activity id is already raw. */
+    ref: string
     /** Conversation/space ID. */
     roomId: string
+    /** Raw UUID ref for `roomId`. */
+    roomRef: string
     /** ID of the person who performed the action. */
     actorId: string
+    /** Raw UUID ref for `actorId`. */
+    actorRef: string
     /** Room action: "created" or "updated". */
     action: string
     /** ISO 8601 timestamp. */

package/src/platforms/webexbot/client.ts

@@ -2,33 +2,10 @@ import { WebexClient } from '../webex/client'
 import type { WebexMembership, WebexMessage, WebexPerson, WebexSpace } from '../webex/types'
 import { WebexBotError } from './types'
 
-interface DecodedWebexId {
-  cluster: string
-  type: string
-  uuid: string
-}
-
-// Webex REST ids are base64(url) of `ciscospark://<cluster>/<TYPE>/<uuid>`; the
-// cluster correction needs all three parts, not just the <uuid> `fromRestId` returns.
-function decodeWebexId(restId: string): DecodedWebexId | null {
-  if (!restId) return null
-  const decoded = Buffer.from(restId, 'base64').toString('utf-8')
-  const match = decoded.match(/^ciscospark:\/\/([^/]+)\/([^/]+)\/(.+)$/)
-  if (!match) return null
-  return { cluster: match[1], type: match[2], uuid: match[3] }
-}
-
 export class WebexBotClient {
-  private client = new WebexClient()
+  private client = new WebexClient({ roomResolutionWarningPrefix: '[webexbot]' })
   private token: string | null = null
 
-  // The listener flattens room ids to `ciscospark://us/ROOM/<uuid>`, but team/group
-  // rooms live on `ciscospark://urn:TEAM:<cluster>/ROOM/<uuid>` — a cluster the bare
-  // uuid cannot recover. Cache the real clustered id per uuid and dedupe concurrent
-  // lookups so a burst of calls triggers a single `listSpaces`.
-  private clusteredRoomIds = new Map<string, string>()
-  private roomIdLookups = new Map<string, Promise<string>>()
-
   async login(credentials?: { token: string }): Promise<this> {
     if (credentials) {
       if (!credentials.token) {
@@ -64,7 +41,7 @@ export class WebexBotClient {
   }
 
   async getSpace(spaceId: string): Promise<WebexSpace> {
-    return this.client.getSpace(await this.resolveRoomId(spaceId))
+    return this.client.getSpace(spaceId)
   }
 
   async sendMessage(
@@ -72,7 +49,7 @@ export class WebexBotClient {
     text: string,
     options?: { markdown?: boolean; parentId?: string; files?: string[] },
   ): Promise<WebexMessage> {
-    return this.client.sendMessage(await this.resolveRoomId(roomId), text, options)
+    return this.client.sendMessage(roomId, text, options)
   }
 
   async sendDirectMessage(personEmail: string, text: string, options?: { markdown?: boolean }): Promise<WebexMessage> {
@@ -80,14 +57,14 @@ export class WebexBotClient {
   }
 
   async listMessages(roomId: string, options?: { max?: number; parentId?: string }): Promise<WebexMessage[]> {
-    const resolvedRoomId = await this.resolveRoomId(roomId)
+    const resolvedRoomId = await this.client.resolveRoomId(roomId)
     const space = await this.client.getSpace(resolvedRoomId)
     const messageOptions = space.type === 'group' ? { ...options, mentionedPeople: 'me' } : options
     return this.client.listMessages(resolvedRoomId, messageOptions)
   }
 
   async listReplies(roomId: string, parentId: string, options?: { max?: number }): Promise<WebexMessage[]> {
-    return this.client.listMessages(await this.resolveRoomId(roomId), { ...options, parentId })
+    return this.client.listMessages(roomId, { ...options, parentId })
   }
 
   async getMessage(messageId: string): Promise<WebexMessage> {
@@ -108,7 +85,7 @@ export class WebexBotClient {
     text: string,
     options?: { markdown?: boolean },
   ): Promise<WebexMessage> {
-    return this.client.editMessage(messageId, await this.resolveRoomId(roomId), text, options)
+    return this.client.editMessage(messageId, roomId, text, options)
   }
 
   async listPeople(options?: { email?: string; displayName?: string; max?: number }): Promise<WebexPerson[]> {
@@ -124,7 +101,7 @@ export class WebexBotClient {
   }
 
   async listMemberships(roomId: string, options?: { max?: number }): Promise<WebexMembership[]> {
-    return this.client.listMemberships(await this.resolveRoomId(roomId), options)
+    return this.client.listMemberships(roomId, options)
   }
 
   async uploadFile(
@@ -132,53 +109,10 @@ export class WebexBotClient {
     file: { content: Blob; filename: string },
     options?: { text?: string; markdown?: boolean; parentId?: string },
   ): Promise<WebexMessage> {
-    return this.client.uploadFile(await this.resolveRoomId(roomId), file, options)
+    return this.client.uploadFile(roomId, file, options)
   }
 
   async downloadContent(contentRef: string): Promise<{ data: ArrayBuffer; filename: string; contentType: string }> {
     return this.client.downloadContent(contentRef)
   }
-
-  private async resolveRoomId(roomId: string): Promise<string> {
-    const decoded = decodeWebexId(roomId)
-    // Already cluster-qualified or undecodable: nothing to correct.
-    if (!decoded || decoded.cluster.startsWith('urn:')) return roomId
-
-    const { uuid } = decoded
-    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, roomId)
-    this.roomIdLookups.set(uuid, lookup)
-    try {
-      return await lookup
-    } finally {
-      this.roomIdLookups.delete(uuid)
-    }
-  }
-
-  private async lookupRoomId(uuid: string, fallback: string): Promise<string> {
-    try {
-      // Page through every room the bot belongs to (largest page size, following
-      // `Link` pages), stopping as soon as the trailing UUID matches.
-      for await (const room of this.client.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(
-      `[webexbot] 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
-  }
 }

package/src/platforms/webexbot/commands/file.ts

@@ -10,7 +10,9 @@ import { getClient } from './shared'
 
 interface FileResult {
   id?: string
+  ref?: string
   roomId?: string
+  roomRef?: string
   files?: string[]
   created?: string
   downloaded?: string
@@ -37,7 +39,9 @@ export async function uploadAction(
 
     return {
       id: message.id,
+      ref: message.ref,
       roomId: message.roomId,
+      roomRef: message.roomRef,
       files: message.files,
       created: message.created,
     }

package/src/platforms/webexbot/commands/member.ts

@@ -8,7 +8,9 @@ import { getClient } from './shared'
 interface MemberResult {
   members?: Array<{
     id: string
+    ref: string
     personId: string
+    personRef: string
     personEmail: string
     personDisplayName: string
     isModerator: boolean
@@ -26,7 +28,9 @@ export async function listAction(space: string, options: BotOption & { max?: str
     return {
       members: members.map((m) => ({
         id: m.id,
+        ref: m.ref,
         personId: m.personId,
+        personRef: m.personRef,
         personEmail: m.personEmail,
         personDisplayName: m.personDisplayName,
         isModerator: m.isModerator,

package/src/platforms/webexbot/commands/message.ts

@@ -8,7 +8,9 @@ import { getClient } from './shared'
 
 interface MessageResult {
   id?: string
+  ref?: string
   roomId?: string
+  roomRef?: string
   text?: string
   markdown?: string
   html?: string
@@ -16,7 +18,9 @@ interface MessageResult {
   created?: string
   messages?: Array<{
     id: string
+    ref: string
     roomId: string
+    roomRef: string
     text?: string
     personEmail: string
     created: string
@@ -28,7 +32,9 @@ interface MessageResult {
 function formatMessage(message: WebexMessage): MessageResult {
   return {
     id: message.id,
+    ref: message.ref,
     roomId: message.roomId,
+    roomRef: message.roomRef,
     text: message.text,
     markdown: message.markdown,
     html: message.html,
@@ -81,7 +87,9 @@ export async function repliesAction(
     return {
       messages: messages.map((msg) => ({
         id: msg.id,
+        ref: msg.ref,
         roomId: msg.roomId,
+        roomRef: msg.roomRef,
         text: msg.text,
         personEmail: msg.personEmail,
         created: msg.created,
@@ -116,7 +124,9 @@ export async function listAction(space: string, options: BotOption & { max?: str
     return {
       messages: messages.map((msg) => ({
         id: msg.id,
+        ref: msg.ref,
         roomId: msg.roomId,
+        roomRef: msg.roomRef,
         text: msg.text,
         personEmail: msg.personEmail,
         created: msg.created,

package/src/platforms/webexbot/commands/snapshot.ts

@@ -2,17 +2,20 @@ import { Command } from 'commander'
 
 import { cliOutput } from '@/shared/utils/cli-output'
 
+import { toRef } from '../../webex/id-normalizer'
 import type { BotOption } from './shared'
 import { getClient } from './shared'
 
 interface SnapshotResult {
   bot?: {
     id: string
+    ref: string
     displayName: string
     emails: string[]
   }
   spaces?: Array<{
     id: string
+    ref: string
     title: string
     type?: 'group' | 'direct'
     lastActivity?: string
@@ -31,12 +34,19 @@ export async function snapshotAction(options: BotOption & { full?: boolean; max?
     const result: SnapshotResult = {
       bot: {
         id: me.id,
+        ref: me.ref,
         displayName: me.displayName,
         emails: me.emails,
       },
       spaces: options.full
-        ? spaces.map((s) => ({ id: s.id, title: s.title, type: s.type, lastActivity: s.lastActivity }))
-        : spaces.map((s) => ({ id: s.id, title: s.title })),
+        ? spaces.map((s) => ({
+            id: s.id,
+            ref: toRef(s.id),
+            title: s.title,
+            type: s.type,
+            lastActivity: s.lastActivity,
+          }))
+        : spaces.map((s) => ({ id: s.id, ref: toRef(s.id), title: s.title })),
     }
 
     if (!options.full) {

package/src/platforms/webexbot/commands/space.ts

@@ -2,20 +2,25 @@ import { Command } from 'commander'
 
 import { cliOutput } from '@/shared/utils/cli-output'
 
+import { toRef } from '../../webex/id-normalizer'
 import type { BotOption } from './shared'
 import { getClient } from './shared'
 
 interface SpaceResult {
   id?: string
+  ref?: string
   title?: string
   type?: 'group' | 'direct'
   isLocked?: boolean
   teamId?: string | null
+  teamRef?: string | null
   lastActivity?: string
   created?: string
   creatorId?: string
+  creatorRef?: string
   spaces?: Array<{
     id: string
+    ref: string
     title: string
     type: 'group' | 'direct'
     lastActivity: string
@@ -33,6 +38,7 @@ export async function listAction(options: BotOption & { max?: string; type?: str
     return {
       spaces: spaces.map((s) => ({
         id: s.id,
+        ref: toRef(s.id),
         title: s.title,
         type: s.type,
         lastActivity: s.lastActivity,
@@ -50,13 +56,16 @@ export async function infoAction(spaceId: string, options: BotOption): Promise<S
     const space = await client.getSpace(spaceId)
     return {
       id: space.id,
+      ref: toRef(space.id),
       title: space.title,
       type: space.type,
       isLocked: space.isLocked,
       teamId: space.teamId || null,
+      teamRef: space.teamId ? toRef(space.teamId) : null,
       lastActivity: space.lastActivity,
       created: space.created,
       creatorId: space.creatorId,
+      creatorRef: toRef(space.creatorId),
     }
   } catch (error) {
     return { error: (error as Error).message }

package/src/platforms/webexbot/commands/user.test.ts

@@ -4,13 +4,19 @@ import { mkdir } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
+const restId = (type: string, ref: string) => Buffer.from(`ciscospark://us/${type}/${ref}`).toString('base64url')
+const personId = restId('PEOPLE', 'p1')
+const orgId = restId('ORGANIZATION', 'o1')
+
 const mockListPeople = mock(() =>
   Promise.resolve([
     {
-      id: 'p1',
+      id: personId,
+      ref: 'p1',
       emails: ['alice@example.com'],
       displayName: 'Alice',
-      orgId: 'o1',
+      orgId,
+      orgRef: 'o1',
       type: 'person' as const,
       created: '',
     },
@@ -19,10 +25,12 @@ const mockListPeople = mock(() =>
 
 const mockGetPerson = mock(() =>
   Promise.resolve({
-    id: 'p1',
+    id: personId,
+    ref: 'p1',
     emails: ['alice@example.com'],
     displayName: 'Alice',
-    orgId: 'o1',
+    orgId,
+    orgRef: 'o1',
     type: 'person' as const,
     created: '2024-01-01T00:00:00Z',
   }),
@@ -65,13 +73,15 @@ describe('webexbot user commands', () => {
 
     expect(result.users).toHaveLength(1)
     expect(result.users?.[0].displayName).toBe('Alice')
+    expect(result.users?.[0].ref).toBe('p1')
     expect(mockListPeople).toHaveBeenCalled()
   })
 
   it('gets a person by id', async () => {
     const result = await infoAction('p1', { _credManager: manager })
 
-    expect(result.id).toBe('p1')
+    expect(result.id).toBe(personId)
+    expect(result.ref).toBe('p1')
     expect(result.displayName).toBe('Alice')
   })
 })

package/src/platforms/webexbot/commands/user.ts

@@ -8,6 +8,7 @@ import { getClient } from './shared'
 
 interface UserResult {
   id?: string
+  ref?: string
   emails?: string[]
   displayName?: string
   nickName?: string
@@ -15,10 +16,12 @@ interface UserResult {
   lastName?: string
   avatar?: string
   orgId?: string
+  orgRef?: string
   type?: 'person' | 'bot'
   created?: string
   users?: Array<{
     id: string
+    ref: string
     emails: string[]
     displayName: string
     type: 'person' | 'bot'
@@ -29,6 +32,7 @@ interface UserResult {
 function formatPerson(person: WebexPerson): UserResult {
   return {
     id: person.id,
+    ref: person.ref,
     emails: person.emails,
     displayName: person.displayName,
     nickName: person.nickName,
@@ -36,6 +40,7 @@ function formatPerson(person: WebexPerson): UserResult {
     lastName: person.lastName,
     avatar: person.avatar,
     orgId: person.orgId,
+    orgRef: person.orgRef,
     type: person.type,
     created: person.created,
   }
@@ -52,6 +57,7 @@ export async function listAction(
     return {
       users: people.map((p) => ({
         id: p.id,
+        ref: p.ref,
         emails: p.emails,
         displayName: p.displayName,
         type: p.type,

package/src/platforms/webexbot/commands/whoami.ts

@@ -7,10 +7,12 @@ import { getClient } from './shared'
 
 interface WhoamiResult {
   id?: string
+  ref?: string
   emails?: string[]
   displayName?: string
   avatar?: string
   orgId?: string
+  orgRef?: string
   type?: 'person' | 'bot'
   created?: string
   error?: string
@@ -22,10 +24,12 @@ export async function whoamiAction(options: BotOption): Promise<WhoamiResult> {
     const info = await client.testAuth()
     return {
       id: info.id,
+      ref: info.ref,
       emails: info.emails,
       displayName: info.displayName,
       avatar: info.avatar,
       orgId: info.orgId,
+      orgRef: info.orgRef,
       type: info.type,
       created: info.created,
     }

package/src/platforms/webexbot/index.ts

@@ -1,7 +1,7 @@
 export { WebexBotClient } from './client'
 export { WebexBotCredentialManager } from './credential-manager'
-export { fromRestId, toRestId } from '../webex/id-normalizer'
-export type { WebexRestIdType } from '../webex/id-normalizer'
+export { decodeWebexId, fromRestId, toRef, toRestId } from '../webex/id-normalizer'
+export type { DecodedWebexId, WebexRestIdType } from '../webex/id-normalizer'
 export { WebexBotListener } from './listener'
 export type { WebexBotListenerOptions } from './listener'
 export type { WebexBotConfig, WebexBotCredentials, WebexBotEntry, WebexBotListenerEventMap } from './types'

package/src/tui/adapters/types.ts

@@ -1,12 +1,15 @@
 export interface UnifiedChannel {
   id: string
+  ref?: string
   name: string
   parentId?: string
 }
 
 export interface UnifiedMessage {
   id: string
+  ref?: string
   channelId: string
+  channelRef?: string
   author: string
   content: string
   timestamp: string