agent-messenger 2.33.0 → 2.34.0

package/src/platforms/discord/client.ts

@@ -11,10 +11,13 @@ import type {
   DiscordMention,
   DiscordMessage,
   DiscordReadState,
+  DiscordReadStateSnapshot,
   DiscordRelationship,
   DiscordRole,
   DiscordSearchOptions,
   DiscordSearchResult,
+  DiscordUnreadDM,
+  DiscordUnreadDMsResult,
   DiscordUnreadMention,
   DiscordUnreadMentionsResult,
   DiscordUser,
@@ -34,6 +37,47 @@ function isSnowflakeNewer(candidate: string, marker: string): boolean {
   }
 }
 
+interface ReadStateCandidateChannel {
+  id: string
+  last_message_id?: string | null
+}
+
+export interface UnreadChannel<T> {
+  channel: T
+  lastMessageId: string
+  unreadCount: number | null
+}
+
+export function selectUnreadChannels<T extends ReadStateCandidateChannel>(
+  channels: T[],
+  readState: DiscordReadStateSnapshot,
+): UnreadChannel<T>[] {
+  const readStateByChannel = new Map(readState.states.map((state) => [state.channelId, state]))
+
+  const unread: UnreadChannel<T>[] = []
+  for (const channel of channels) {
+    const lastMessageId = channel.last_message_id
+    if (!lastMessageId) continue
+
+    const state = readStateByChannel.get(channel.id)
+    // An absent entry only carries meaning when the collection is complete. In a
+    // complete payload Discord omits read states for channels it never tracked, so a
+    // channel holding messages with no marker is far more likely never-opened than
+    // read: surface it with an unknown count rather than silently hiding it. In a
+    // partial payload the entry may simply have been left out, so reporting it would
+    // be a false positive on an already-read channel.
+    if (!state) {
+      if (!readState.partial) unread.push({ channel, lastMessageId, unreadCount: null })
+      continue
+    }
+
+    if (state.lastMessageId !== null && !isSnowflakeNewer(lastMessageId, state.lastMessageId)) continue
+    unread.push({ channel, lastMessageId, unreadCount: state.mentionCount })
+  }
+
+  return unread.sort((a, b) => (isSnowflakeNewer(a.lastMessageId, b.lastMessageId) ? -1 : 1))
+}
+
 export class DiscordError extends Error {
   code: string
 
@@ -350,6 +394,31 @@ export class DiscordClient {
     })
   }
 
+  async getUnreadDMs(options?: { limit?: number }): Promise<DiscordUnreadDMsResult> {
+    const [readState, channels] = await Promise.all([this.fetchReadStateSnapshot(), this.listDMChannels()])
+
+    const unread = selectUnreadChannels(channels, readState).map(
+      ({ channel, lastMessageId, unreadCount }): DiscordUnreadDM => ({
+        id: channel.id,
+        type: channel.type,
+        name: channel.name ?? null,
+        recipients: channel.recipients,
+        lastMessageId,
+        unreadCount,
+      }),
+    )
+
+    const totalUnread = unread.reduce((sum, channel) => sum + (channel.unreadCount ?? 0), 0)
+    const limited = options?.limit === undefined ? unread : unread.slice(0, options.limit)
+
+    return {
+      channels: limited,
+      count: unread.length,
+      totalUnread,
+      complete: !readState.partial,
+    }
+  }
+
   async getMentions(options?: { limit?: number; guildId?: string; before?: string }): Promise<DiscordMention[]> {
     const params = new URLSearchParams()
     params.set('limit', (options?.limit ?? 25).toString())
@@ -367,15 +436,19 @@ export class DiscordClient {
   }
 
   async fetchReadState(): Promise<DiscordReadState[]> {
+    return (await this.fetchReadStateSnapshot()).states
+  }
+
+  async fetchReadStateSnapshot(): Promise<DiscordReadStateSnapshot> {
     const { DiscordListener } = await import('./listener')
     const listener = new DiscordListener(this)
     try {
       await listener.start()
-      const readState = listener.getReadState()
-      if (readState === null) {
+      const snapshot = listener.getReadStateSnapshot()
+      if (snapshot === null) {
         throw new DiscordError('Discord gateway did not deliver read state', 'no_read_state')
       }
-      return readState
+      return snapshot
     } finally {
       listener.stop()
     }

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

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from 'bun:te
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
 import type { DiscordDMChannel } from '../types'
-import { createAction, listAction } from './dm'
+import { createAction, listAction, unreadAction } from './dm'
 
 class ProcessExit extends Error {
   constructor(readonly code?: string | number | null) {
@@ -13,6 +13,7 @@ class ProcessExit extends Error {
 
 let clientListDMChannelsSpy: ReturnType<typeof spyOn>
 let clientCreateDMSpy: ReturnType<typeof spyOn>
+let clientGetUnreadDMsSpy: ReturnType<typeof spyOn>
 let credManagerLoadSpy: ReturnType<typeof spyOn>
 
 const mockChannels: DiscordDMChannel[] = [
@@ -57,6 +58,30 @@ beforeEach(() => {
     ],
   })
 
+  clientGetUnreadDMsSpy = spyOn(DiscordClient.prototype, 'getUnreadDMs').mockResolvedValue({
+    channels: [
+      {
+        id: '123',
+        type: 1,
+        name: null,
+        recipients: [{ id: '456', username: 'testuser' }],
+        lastMessageId: '900',
+        unreadCount: 3,
+      },
+      {
+        id: '789',
+        type: 3,
+        name: 'Group Chat',
+        recipients: [{ id: '111', username: 'user1' }],
+        lastMessageId: '800',
+        unreadCount: null,
+      },
+    ],
+    count: 2,
+    totalUnread: 3,
+    complete: true,
+  })
+
   credManagerLoadSpy = spyOn(DiscordCredentialManager.prototype, 'load').mockResolvedValue({
     token: 'test-token',
     current_server: null,
@@ -67,6 +92,7 @@ beforeEach(() => {
 afterEach(() => {
   clientListDMChannelsSpy?.mockRestore()
   clientCreateDMSpy?.mockRestore()
+  clientGetUnreadDMsSpy?.mockRestore()
   credManagerLoadSpy?.mockRestore()
 })
 
@@ -150,4 +176,103 @@ describe('dm commands', () => {
       }
     })
   })
+
+  describe('unreadAction', () => {
+    it('reports unread channels with labelled types and totals', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.count).toBe(2)
+      expect(payload.total_unread).toBe(3)
+      expect(payload.complete).toBe(true)
+      expect(payload.channels[0]).toEqual({
+        id: '123',
+        type: 'DM',
+        name: null,
+        recipients: [{ id: '456', username: 'testuser' }],
+        last_message_id: '900',
+        unread_count: 3,
+      })
+      expect(payload.channels[1].type).toBe('Group DM')
+    })
+
+    it('preserves an unknown unread count as null', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.channels[1].unread_count).toBeNull()
+    })
+
+    it('surfaces an incomplete read state as complete false', async () => {
+      clientGetUnreadDMsSpy.mockResolvedValue({ channels: [], count: 0, totalUnread: 0, complete: false })
+
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.complete).toBe(false)
+    })
+
+    it('forwards the limit to the client', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ limit: 5, pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      expect(clientGetUnreadDMsSpy).toHaveBeenCalledWith({ limit: 5 })
+    })
+
+    it('handles authentication error', async () => {
+      credManagerLoadSpy.mockResolvedValue({
+        token: '',
+        current_server: null,
+        servers: {},
+      })
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation((code?: string | number | null) => {
+        throw new ProcessExit(code)
+      })
+
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await expect(unreadAction({ pretty: false })).rejects.toThrow(ProcessExit)
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Not authenticated'))
+        expect(exitSpy).toHaveBeenCalledWith(1)
+      } finally {
+        console.log = originalLog
+        exitSpy.mockRestore()
+      }
+    })
+  })
 })

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

@@ -1,4 +1,4 @@
-import { Command } from 'commander'
+import { Command, InvalidArgumentError } from 'commander'
 
 import { handleError } from '@/shared/utils/error-handler'
 import { formatOutput } from '@/shared/utils/output'
@@ -7,6 +7,18 @@ import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
 import type { DiscordDMChannel } from '../types'
 
+function parseLimit(value: string): number {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new InvalidArgumentError('Must be a positive integer.')
+  }
+  return parsed
+}
+
+function channelTypeLabel(type: number): string {
+  return type === 1 ? 'DM' : 'Group DM'
+}
+
 export async function listAction(options: { pretty?: boolean }): Promise<void> {
   try {
     const credManager = new DiscordCredentialManager()
@@ -22,7 +34,7 @@ export async function listAction(options: { pretty?: boolean }): Promise<void> {
 
     const output = channels.map((channel: DiscordDMChannel) => ({
       id: channel.id,
-      type: channel.type === 1 ? 'DM' : 'Group DM',
+      type: channelTypeLabel(channel.type),
       name: channel.name || null,
       recipients: channel.recipients.map((user) => ({
         id: user.id,
@@ -52,7 +64,7 @@ export async function createAction(userId: string, options: { pretty?: boolean }
 
     const output = {
       id: channel.id,
-      type: channel.type === 1 ? 'DM' : 'Group DM',
+      type: channelTypeLabel(channel.type),
       name: channel.name || null,
       recipients: channel.recipients.map((user) => ({
         id: user.id,
@@ -66,6 +78,42 @@ export async function createAction(userId: string, options: { pretty?: boolean }
   }
 }
 
+export async function unreadAction(options: { limit?: number; pretty?: boolean }): Promise<void> {
+  try {
+    const credManager = new DiscordCredentialManager()
+    const config = await credManager.load()
+
+    if (!config.token) {
+      console.log(formatOutput({ error: 'Not authenticated. Run "auth extract" first.' }, options.pretty))
+      process.exit(1)
+    }
+
+    const client = await new DiscordClient().login({ token: config.token })
+    const result = await client.getUnreadDMs({ limit: options.limit })
+
+    const output = {
+      channels: result.channels.map((channel) => ({
+        id: channel.id,
+        type: channelTypeLabel(channel.type),
+        name: channel.name,
+        recipients: channel.recipients.map((user) => ({
+          id: user.id,
+          username: user.username,
+        })),
+        last_message_id: channel.lastMessageId,
+        unread_count: channel.unreadCount,
+      })),
+      count: result.count,
+      total_unread: result.totalUnread,
+      complete: result.complete,
+    }
+
+    console.log(formatOutput(output, options.pretty))
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
 export const dmCommand = new Command('dm')
   .description('DM channel commands')
   .addCommand(
@@ -81,3 +129,15 @@ export const dmCommand = new Command('dm')
       .option('--pretty', 'Pretty print JSON output')
       .action(createAction),
   )
+  .addCommand(
+    new Command('unread')
+      .description('List unread DM and group-DM channels, newest first')
+      .option('--limit <n>', 'Max number of channels to return', parseLimit)
+      .option('--pretty', 'Pretty print JSON output')
+      .action((options) => {
+        unreadAction({
+          limit: options.limit,
+          pretty: options.pretty,
+        })
+      }),
+  )

package/src/platforms/discord/index.ts

@@ -26,6 +26,7 @@ export type {
   DiscordMessage,
   DiscordReaction,
   DiscordReadState,
+  DiscordReadStateSnapshot,
   DiscordRelationship,
   DiscordRole,
   DiscordRoleColors,
@@ -33,6 +34,8 @@ export type {
   DiscordSearchOptions,
   DiscordSearchResponse,
   DiscordSearchResult,
+  DiscordUnreadDM,
+  DiscordUnreadDMsResult,
   DiscordUnreadMention,
   DiscordUnreadMentionsResult,
   DiscordUser,

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

@@ -143,19 +143,28 @@ describe('parseReadStates', () => {
       { id: 'c2', read_state_type: 2, mention_count: 5 },
     ])
 
-    expect(result).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+    expect(result.states).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
   })
 
   it('normalizes missing last_message_id and mention_count', () => {
     const result = parseReadStates([{ id: 'c1' }])
 
-    expect(result).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 0 }])
+    expect(result.states).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 0 }])
   })
 
   it('skips malformed entries but keeps valid ones', () => {
     const result = parseReadStates([{ id: 'c1', mention_count: 1 }, { mention_count: 3 }])
 
-    expect(result).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 1 }])
+    expect(result.states).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 1 }])
+  })
+
+  it('treats a bare array payload as complete', () => {
+    expect(parseReadStates([{ id: 'c1' }]).partial).toBe(false)
+  })
+
+  it('reads the partial flag from a versioned payload', () => {
+    expect(parseReadStates({ entries: [{ id: 'c1' }], version: 7, partial: true }).partial).toBe(true)
+    expect(parseReadStates({ entries: [{ id: 'c1' }], version: 7 }).partial).toBe(false)
   })
 
   it('throws on a non-array, non-versioned payload', () => {

package/src/platforms/discord/listener.ts

@@ -3,16 +3,22 @@ import { EventEmitter } from 'events'
 import WebSocket from 'ws'
 
 import type { DiscordClient } from './client'
-import type { DiscordListenerEventMap, DiscordGatewayGenericEvent, DiscordReadState } from './types'
+import type {
+  DiscordListenerEventMap,
+  DiscordGatewayGenericEvent,
+  DiscordReadState,
+  DiscordReadStateSnapshot,
+} from './types'
 import { DiscordGatewayOpcode, DiscordRawReadStateSchema, DiscordReadyReadStateSchema } from './types'
 
-export function parseReadStates(value: unknown): DiscordReadState[] {
+export function parseReadStates(value: unknown): DiscordReadStateSnapshot {
   const parsed = DiscordReadyReadStateSchema.safeParse(value)
   if (!parsed.success) {
     throw new Error('Discord READY contained an invalid read_state payload')
   }
 
   const entries = Array.isArray(parsed.data) ? parsed.data : parsed.data.entries
+  const partial = Array.isArray(parsed.data) ? false : (parsed.data.partial ?? false)
 
   const readStates: DiscordReadState[] = []
   for (const entry of entries) {
@@ -25,7 +31,7 @@ export function parseReadStates(value: unknown): DiscordReadState[] {
       mentionCount: state.data.mention_count ?? 0,
     })
   }
-  return readStates
+  return { states: readStates, partial }
 }
 
 const GATEWAY_URL = 'wss://gateway.discord.gg/?v=10&encoding=json'
@@ -80,6 +86,7 @@ export class DiscordListener {
   private token: string | null = null
   private cachedUser: { id: string; username: string } | null = null
   private readState: DiscordReadState[] | null = null
+  private readStatePartial = false
   private generation = 0
   private startPromise: Promise<void> | null = null
   private pendingStartReject: ((error: Error) => void) | null = null
@@ -202,6 +209,10 @@ export class DiscordListener {
     return this.readState
   }
 
+  getReadStateSnapshot(): DiscordReadStateSnapshot | null {
+    return this.readState === null ? null : { states: this.readState, partial: this.readStatePartial }
+  }
+
   private isCurrent(generation: number, ws?: WebSocket): boolean {
     if (generation !== this.generation || !this.running) return false
     if (ws !== undefined && this.ws !== ws) return false
@@ -326,7 +337,9 @@ export class DiscordListener {
       this.sessionId = d.session_id
       this.resumeGatewayUrl = d.resume_gateway_url
       this.cachedUser = d.user
-      this.readState = d.read_state === undefined ? [] : parseReadStates(d.read_state)
+      const snapshot = d.read_state === undefined ? null : parseReadStates(d.read_state)
+      this.readState = snapshot === null ? [] : snapshot.states
+      this.readStatePartial = snapshot?.partial ?? false
       this.reconnectAttempts = 0
       this.emitter.emit('connected', { user: d.user, sessionId: d.session_id })
       return

package/src/platforms/discord/types.ts

@@ -139,6 +139,13 @@ export interface DiscordReadState {
   mentionCount: number
 }
 
+// When partial is true the entries are an incomplete slice, so an absent channel
+// carries no information: it may simply have been left out of this payload.
+export interface DiscordReadStateSnapshot {
+  states: DiscordReadState[]
+  partial: boolean
+}
+
 export interface DiscordUnreadMention extends DiscordMention {
   mention_count: number
 }
@@ -153,6 +160,31 @@ export interface DiscordUnreadMentionsResult {
   windowDays: number
 }
 
+export interface DiscordUnreadDM {
+  id: string
+  type: number
+  name: string | null
+  recipients: DiscordUser[]
+  lastMessageId: string
+  // Discord's own badge counter, which counts every message in a DM rather than
+  // only mentions. null when the channel has no READY read-state entry (count
+  // unknown); 0 when the DM is muted, since muting stops the counter but still
+  // leaves the channel unread.
+  unreadCount: number | null
+}
+
+// count and totalUnread describe every unread DM found, so they stay truthful when
+// `channels` is capped by a limit. totalUnread sums known counts only, meaning
+// channels with an unknown count contribute nothing to it. complete is false when
+// Discord delivered a partial read state, in which case never-opened DMs may be
+// missing from the result.
+export interface DiscordUnreadDMsResult {
+  channels: DiscordUnreadDM[]
+  count: number
+  totalUnread: number
+  complete: boolean
+}
+
 export interface DiscordSearchResult {
   id: string
   channel_id: string
@@ -512,7 +544,11 @@ export type DiscordRawReadState = z.infer<typeof DiscordRawReadStateSchema>
 // VERSIONED_READ_STATES gateway capability is negotiated.
 export const DiscordReadyReadStateSchema = z.union([
   z.array(z.unknown()),
-  z.object({ entries: z.array(z.unknown()), version: z.number().optional() }),
+  z.object({
+    entries: z.array(z.unknown()),
+    version: z.number().optional(),
+    partial: z.boolean().optional(),
+  }),
 ])
 
 export type DiscordGatewayEvent =