agent-messenger 2.27.2 → 2.28.0

package/skills/agent-instagram/references/common-patterns.md

@@ -323,6 +323,39 @@ agent-instagram message send-to alice "Hello!"
 agent-instagram message send 12345678901 "Hello!"
 ```
 
+## Pattern 11: Real-Time DM Monitor (SDK)
+
+**Use case**: Receive new DMs as they arrive, without polling
+
+The SDK's `InstagramHybridListener` is the right tool for continuous DM monitoring. It connects over Instagram's MQTToT transport and falls back to polling automatically — no manual loop or `sleep` needed.
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client)
+
+listener.on('connected', ({ userId, transport }) => {
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text ?? `[${msg.type}]`}`)
+})
+
+listener.on('error', (err) => {
+  console.error('Listener error:', err.message)
+})
+
+await listener.start()
+// Runs until listener.stop() is called
+```
+
+**When to use**: Any time you need to react to incoming DMs in real time — notifications, bots, monitoring dashboards. Prefer this over a polling shell loop.
+
+**Contrast with shell polling**: The `monitor-chat.sh` template uses `sleep` + `message list` in a loop. That works for simple scripts but makes one HTTP request per interval and can't react faster than the interval. The SDK listener holds a persistent connection and delivers messages as they arrive.
+
 ## Anti-Patterns
 
 ### Don't Poll Too Frequently
@@ -341,6 +374,8 @@ while true; do
 done
 ```
 
+For real-time monitoring, the SDK's `InstagramHybridListener` is a better alternative — it holds a persistent connection and avoids repeated HTTP requests entirely. See [Pattern 11](#pattern-11-real-time-dm-monitor-sdk) above.
+
 ### Don't Spam Threads
 
 ```bash
@@ -360,3 +395,4 @@ agent-instagram message send "$THREAD" "$MESSAGE"
 ## See Also
 
 - [Authentication Guide](authentication.md) - Setting up credentials
+- For real-time events, use the `InstagramHybridListener` SDK (see SKILL.md → SDK: Real-Time Events)

package/skills/agent-instagram/templates/monitor-chat.sh

@@ -12,6 +12,11 @@
 # Example:
 #   ./monitor-chat.sh 340282366841710300949128138443434234567
 #   ./monitor-chat.sh 340282366841710300949128138443434234567 10
+#
+# NOTE: For real-time monitoring, prefer the SDK's InstagramHybridListener over
+# this poll-based approach. It connects over Instagram's MQTToT transport and
+# delivers messages as they arrive, with automatic fallback to polling if needed.
+# See SKILL.md -> SDK: Real-Time Events for setup and usage.
 
 set -euo pipefail
 

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:

package/skills/agent-line/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-line
 description: Interact with LINE - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-line:*)
 metadata:
   openclaw:

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegrambot
 description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-telegrambot:*)
 metadata:
   openclaw:

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:

package/skills/agent-webexbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webexbot
 description: Interact with Cisco Webex using bot tokens - send messages, reply in threads, upload and download files, look up people, read spaces, manage memberships, stream real-time events
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-webexbot:*)
 metadata:
   openclaw:

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/cli.ts

@@ -68,6 +68,10 @@ program.command('channeltalk', 'Interact with Channel Talk', {
   executableFile: join(__dirname, 'platforms', 'channeltalk', `cli${ext}`),
 })
 
+program.command('imessage', 'Interact with iMessage via imsg (local, on-Mac)', {
+  executableFile: join(__dirname, 'platforms', 'imessage', `cli${ext}`),
+})
+
 program.command('channeltalkbot', 'Interact with Channel Talk using API credentials', {
   executableFile: join(__dirname, 'platforms', 'channeltalkbot', `cli${ext}`),
 })

package/src/platforms/imessage/cli.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+
+import type { Command as CommandType } from 'commander'
+import { Command } from 'commander'
+
+import pkg from '../../../package.json' with { type: 'json' }
+import { authCommand, chatCommand, doctorCommand, messageCommand, setupCommand, whoamiCommand } from './commands/index'
+import { ensureIMessageAuth } from './ensure-auth'
+
+const UNGUARDED = new Set(['auth', 'setup', 'doctor'])
+
+function isUnguarded(command: CommandType): boolean {
+  let cmd: CommandType | null = command
+  while (cmd) {
+    if (UNGUARDED.has(cmd.name())) return true
+    cmd = cmd.parent
+  }
+  return false
+}
+
+const program = new Command()
+
+program.name('agent-imessage').description('CLI tool for iMessage via imsg (local, on-Mac)').version(pkg.version)
+
+program.hook('preAction', async (_thisCommand, actionCommand) => {
+  if (isUnguarded(actionCommand)) return
+  await ensureIMessageAuth()
+})
+
+program.addCommand(authCommand)
+program.addCommand(setupCommand)
+program.addCommand(doctorCommand)
+program.addCommand(chatCommand)
+program.addCommand(messageCommand)
+program.addCommand(whoamiCommand)
+
+program.parse(process.argv)
+
+export default program

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

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'bun:test'
+import { join } from 'node:path'
+
+import { ImsgClient } from './client'
+import { IMessageError } from './types'
+
+const STUB = join(import.meta.dir, 'test-stub-imsg.mjs')
+
+function clientWith(mode = 'ok'): ImsgClient {
+  process.env.IMSG_STUB_MODE = mode
+  return new ImsgClient()
+}
+
+describe('ImsgClient (against stub imsg binary)', () => {
+  it('getVersion returns the imsg version', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    expect(await c.getVersion()).toBe('0.11.1')
+    await c.close()
+  })
+
+  it('connect succeeds and listChats maps group/individual + fields', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const chats = await c.listChats(10)
+    expect(chats[0]).toMatchObject({ id: 42, name: 'Jane', is_group: false, service: 'iMessage' })
+    expect(chats[1]).toMatchObject({ id: 43, name: 'Crew', is_group: true })
+    expect(chats[1]?.participants).toHaveLength(2)
+    await c.close()
+  })
+
+  it('connect throws full_disk_access when the DB is not readable', async () => {
+    const c = await clientWith('fda_denied').login({ binaryPath: STUB })
+    try {
+      await c.connect()
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('full_disk_access')
+      expect((error as IMessageError).suggestion).toContain('Full Disk Access')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('getMessages maps fields oldest-first with is_outgoing', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const msgs = await c.getMessages(42, 10)
+    expect(msgs.map((m) => m.guid)).toEqual(['m1', 'm2'])
+    expect(msgs[0]?.is_outgoing).toBe(false)
+    expect(msgs[1]?.is_outgoing).toBe(true)
+    await c.close()
+  })
+
+  it('sendMessage returns guid/id; send failure maps to send_failed', async () => {
+    const ok = await clientWith('ok').login({ binaryPath: STUB })
+    await ok.connect()
+    expect(await ok.sendMessage({ chatId: 42 }, 'hi')).toMatchObject({ guid: 'sent-guid', id: 99, is_outgoing: true })
+    await ok.close()
+
+    const fail = await clientWith('send_fail').login({ binaryPath: STUB })
+    await fail.connect()
+    try {
+      await fail.sendMessage({ chatId: 42 }, 'hi')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('send_failed')
+    } finally {
+      await fail.close()
+    }
+  })
+
+  it('watch delivers live notifications', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const received: string[] = []
+    const stop = await c.watch((m) => received.push(m.guid), { chatId: 42 })
+    await new Promise((r) => setTimeout(r, 120))
+    await stop()
+    await c.close()
+    expect(received).toContain('m3')
+  })
+
+  it('sendReaction: standard via CLI; custom + message-target rejected', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    await expect(c.sendReaction(42, 'love')).resolves.toBeUndefined()
+    await expect(c.sendReaction(42, 'sparkles')).rejects.toMatchObject({ code: 'private_api_required' })
+    await expect(c.sendReaction(42, 'love', 'some-guid')).rejects.toMatchObject({ code: 'private_api_required' })
+    await c.close()
+  })
+
+  it('maps an Automation-denied "imsg react" failure to automation_denied (not send_failed)', async () => {
+    const c = await clientWith('react_automation_denied').login({ binaryPath: STUB })
+    await c.connect()
+    try {
+      await c.sendReaction(42, 'love')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('automation_denied')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('maps AppleScript "not authorized" send error to automation_denied (not send_failed)', async () => {
+    const c = await clientWith('automation_denied').login({ binaryPath: STUB })
+    await c.connect()
+    try {
+      await c.sendMessage({ chatId: 42 }, 'hi')
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('automation_denied')
+    } finally {
+      await c.close()
+    }
+  })
+
+  it('close() rejects in-flight requests instead of hanging', async () => {
+    const c = await clientWith().login({ binaryPath: STUB })
+    await c.connect()
+    const pending = c.listChats(1)
+    await c.close()
+    await expect(pending).rejects.toMatchObject({ code: 'rpc_error' })
+  })
+
+  it('imsg_not_found when the binary does not exist', async () => {
+    const c = await new ImsgClient().login({ binaryPath: '/nonexistent/imsg-xyz' })
+    try {
+      await c.connect()
+      throw new Error('should have thrown')
+    } catch (error) {
+      expect((error as IMessageError).code).toBe('imsg_not_found')
+    } finally {
+      await c.close()
+    }
+  })
+})

package/src/platforms/imessage/client.ts

@@ -0,0 +1,253 @@
+import { spawn } from 'node:child_process'
+
+import { classifyImsgFailure } from './errors'
+import { ImsgRpc } from './rpc'
+import { type IMessageChatSummary, type IMessageMessageSummary, type IMessageStatus, IMessageError } from './types'
+
+interface ImsgChat {
+  id: number
+  name?: string | null
+  identifier?: string | null
+  guid?: string | null
+  service?: string | null
+  is_group?: boolean
+  participants?: string[] | null
+  last_message?: ImsgMessage | null
+}
+
+interface ImsgMessage {
+  id: number
+  chat_id: number
+  guid: string
+  sender?: string | null
+  sender_name?: string | null
+  is_from_me?: boolean
+  text?: string | null
+  created_at?: string | null
+}
+
+const STANDARD_REACTIONS = new Set(['love', 'like', 'dislike', 'laugh', 'emphasis', 'question'])
+
+export interface SendTarget {
+  chatId?: number
+  chatGuid?: string
+  chatIdentifier?: string
+  to?: string
+}
+
+export type OneShotRunner = (
+  binaryPath: string,
+  args: string[],
+) => Promise<{ code: number; stdout: string; stderr: string }>
+
+const defaultRunner: OneShotRunner = (binaryPath, args) =>
+  new Promise((resolve, reject) => {
+    let proc: ReturnType<typeof spawn>
+    try {
+      proc = spawn(binaryPath, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch {
+      reject(new IMessageError(`Could not run "${binaryPath}".`, 'imsg_not_found'))
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    proc.stdout?.on('data', (c: Buffer) => (stdout += c.toString()))
+    proc.stderr?.on('data', (c: Buffer) => (stderr += c.toString()))
+    proc.once('error', (err: NodeJS.ErrnoException) => {
+      reject(
+        err.code === 'ENOENT'
+          ? new IMessageError(`Could not run "${binaryPath}".`, 'imsg_not_found', {
+              suggestion: 'Install imsg: "brew install steipete/tap/imsg".',
+              doctorCommand: 'agent-imessage doctor',
+            })
+          : err,
+      )
+    })
+    proc.once('close', (code) => resolve({ code: code ?? 0, stdout, stderr }))
+  })
+
+function summarizeMessage(msg: ImsgMessage): IMessageMessageSummary {
+  return {
+    id: msg.id,
+    guid: msg.guid,
+    chat_id: msg.chat_id,
+    from: msg.is_from_me ? '' : (msg.sender ?? ''),
+    from_name: msg.sender_name ?? undefined,
+    is_outgoing: Boolean(msg.is_from_me),
+    timestamp: msg.created_at ?? new Date(0).toISOString(),
+    text: msg.text ?? undefined,
+  }
+}
+
+function summarizeChat(chat: ImsgChat): IMessageChatSummary {
+  return {
+    id: chat.id,
+    guid: chat.guid ?? null,
+    identifier: chat.identifier ?? null,
+    name: chat.name?.trim() || chat.identifier || chat.guid || String(chat.id),
+    service: chat.service ?? 'iMessage',
+    is_group: Boolean(chat.is_group),
+    participants: chat.participants ?? [],
+    last_message: chat.last_message ? summarizeMessage(chat.last_message) : undefined,
+  }
+}
+
+export class ImsgClient {
+  private binaryPath = 'imsg'
+  private region: string | undefined
+  private rpc: ImsgRpc
+  private runner: OneShotRunner
+
+  constructor(deps?: { rpc?: ImsgRpc; runner?: OneShotRunner }) {
+    this.rpc = deps?.rpc ?? new ImsgRpc()
+    this.runner = deps?.runner ?? defaultRunner
+  }
+
+  async login(credentials?: { binaryPath?: string; region?: string }): Promise<this> {
+    if (credentials) {
+      this.binaryPath = credentials.binaryPath ?? 'imsg'
+      this.region = credentials.region
+      return this
+    }
+    const { IMessageCredentialManager } = await import('./credential-manager')
+    const resolved = await new IMessageCredentialManager().resolveAccount()
+    this.binaryPath = resolved?.binary_path ?? 'imsg'
+    this.region = resolved?.region
+    return this
+  }
+
+  async connect(): Promise<void> {
+    await this.rpc.start(this.binaryPath)
+    await this.rpc.request('chats.list', { limit: 1 })
+  }
+
+  async getVersion(): Promise<string | null> {
+    const result = await this.runner(this.binaryPath, ['--version'])
+    if (result.code !== 0) return null
+    return result.stdout.trim() || null
+  }
+
+  async getStatus(): Promise<IMessageStatus> {
+    let version: string | null = null
+    let fullDiskAccess = false
+    try {
+      version = await this.getVersion()
+    } catch {
+      version = null
+    }
+    try {
+      await this.rpc.request('chats.list', { limit: 1 })
+      fullDiskAccess = true
+    } catch {
+      fullDiskAccess = false
+    }
+    return {
+      imsg_version: version,
+      binary_path: this.binaryPath,
+      full_disk_access: fullDiskAccess,
+      automation: 'unknown',
+      bridge_available: false,
+    }
+  }
+
+  async listChats(limit = 25): Promise<IMessageChatSummary[]> {
+    const result = await this.rpc.request<{ chats: ImsgChat[] }>('chats.list', { limit })
+    return result.chats.map(summarizeChat)
+  }
+
+  async searchChats(query: string, limit = 25): Promise<IMessageChatSummary[]> {
+    const all = await this.listChats(Math.max(limit, 100))
+    const lower = query.toLowerCase()
+    return all
+      .filter((c) => c.name.toLowerCase().includes(lower) || (c.identifier ?? '').toLowerCase().includes(lower))
+      .slice(0, limit)
+  }
+
+  async getMessages(chatId: number, limit = 25, start?: string): Promise<IMessageMessageSummary[]> {
+    const result = await this.rpc.request<{ messages: ImsgMessage[] }>('messages.history', {
+      chat_id: chatId,
+      limit,
+      ...(start ? { start } : {}),
+    })
+    return result.messages.map(summarizeMessage).sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+  }
+
+  async sendMessage(target: SendTarget, text: string): Promise<IMessageMessageSummary> {
+    const params: Record<string, unknown> = { text }
+    if (target.chatId !== undefined) params.chat_id = target.chatId
+    else if (target.chatGuid) params.chat_guid = target.chatGuid
+    else if (target.chatIdentifier) params.chat_identifier = target.chatIdentifier
+    else if (target.to) params.to = target.to
+    else throw new IMessageError('A chat id, guid, or recipient is required to send.', 'chat_not_found')
+    if (this.region) params.region = this.region
+
+    const result = await this.rpc.request<{ ok?: boolean; guid?: string; id?: number; service?: string }>(
+      'send',
+      params,
+    )
+    return {
+      id: result.id ?? 0,
+      guid: result.guid ?? '',
+      chat_id: target.chatId ?? 0,
+      from: '',
+      is_outgoing: true,
+      timestamp: new Date().toISOString(),
+      text,
+    }
+  }
+
+  async sendReaction(chatId: number, reaction: string, messageGuid?: string): Promise<void> {
+    if (messageGuid) {
+      throw new IMessageError(
+        'Reacting to a specific message requires the imsg Private API bridge.',
+        'private_api_required',
+        { suggestion: 'Enable the bridge with "imsg launch" (requires SIP disabled).' },
+      )
+    }
+    if (!STANDARD_REACTIONS.has(reaction)) {
+      throw new IMessageError(
+        `Custom reactions require the imsg Private API bridge. Standard tapbacks: ${[...STANDARD_REACTIONS].join(', ')}.`,
+        'private_api_required',
+        { suggestion: 'Enable the bridge with "imsg launch" (requires SIP disabled).' },
+      )
+    }
+    const result = await this.runner(this.binaryPath, [
+      'react',
+      '--chat-id',
+      String(chatId),
+      '--reaction',
+      reaction,
+      '--json',
+    ])
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim() || 'Reaction failed.'
+      throw classifyImsgFailure(detail, 'send_failed')
+    }
+  }
+
+  async watch(
+    onMessage: (msg: IMessageMessageSummary) => void,
+    options: { chatId?: number; sinceRowId?: number; onError?: (msg: string) => void } = {},
+  ): Promise<() => Promise<void>> {
+    const params: Record<string, unknown> = { include_reactions: false }
+    if (options.chatId !== undefined) params.chat_id = options.chatId
+    if (options.sinceRowId !== undefined) params.since_rowid = options.sinceRowId
+
+    const subscription = await this.rpc.subscribe(
+      params,
+      (raw) => onMessage(summarizeMessage(raw as ImsgMessage)),
+      options.onError,
+    )
+    return async () => {
+      await this.rpc.unsubscribe(subscription)
+    }
+  }
+
+  async getProfile(): Promise<IMessageStatus> {
+    return this.getStatus()
+  }
+
+  async close(): Promise<void> {
+    this.rpc.close()
+  }
+}