agent-messenger 2.8.0 → 2.9.0

package/src/platforms/channeltalkbot/commands/snapshot.test.ts

@@ -67,10 +67,28 @@ describe('snapshot command', () => {
   })
 
   describe('snapshotAction', () => {
-    test('returns workspace, groups, user_chats, managers, bots', async () => {
+    test('brief snapshot returns workspace, groups (names), chat counts, and hint', async () => {
       const manager = new ChannelBotCredentialManager(tempDir)
       const result = await snapshotAction({ _credManager: manager })
 
+      expect(result.error).toBeUndefined()
+      expect(result.workspace).toBeDefined()
+      expect(result.workspace?.id).toBe('ch1')
+      expect(result.workspace?.name).toBe('Test Workspace')
+      expect(result.groups).toBeDefined()
+      expect(result.groups?.[0]).toEqual({ id: 'grp1', name: 'Team Alpha' })
+      expect(result.user_chats).toBeDefined()
+      expect(result.user_chats?.opened_count).toBe(1)
+      expect(result.hint).toBeDefined()
+      expect(result.managers).toBeUndefined()
+      expect(result.bots).toBeUndefined()
+      expect(mockGetGroupMessages).not.toHaveBeenCalled()
+    })
+
+    test('full snapshot returns workspace, groups, user_chats, managers, bots', async () => {
+      const manager = new ChannelBotCredentialManager(tempDir)
+      const result = await snapshotAction({ full: true, _credManager: manager })
+
       expect(result.error).toBeUndefined()
       expect(result.workspace).toBeDefined()
       expect(result.workspace?.id).toBe('ch1')
@@ -83,7 +101,7 @@ describe('snapshot command', () => {
 
     test('groups-only flag skips user_chats, managers, bots', async () => {
       const manager = new ChannelBotCredentialManager(tempDir)
-      const result = await snapshotAction({ groupsOnly: true, _credManager: manager })
+      const result = await snapshotAction({ full: true, groupsOnly: true, _credManager: manager })
 
       expect(result.error).toBeUndefined()
       expect(result.workspace).toBeDefined()
@@ -95,7 +113,7 @@ describe('snapshot command', () => {
 
     test('chats-only flag skips groups, managers, bots', async () => {
       const manager = new ChannelBotCredentialManager(tempDir)
-      const result = await snapshotAction({ chatsOnly: true, _credManager: manager })
+      const result = await snapshotAction({ full: true, chatsOnly: true, _credManager: manager })
 
       expect(result.error).toBeUndefined()
       expect(result.workspace).toBeDefined()
@@ -105,21 +123,21 @@ describe('snapshot command', () => {
       expect(result.bots).toBeUndefined()
     })
 
-    test('groups include recent messages', async () => {
+    test('full groups include recent messages', async () => {
       const manager = new ChannelBotCredentialManager(tempDir)
-      const result = await snapshotAction({ groupsOnly: true, limit: 3, _credManager: manager })
+      const result = await snapshotAction({ full: true, groupsOnly: true, limit: 3, _credManager: manager })
 
       expect(result.groups?.[0].messages).toBeDefined()
       expect(result.groups?.[0].messages?.[0].id).toBe('msg1')
     })
 
-    test('user_chats includes counts and recent opened', async () => {
+    test('full user_chats includes counts and recent opened', async () => {
       const manager = new ChannelBotCredentialManager(tempDir)
-      const result = await snapshotAction({ chatsOnly: true, _credManager: manager })
+      const result = await snapshotAction({ full: true, chatsOnly: true, _credManager: manager })
 
       expect(result.user_chats?.opened_count).toBe(1)
       expect(result.user_chats?.recent_opened).toHaveLength(1)
-      expect(result.user_chats?.recent_opened[0].id).toBe('chat1')
+      expect(result.user_chats?.recent_opened?.[0].id).toBe('chat1')
     })
   })
 })

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

@@ -9,6 +9,7 @@ import { getClient } from './shared'
 interface SnapshotOption extends WorkspaceOption {
   groupsOnly?: boolean
   chatsOnly?: boolean
+  full?: boolean
   limit?: number
 }
 
@@ -33,7 +34,7 @@ interface SnapshotResult {
     opened_count: number
     snoozed_count: number
     closed_count: number
-    recent_opened: Array<{
+    recent_opened?: Array<{
       id: string
       name?: string
       user_id?: string
@@ -46,13 +47,13 @@ interface SnapshotResult {
   }
   managers?: Array<{ id: string; name: string; description?: string }>
   bots?: Array<{ id: string; name: string }>
+  hint?: string
   error?: string
 }
 
 export async function snapshotAction(options: SnapshotOption): Promise<SnapshotResult> {
   try {
     const client = await getClient(options)
-    const limit = options.limit ?? 5
 
     const channel = await client.getChannel()
     const workspace = {
@@ -62,71 +63,75 @@ export async function snapshotAction(options: SnapshotOption): Promise<SnapshotR
       description: channel.description,
     }
 
-    if (options.groupsOnly) {
-      const groups = await client.listGroups({ limit: 20 })
-      const groupsWithMessages = await Promise.all(
-        groups.map(async (g) => {
-          const messages = await client.getGroupMessages(g.id, { limit, sortOrder: 'desc' })
-          return {
-            id: g.id,
-            name: g.name,
-            messages: messages.map((m) => ({
-              id: m.id,
-              person_type: m.personType,
-              plain_text: m.plainText,
-              created_at: m.createdAt,
-            })),
-          }
-        }),
-      )
-      return { workspace, groups: groupsWithMessages }
+    if (options.full) {
+      return buildFullSnapshot(client, workspace, options)
     }
 
-    if (options.chatsOnly) {
-      const [openedChats, snoozedChats, closedChats] = await Promise.all([
-        client.listUserChats({ state: 'opened', limit: 10, sortOrder: 'desc' }),
-        client.listUserChats({ state: 'snoozed', limit: 1 }),
-        client.listUserChats({ state: 'closed', limit: 1 }),
-      ])
-
-      const recentOpened = await Promise.all(
-        openedChats.slice(0, 5).map(async (chat) => {
-          const messages = await client.getUserChatMessages(chat.id, { limit: 1, sortOrder: 'desc' })
-          return {
-            id: chat.id,
-            name: chat.name,
-            user_id: chat.userId,
-            last_message: messages[0]
-              ? {
-                  id: messages[0].id,
-                  plain_text: messages[0].plainText,
-                  created_at: messages[0].createdAt,
-                }
-              : undefined,
-          }
-        }),
-      )
+    return buildBriefSnapshot(client, workspace, options)
+  } catch (error) {
+    return { error: (error as Error).message }
+  }
+}
 
-      return {
-        workspace,
-        user_chats: {
-          opened_count: openedChats.length,
-          snoozed_count: snoozedChats.length,
-          closed_count: closedChats.length,
-          recent_opened: recentOpened,
-        },
-      }
+async function buildBriefSnapshot(
+  client: Awaited<ReturnType<typeof getClient>>,
+  workspace: SnapshotResult['workspace'],
+  options: SnapshotOption,
+): Promise<SnapshotResult> {
+  if (options.groupsOnly) {
+    const groups = await client.listGroups({ limit: 20 })
+    return {
+      workspace,
+      groups: groups.map((g) => ({ id: g.id, name: g.name })),
+      hint: "Use 'group messages <group>' for messages.",
     }
+  }
 
-    const [groups, openedChats, snoozedChats, closedChats, managers, bots] = await Promise.all([
-      client.listGroups({ limit: 20 }),
+  if (options.chatsOnly) {
+    const [openedChats, snoozedChats, closedChats] = await Promise.all([
       client.listUserChats({ state: 'opened', limit: 10, sortOrder: 'desc' }),
       client.listUserChats({ state: 'snoozed', limit: 1 }),
       client.listUserChats({ state: 'closed', limit: 1 }),
-      client.listManagers({ limit: 50 }),
-      client.listBots({ limit: 50 }),
     ])
+    return {
+      workspace,
+      user_chats: {
+        opened_count: openedChats.length,
+        snoozed_count: snoozedChats.length,
+        closed_count: closedChats.length,
+      },
+      hint: "Use 'chat list --state opened' for chat details, 'chat messages <chat>' for messages.",
+    }
+  }
+
+  const [groups, openedChats, snoozedChats, closedChats] = await Promise.all([
+    client.listGroups({ limit: 20 }),
+    client.listUserChats({ state: 'opened', limit: 10, sortOrder: 'desc' }),
+    client.listUserChats({ state: 'snoozed', limit: 1 }),
+    client.listUserChats({ state: 'closed', limit: 1 }),
+  ])
+
+  return {
+    workspace,
+    groups: groups.map((g) => ({ id: g.id, name: g.name })),
+    user_chats: {
+      opened_count: openedChats.length,
+      snoozed_count: snoozedChats.length,
+      closed_count: closedChats.length,
+    },
+    hint: "Use 'group messages <group>' for group messages, 'chat list --state opened' for chats, 'manager list' for managers.",
+  }
+}
+
+async function buildFullSnapshot(
+  client: Awaited<ReturnType<typeof getClient>>,
+  workspace: SnapshotResult['workspace'],
+  options: SnapshotOption,
+): Promise<SnapshotResult> {
+  const limit = options.limit ?? 5
 
+  if (options.groupsOnly) {
+    const groups = await client.listGroups({ limit: 20 })
     const groupsWithMessages = await Promise.all(
       groups.map(async (g) => {
         const messages = await client.getGroupMessages(g.id, { limit, sortOrder: 'desc' })
@@ -142,6 +147,15 @@ export async function snapshotAction(options: SnapshotOption): Promise<SnapshotR
         }
       }),
     )
+    return { workspace, groups: groupsWithMessages }
+  }
+
+  if (options.chatsOnly) {
+    const [openedChats, snoozedChats, closedChats] = await Promise.all([
+      client.listUserChats({ state: 'opened', limit: 10, sortOrder: 'desc' }),
+      client.listUserChats({ state: 'snoozed', limit: 1 }),
+      client.listUserChats({ state: 'closed', limit: 1 }),
+    ])
 
     const recentOpened = await Promise.all(
       openedChats.slice(0, 5).map(async (chat) => {
@@ -163,26 +177,78 @@ export async function snapshotAction(options: SnapshotOption): Promise<SnapshotR
 
     return {
       workspace,
-      groups: groupsWithMessages,
       user_chats: {
         opened_count: openedChats.length,
         snoozed_count: snoozedChats.length,
         closed_count: closedChats.length,
         recent_opened: recentOpened,
       },
-      managers: managers.map((m) => ({ id: m.id, name: m.name, description: m.description })),
-      bots: bots.map((b) => ({ id: b.id, name: b.name })),
     }
-  } catch (error) {
-    return { error: (error as Error).message }
+  }
+
+  const [groups, openedChats, snoozedChats, closedChats, managers, bots] = await Promise.all([
+    client.listGroups({ limit: 20 }),
+    client.listUserChats({ state: 'opened', limit: 10, sortOrder: 'desc' }),
+    client.listUserChats({ state: 'snoozed', limit: 1 }),
+    client.listUserChats({ state: 'closed', limit: 1 }),
+    client.listManagers({ limit: 50 }),
+    client.listBots({ limit: 50 }),
+  ])
+
+  const groupsWithMessages = await Promise.all(
+    groups.map(async (g) => {
+      const messages = await client.getGroupMessages(g.id, { limit, sortOrder: 'desc' })
+      return {
+        id: g.id,
+        name: g.name,
+        messages: messages.map((m) => ({
+          id: m.id,
+          person_type: m.personType,
+          plain_text: m.plainText,
+          created_at: m.createdAt,
+        })),
+      }
+    }),
+  )
+
+  const recentOpened = await Promise.all(
+    openedChats.slice(0, 5).map(async (chat) => {
+      const messages = await client.getUserChatMessages(chat.id, { limit: 1, sortOrder: 'desc' })
+      return {
+        id: chat.id,
+        name: chat.name,
+        user_id: chat.userId,
+        last_message: messages[0]
+          ? {
+              id: messages[0].id,
+              plain_text: messages[0].plainText,
+              created_at: messages[0].createdAt,
+            }
+          : undefined,
+      }
+    }),
+  )
+
+  return {
+    workspace,
+    groups: groupsWithMessages,
+    user_chats: {
+      opened_count: openedChats.length,
+      snoozed_count: snoozedChats.length,
+      closed_count: closedChats.length,
+      recent_opened: recentOpened,
+    },
+    managers: managers.map((m) => ({ id: m.id, name: m.name, description: m.description })),
+    bots: bots.map((b) => ({ id: b.id, name: b.name })),
   }
 }
 
 export const snapshotCommand = new Command('snapshot')
-  .description('Workspace overview for AI agent context')
+  .description('Workspace overview for AI agents (brief by default, use --full for comprehensive data)')
+  .option('--full', 'Include messages, managers, and bots (verbose)')
   .option('--groups-only', 'List groups only, skip user chats')
   .option('--chats-only', 'List user chats only, skip groups')
-  .option('--limit <n>', 'Messages per group/chat (default: 5)', '5')
+  .option('--limit <n>', 'Messages per group/chat with --full (default: 5)', '5')
   .option('--workspace <id>', 'Workspace ID')
   .option('--bot <name>', 'Bot name')
   .option('--pretty', 'Pretty print JSON output')
@@ -190,6 +256,7 @@ export const snapshotCommand = new Command('snapshot')
     try {
       const result = await snapshotAction({
         ...options,
+        full: options.full,
         limit: parseInt(options.limit, 10),
       })
       console.log(formatOutput(result, options.pretty))

package/src/platforms/discord/commands/snapshot.test.ts

@@ -8,7 +8,7 @@ test('snapshot: command is defined', () => {
 })
 
 test('snapshot: command has correct description', () => {
-  expect(snapshotCommand.description()).toContain('server state')
+  expect(snapshotCommand.description()).toContain('server overview')
 })
 
 test('snapshot: command has --channels-only option', () => {

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

@@ -11,6 +11,7 @@ import type { DiscordChannel } from '../types'
 export async function snapshotAction(options: {
   channelsOnly?: boolean
   usersOnly?: boolean
+  full?: boolean
   limit?: number
   pretty?: boolean
 }): Promise<void> {
@@ -25,7 +26,6 @@ export async function snapshotAction(options: {
 
     const client = await new DiscordClient().login({ token: config.token as string })
     const serverId = config.current_server as string
-    const messageLimit = options.limit || 20
 
     const snapshot: Record<string, any> = {}
 
@@ -35,51 +35,65 @@ export async function snapshotAction(options: {
       name: server.name,
     }
 
-    if (!options.usersOnly) {
-      const channels = await client.listChannels(serverId)
+    const isFull = options.full || options.channelsOnly || options.usersOnly
+    if (isFull) {
+      const messageLimit = options.limit || 20
 
-      snapshot.channels = channels.map((ch) => ({
-        id: ch.id,
-        name: ch.name,
-        type: ch.type,
-        topic: ch.topic,
-      }))
+      if (!options.usersOnly) {
+        const channels = await client.listChannels(serverId)
 
-      if (!options.channelsOnly) {
-        const isTextChannel = (ch: DiscordChannel) => ch.type === 0 || ch.type === 5
-        const textChannels = channels.filter(isTextChannel)
-
-        const channelMessages = await parallelMap(
-          textChannels,
-          async (channel: DiscordChannel) => {
-            const messages = await client.getMessages(channel.id, messageLimit)
-            return messages.map((msg) => ({
-              ...msg,
-              channel_name: channel.name,
-            }))
-          },
-          5,
-        )
-
-        snapshot.recent_messages = channelMessages.flat().map((msg) => ({
-          channel_id: msg.channel_id,
-          channel_name: msg.channel_name,
-          id: msg.id,
-          author: msg.author.username,
-          content: msg.content,
-          timestamp: msg.timestamp,
+        snapshot.channels = channels.map((ch) => ({
+          id: ch.id,
+          name: ch.name,
+          type: ch.type,
+          topic: ch.topic,
         }))
+
+        if (!options.channelsOnly) {
+          const isTextChannel = (ch: DiscordChannel) => ch.type === 0 || ch.type === 5
+          const textChannels = channels.filter(isTextChannel)
+
+          const channelMessages = await parallelMap(
+            textChannels,
+            async (channel: DiscordChannel) => {
+              const messages = await client.getMessages(channel.id, messageLimit)
+              return messages.map((msg) => ({
+                ...msg,
+                channel_name: channel.name,
+              }))
+            },
+            5,
+          )
+
+          snapshot.recent_messages = channelMessages.flat().map((msg) => ({
+            channel_id: msg.channel_id,
+            channel_name: msg.channel_name,
+            id: msg.id,
+            author: msg.author.username,
+            content: msg.content,
+            timestamp: msg.timestamp,
+          }))
+        }
       }
-    }
 
-    if (!options.channelsOnly) {
-      const users = await client.listUsers(serverId)
+      if (!options.channelsOnly) {
+        const users = await client.listUsers(serverId)
+
+        snapshot.members = users.map((u) => ({
+          id: u.id,
+          username: u.username,
+          global_name: u.global_name || null,
+        }))
+      }
+    } else {
+      if (!options.usersOnly) {
+        const channels = await client.listChannels(serverId)
+        const textChannels = channels.filter((ch: DiscordChannel) => ch.type === 0 || ch.type === 5)
+        snapshot.channels = textChannels.map((ch) => ({ id: ch.id, name: ch.name }))
+      }
 
-      snapshot.members = users.map((u) => ({
-        id: u.id,
-        username: u.username,
-        global_name: u.global_name || null,
-      }))
+      snapshot.hint =
+        "Use 'message list <channel>' for messages, 'channel info <channel>' for channel details, 'user list' for members."
     }
 
     console.log(formatOutput(snapshot, options.pretty))
@@ -89,14 +103,16 @@ export async function snapshotAction(options: {
 }
 
 export const snapshotCommand = new Command('snapshot')
-  .description('Get comprehensive server state for AI agents')
+  .description('Get server overview for AI agents (brief by default, use --full for comprehensive data)')
+  .option('--full', 'Include messages and members (verbose)')
   .option('--channels-only', 'Include only channels (exclude messages and members)')
   .option('--users-only', 'Include only members (exclude channels and messages)')
-  .option('--limit <n>', 'Number of recent messages per channel (default: 20)', '20')
+  .option('--limit <n>', 'Number of recent messages per channel with --full (default: 20)', '20')
   .action(async (options) => {
     await snapshotAction({
       channelsOnly: options.channelsOnly,
       usersOnly: options.usersOnly,
+      full: options.full,
       limit: parseInt(options.limit, 10),
       pretty: options.pretty,
     })

package/src/platforms/discordbot/commands/snapshot.test.ts

@@ -86,23 +86,17 @@ describe('snapshot command', () => {
     process.env = originalEnv
   })
 
-  describe('default (channels + messages)', () => {
-    test('returns channels with recent messages', async () => {
+  describe('default (brief)', () => {
+    test('returns channels with id and name only', async () => {
       const manager = await setupManager(tempDir)
 
       const result = await snapshotAction({ _credManager: manager })
 
       expect(result.server_id).toBe('guild1')
       expect(result.channels).toHaveLength(2)
-      expect(result.channels?.[0].id).toBe('ch1')
-      expect(result.channels?.[0].name).toBe('general')
-      expect(result.channels?.[0].messages).toHaveLength(2)
-      expect(result.channels?.[0].messages?.[0]).toEqual({
-        id: 'msg1-ch1',
-        author: 'alice',
-        content: 'Hello from ch1',
-        timestamp: '2025-01-01T00:00:00Z',
-      })
+      expect(result.channels?.[0]).toEqual({ id: 'ch1', name: 'general' })
+      expect(result.channels?.[1]).toEqual({ id: 'ch2', name: 'random' })
+      expect(result.hint).toBeDefined()
     })
 
     test('filters out non-text channels', async () => {
@@ -114,11 +108,39 @@ describe('snapshot command', () => {
       expect(channelNames).not.toContain('voice')
     })
 
-    test('fetches messages in parallel for all text channels', async () => {
+    test('does not fetch messages', async () => {
       const manager = await setupManager(tempDir)
 
       await snapshotAction({ _credManager: manager })
 
+      expect(mockGetMessages).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('--full (channels + messages)', () => {
+    test('returns channels with recent messages', async () => {
+      const manager = await setupManager(tempDir)
+
+      const result = await snapshotAction({ _credManager: manager, full: true })
+
+      expect(result.server_id).toBe('guild1')
+      expect(result.channels).toHaveLength(2)
+      expect(result.channels?.[0].id).toBe('ch1')
+      expect(result.channels?.[0].name).toBe('general')
+      expect(result.channels?.[0].messages).toHaveLength(2)
+      expect(result.channels?.[0].messages?.[0]).toEqual({
+        id: 'msg1-ch1',
+        author: 'alice',
+        content: 'Hello from ch1',
+        timestamp: '2025-01-01T00:00:00Z',
+      })
+    })
+
+    test('fetches messages in parallel for all text channels', async () => {
+      const manager = await setupManager(tempDir)
+
+      await snapshotAction({ _credManager: manager, full: true })
+
       expect(mockGetMessages).toHaveBeenCalledTimes(2)
       expect(mockGetMessages).toHaveBeenCalledWith('ch1', 5)
       expect(mockGetMessages).toHaveBeenCalledWith('ch2', 5)
@@ -127,7 +149,7 @@ describe('snapshot command', () => {
     test('respects --limit option', async () => {
       const manager = await setupManager(tempDir)
 
-      await snapshotAction({ _credManager: manager, limit: 10 })
+      await snapshotAction({ _credManager: manager, full: true, limit: 10 })
 
       expect(mockGetMessages).toHaveBeenCalledWith('ch1', 10)
       expect(mockGetMessages).toHaveBeenCalledWith('ch2', 10)
@@ -136,17 +158,17 @@ describe('snapshot command', () => {
     test('defaults limit to 5', async () => {
       const manager = await setupManager(tempDir)
 
-      await snapshotAction({ _credManager: manager })
+      await snapshotAction({ _credManager: manager, full: true })
 
       expect(mockGetMessages).toHaveBeenCalledWith('ch1', 5)
     })
   })
 
-  describe('--channels-only', () => {
+  describe('--full --channels-only', () => {
     test('returns only channel list without messages', async () => {
       const manager = await setupManager(tempDir)
 
-      const result = await snapshotAction({ _credManager: manager, channelsOnly: true })
+      const result = await snapshotAction({ _credManager: manager, full: true, channelsOnly: true })
 
       expect(result.server_id).toBe('guild1')
       expect(result.channels).toHaveLength(2)
@@ -156,11 +178,11 @@ describe('snapshot command', () => {
     })
   })
 
-  describe('--users-only', () => {
+  describe('--full --users-only', () => {
     test('returns only user list', async () => {
       const manager = await setupManager(tempDir)
 
-      const result = await snapshotAction({ _credManager: manager, usersOnly: true })
+      const result = await snapshotAction({ _credManager: manager, full: true, usersOnly: true })
 
       expect(result.server_id).toBe('guild1')
       expect(result.users).toHaveLength(3)