agent-messenger 2.21.0 → 2.23.0

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

@@ -40,11 +40,27 @@ function formatMessage(message: WebexMessage): MessageResult {
 export async function sendAction(
   space: string,
   text: string,
+  options: BotOption & { markdown?: boolean; parent?: string },
+): Promise<MessageResult> {
+  try {
+    const client = await getClient(options)
+    const message = await client.sendMessage(space, text, { markdown: options.markdown, parentId: options.parent })
+
+    return formatMessage(message)
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
+
+export async function replyAction(
+  space: string,
+  parentId: string,
+  text: string,
   options: BotOption & { markdown?: boolean },
 ): Promise<MessageResult> {
   try {
     const client = await getClient(options)
-    const message = await client.sendMessage(space, text, { markdown: options.markdown })
+    const message = await client.sendMessage(space, text, { markdown: options.markdown, parentId })
 
     return formatMessage(message)
   } catch (error) {
@@ -52,6 +68,30 @@ export async function sendAction(
   }
 }
 
+export async function repliesAction(
+  space: string,
+  parentId: string,
+  options: BotOption & { max?: string },
+): Promise<MessageResult> {
+  try {
+    const client = await getClient(options)
+    const max = options.max ? parseInt(options.max, 10) : 50
+    const messages = await client.listReplies(space, parentId, { max })
+
+    return {
+      messages: messages.map((msg) => ({
+        id: msg.id,
+        roomId: msg.roomId,
+        text: msg.text,
+        personEmail: msg.personEmail,
+        created: msg.created,
+      })),
+    }
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
+
 export async function dmAction(
   email: string,
   text: string,
@@ -133,12 +173,38 @@ export const messageCommand = new Command('message')
       .argument('<space>', 'Space/Room ID')
       .argument('<text>', 'Message text')
       .option('--markdown', 'Send as markdown')
+      .option('--parent <id>', 'Reply within a thread (parent message ID)')
       .option('--bot <id>', 'Use specific bot')
       .option('--pretty', 'Pretty print JSON output')
-      .action(async (space: string, text: string, opts: BotOption & { markdown?: boolean }) => {
+      .action(async (space: string, text: string, opts: BotOption & { markdown?: boolean; parent?: string }) => {
         cliOutput(await sendAction(space, text, opts), opts.pretty)
       }),
   )
+  .addCommand(
+    new Command('reply')
+      .description('Reply to a message in a thread')
+      .argument('<space>', 'Space/Room ID')
+      .argument('<parent>', 'Parent message ID')
+      .argument('<text>', 'Reply text')
+      .option('--markdown', 'Send as markdown')
+      .option('--bot <id>', 'Use specific bot')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (space: string, parent: string, text: string, opts: BotOption & { markdown?: boolean }) => {
+        cliOutput(await replyAction(space, parent, text, opts), opts.pretty)
+      }),
+  )
+  .addCommand(
+    new Command('replies')
+      .description('List replies in a thread')
+      .argument('<space>', 'Space/Room ID')
+      .argument('<parent>', 'Parent message ID')
+      .option('--max <n>', 'Number of replies to fetch', '50')
+      .option('--bot <id>', 'Use specific bot')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (space: string, parent: string, opts: BotOption & { max?: string }) => {
+        cliOutput(await repliesAction(space, parent, opts), opts.pretty)
+      }),
+  )
   .addCommand(
     new Command('dm')
       .description('Send a direct message by recipient email')

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

@@ -0,0 +1,60 @@
+import { Command } from 'commander'
+
+import { cliOutput } from '@/shared/utils/cli-output'
+
+import type { BotOption } from './shared'
+import { getClient } from './shared'
+
+interface SnapshotResult {
+  bot?: {
+    id: string
+    displayName: string
+    emails: string[]
+  }
+  spaces?: Array<{
+    id: string
+    title: string
+    type?: 'group' | 'direct'
+    lastActivity?: string
+  }>
+  hint?: string
+  error?: string
+}
+
+export async function snapshotAction(options: BotOption & { full?: boolean; max?: string }): Promise<SnapshotResult> {
+  try {
+    const client = await getClient(options)
+    const max = options.max ? parseInt(options.max, 10) : 100
+
+    const [me, spaces] = await Promise.all([client.testAuth(), client.listSpaces({ max })])
+
+    const result: SnapshotResult = {
+      bot: {
+        id: me.id,
+        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 })),
+    }
+
+    if (!options.full) {
+      result.hint = "Use 'message list <space>' for messages, 'space info <space>' for details."
+    }
+
+    return result
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
+
+export const snapshotCommand = new Command('snapshot')
+  .description('Workspace overview for AI agents (brief by default, --full for details)')
+  .option('--full', 'Include full space details')
+  .option('--max <n>', 'Number of spaces to retrieve', '100')
+  .option('--bot <id>', 'Use specific bot')
+  .option('--pretty', 'Pretty print JSON output')
+  .action(async (opts: BotOption & { full?: boolean; max?: string }) => {
+    cliOutput(await snapshotAction(opts), opts.pretty)
+  })

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

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
+import { existsSync, rmSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const mockListPeople = mock(() =>
+  Promise.resolve([
+    {
+      id: 'p1',
+      emails: ['alice@example.com'],
+      displayName: 'Alice',
+      orgId: 'o1',
+      type: 'person' as const,
+      created: '',
+    },
+  ]),
+)
+
+const mockGetPerson = mock(() =>
+  Promise.resolve({
+    id: 'p1',
+    emails: ['alice@example.com'],
+    displayName: 'Alice',
+    orgId: 'o1',
+    type: 'person' as const,
+    created: '2024-01-01T00:00:00Z',
+  }),
+)
+
+mock.module('../client', () => ({
+  WebexBotClient: class MockWebexBotClient {
+    async login(): Promise<this> {
+      return this
+    }
+    listPeople = mockListPeople
+    getPerson = mockGetPerson
+  },
+}))
+
+import { WebexBotCredentialManager } from '../credential-manager'
+import { infoAction, listAction } from './user'
+
+describe('webexbot user commands', () => {
+  let tempDir: string
+  let manager: WebexBotCredentialManager
+
+  beforeEach(async () => {
+    tempDir = join(tmpdir(), `webexbot-user-test-${Date.now()}`)
+    await mkdir(tempDir, { recursive: true })
+    manager = new WebexBotCredentialManager(tempDir)
+    await manager.setCredentials({ token: 'token123', bot_id: 'bot1', bot_name: 'Bot' })
+    mockListPeople.mockClear()
+    mockGetPerson.mockClear()
+  })
+
+  afterEach(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true })
+    }
+  })
+
+  it('lists people by email', async () => {
+    const result = await listAction({ _credManager: manager, email: 'alice@example.com' })
+
+    expect(result.users).toHaveLength(1)
+    expect(result.users?.[0].displayName).toBe('Alice')
+    expect(mockListPeople).toHaveBeenCalled()
+  })
+
+  it('gets a person by id', async () => {
+    const result = await infoAction('p1', { _credManager: manager })
+
+    expect(result.id).toBe('p1')
+    expect(result.displayName).toBe('Alice')
+  })
+})

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

@@ -0,0 +1,98 @@
+import { Command } from 'commander'
+
+import { cliOutput } from '@/shared/utils/cli-output'
+
+import type { WebexPerson } from '../../webex/types'
+import type { BotOption } from './shared'
+import { getClient } from './shared'
+
+interface UserResult {
+  id?: string
+  emails?: string[]
+  displayName?: string
+  nickName?: string
+  firstName?: string
+  lastName?: string
+  avatar?: string
+  orgId?: string
+  type?: 'person' | 'bot'
+  created?: string
+  users?: Array<{
+    id: string
+    emails: string[]
+    displayName: string
+    type: 'person' | 'bot'
+  }>
+  error?: string
+}
+
+function formatPerson(person: WebexPerson): UserResult {
+  return {
+    id: person.id,
+    emails: person.emails,
+    displayName: person.displayName,
+    nickName: person.nickName,
+    firstName: person.firstName,
+    lastName: person.lastName,
+    avatar: person.avatar,
+    orgId: person.orgId,
+    type: person.type,
+    created: person.created,
+  }
+}
+
+export async function listAction(
+  options: BotOption & { email?: string; displayName?: string; max?: string },
+): Promise<UserResult> {
+  try {
+    const client = await getClient(options)
+    const max = options.max ? parseInt(options.max, 10) : undefined
+    const people = await client.listPeople({ email: options.email, displayName: options.displayName, max })
+
+    return {
+      users: people.map((p) => ({
+        id: p.id,
+        emails: p.emails,
+        displayName: p.displayName,
+        type: p.type,
+      })),
+    }
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
+
+export async function infoAction(personId: string, options: BotOption): Promise<UserResult> {
+  try {
+    const client = await getClient(options)
+    const person = await client.getPerson(personId)
+    return formatPerson(person)
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
+
+export const userCommand = new Command('user')
+  .description('User commands')
+  .addCommand(
+    new Command('list')
+      .description('Search people by email or display name')
+      .option('--email <email>', 'Filter by exact email')
+      .option('--display-name <name>', 'Filter by display name prefix')
+      .option('--max <n>', 'Number of users to retrieve')
+      .option('--bot <id>', 'Use specific bot')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: BotOption & { email?: string; displayName?: string; max?: string }) => {
+        cliOutput(await listAction(opts), opts.pretty)
+      }),
+  )
+  .addCommand(
+    new Command('info')
+      .description('Get details for a person')
+      .argument('<id>', 'Person ID')
+      .option('--bot <id>', 'Use specific bot')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (personId: string, opts: BotOption) => {
+        cliOutput(await infoAction(personId, opts), opts.pretty)
+      }),
+  )

package/src/platforms/webexbot/index.ts

@@ -1,5 +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 { WebexBotListener } from './listener'
 export type { WebexBotListenerOptions } from './listener'
 export type { WebexBotConfig, WebexBotCredentials, WebexBotEntry, WebexBotListenerEventMap } from './types'

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

@@ -1,234 +1,47 @@
 import { describe, expect, it, mock } from 'bun:test'
-import { EventEmitter } from 'events'
-
-import type {
-  DecryptedMessage,
-  HandlerStatus,
-  MercuryActivity,
-  WebexMessageHandlerConfig,
-  WebexMessageHandlerEvents,
-} from 'webex-message-handler'
 
+import { WebexListener } from '../webex/listener'
 import { WebexBotListener } from './listener'
 
-const STATUS: HandlerStatus = {
-  status: 'connected',
-  webSocketOpen: true,
-  kmsInitialized: true,
-  deviceRegistered: true,
-  reconnectAttempt: 0,
-}
-
-const RAW_ACTIVITY: MercuryActivity = {
-  id: 'activity-123',
-  verb: 'post',
-  actor: { id: 'person-123', objectType: 'person', emailAddress: 'user@example.com' },
-  object: { id: 'object-123', objectType: 'comment', displayName: 'hello' },
-  target: { id: 'room-123', objectType: 'conversation' },
-  published: '2024-01-01T00:00:00Z',
-}
-
-const MESSAGE: DecryptedMessage = {
-  id: 'message-123',
-  roomId: 'room-123',
-  personId: 'person-123',
-  personEmail: 'user@example.com',
-  text: 'hello',
-  created: '2024-01-01T00:00:00Z',
-  mentionedPeople: [],
-  mentionedGroups: [],
-  files: [],
-  raw: RAW_ACTIVITY,
-}
-
-class FakeWebexMessageHandler extends EventEmitter {
-  connect = mock(() => Promise.resolve())
-  disconnect = mock(() => Promise.resolve())
-  connected = true
-
-  status(): HandlerStatus {
-    return STATUS
-  }
-
-  override on<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
-    return super.on(event, listener)
-  }
-
-  override off<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
-    return super.off(event, listener)
-  }
-
-  override once<K extends keyof WebexMessageHandlerEvents>(event: K, listener: WebexMessageHandlerEvents[K]): this {
-    return super.once(event, listener)
+const httpError = (): Response => new Response('', { status: 500 })
+const missingWdm = (): Response =>
+  new Response(JSON.stringify({ serviceLinks: {} }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+
+async function withFetch(makeResponse: () => Response, run: () => Promise<void>): Promise<void> {
+  const original = globalThis.fetch
+  globalThis.fetch = mock(() => Promise.resolve(makeResponse())) as typeof fetch
+  try {
+    await run()
+  } finally {
+    globalThis.fetch = original
   }
 }
 
 describe('WebexBotListener', () => {
-  it('bridges handler message events and webex_event', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-    const messageCreated = mock((_event: DecryptedMessage) => undefined)
-    const webexEvent = mock((_event: DecryptedMessage) => undefined)
-    listener.on('message_created', messageCreated)
-    listener.on('webex_event', webexEvent)
-
-    await listener.start()
-    handler.emit('message:created', MESSAGE)
-
-    expect(messageCreated).toHaveBeenCalledWith(MESSAGE)
-    expect(webexEvent).toHaveBeenCalledWith(MESSAGE)
-  })
-
-  it('stop calls handler disconnect', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-
-    await listener.start()
-    await listener.stop()
-
-    expect(handler.disconnect).toHaveBeenCalled()
-  })
-
-  it('start is idempotent', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-
-    await listener.start()
-    await listener.start()
-
-    expect(handler.connect).toHaveBeenCalledTimes(1)
-  })
-
-  it('start rethrows and resets state when connect fails, allowing retry', async () => {
-    const failing = new FakeWebexMessageHandler()
-    failing.connect = mock(() => Promise.reject(new Error('device registration failed')))
-    const ok = new FakeWebexMessageHandler()
-    const handlers = [failing, ok]
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handlers.shift()!,
-    })
-
-    await expect(listener.start()).rejects.toThrow('device registration failed')
-    expect(failing.disconnect).toHaveBeenCalled()
-
-    await listener.start()
-    expect(ok.connect).toHaveBeenCalledTimes(1)
-  })
-
-  it('does not throw when handler emits error with no error listener', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-    listener.on('message_created', () => undefined)
-
-    await listener.start()
-
-    expect(() => handler.emit('error', new Error('boom'))).not.toThrow()
-  })
-
-  it('ignores stale handler events after stop', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-    const messageCreated = mock((_event: DecryptedMessage) => undefined)
-    listener.on('message_created', messageCreated)
-
-    await listener.start()
-    await listener.stop()
-    handler.emit('message:created', MESSAGE)
-
-    expect(messageCreated).not.toHaveBeenCalled()
-  })
-
-  it('start-stop-start does not cross-talk between handlers', async () => {
-    const first = new FakeWebexMessageHandler()
-    const second = new FakeWebexMessageHandler()
-    const handlers = [first, second]
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handlers.shift()!,
-    })
-    const messageCreated = mock((_event: DecryptedMessage) => undefined)
-    listener.on('message_created', messageCreated)
-
-    await listener.start()
-    await listener.stop()
-    await listener.start()
-
-    first.emit('message:created', MESSAGE)
-    expect(messageCreated).not.toHaveBeenCalled()
-
-    second.emit('message:created', MESSAGE)
-    expect(messageCreated).toHaveBeenCalledTimes(1)
-  })
-
-  it('preserves disconnected reason', async () => {
-    const handler = new FakeWebexMessageHandler()
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-    const disconnected = mock((_reason: string) => undefined)
-    listener.on('disconnected', disconnected)
-
-    await listener.start()
-    handler.emit('disconnected', 'network lost')
-
-    expect(disconnected).toHaveBeenCalledWith('network lost')
-  })
-
-  it('concurrent start() calls share the same connect failure', async () => {
-    const handler = new FakeWebexMessageHandler()
-    handler.connect = mock(() => Promise.reject(new Error('connect failed')))
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
-    })
-
-    const first = listener.start()
-    const second = listener.start()
-    const firstResult = first.then(
-      () => 'ok',
-      (e: Error) => e.message,
-    )
-    const secondResult = second.then(
-      () => 'ok',
-      (e: Error) => e.message,
-    )
-
-    expect(await firstResult).toBe('connect failed')
-    expect(await secondResult).toBe('connect failed')
-    expect(handler.connect).toHaveBeenCalledTimes(1)
-  })
-
-  it('disconnects a handler whose connect resolves after stop', async () => {
-    const handler = new FakeWebexMessageHandler()
-    let resolveConnect: () => void = () => undefined
-    handler.connect = mock(() => new Promise<void>((resolve) => (resolveConnect = resolve)))
-    const client = { getToken: () => 'token123' }
-    const listener = new WebexBotListener(client, {
-      _handlerFactory: (_config: WebexMessageHandlerConfig) => handler,
+  it('is a WebexListener', () => {
+    expect(new WebexBotListener({ getToken: () => 'token' })).toBeInstanceOf(WebexListener)
+  })
+
+  for (const [label, makeResponse] of [
+    ['HTTP error', httpError],
+    ['missing serviceLinks.wdm', missingWdm],
+  ] as const) {
+    it(`surfaces WDM discovery failures (${label}) as WebexBotError`, async () => {
+      await withFetch(makeResponse, async () => {
+        await expect(new WebexBotListener({ getToken: () => 'token' }).start()).rejects.toMatchObject({
+          name: 'WebexBotError',
+          code: 'wdm_discovery_failed',
+        })
+      })
+    })
+
+    it(`WebexListener surfaces WDM discovery failures (${label}) as WebexError`, async () => {
+      await withFetch(makeResponse, async () => {
+        await expect(new WebexListener({ getToken: () => 'token' }).start()).rejects.toMatchObject({
+          name: 'WebexError',
+          code: 'wdm_discovery_failed',
+        })
+      })
     })
-
-    const starting = listener.start()
-    const stopping = listener.stop()
-    resolveConnect()
-    await Promise.all([starting, stopping])
-
-    expect(handler.disconnect).toHaveBeenCalled()
-  })
+  }
 })