agent-messenger 2.27.2 → 2.28.0

package/src/platforms/imessage/test-stub-imsg.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Test stub for the imsg binary. Behavior controlled by IMSG_STUB_MODE.
+// Modes: ok (default), fda_denied, send_fail
+const mode = process.env.IMSG_STUB_MODE || 'ok'
+const arg = process.argv[2]
+
+if (arg === '--version') {
+  if (mode === 'novers') {
+    process.exit(1)
+  }
+  process.stdout.write('0.11.1\n')
+  process.exit(0)
+}
+
+if (arg === 'react') {
+  if (mode === 'react_automation_denied') {
+    process.stderr.write('AppleScript error: Messages got an error: Not authorized to send Apple events\n')
+    process.exit(1)
+  }
+  if (mode === 'react_fail') {
+    process.stdout.write('error: could not react\n')
+    process.exit(1)
+  }
+  process.stdout.write(JSON.stringify({ success: true, chat_id: 42, reaction_type: 'love' }) + '\n')
+  process.exit(0)
+}
+
+if (arg === 'rpc') {
+  let buf = ''
+  process.stdin.on('data', (d) => {
+    buf += d
+    let i
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim()
+      buf = buf.slice(i + 1)
+      if (!line) continue
+      const req = JSON.parse(line)
+      const reply = (result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: req.id, result }) + '\n')
+      const fail = (code, message, data) =>
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: req.id, error: { code, message, data } }) + '\n')
+
+      if (req.method === 'chats.list') {
+        if (mode === 'fda_denied') {
+          fail(-32603, 'Internal error', 'Permission Error: Cannot access Messages database')
+        } else if (mode === 'connect_rpc_fail') {
+          fail(-32603, 'Internal error', 'some unexpected internal failure')
+        } else {
+          reply({
+            chats: [
+              {
+                id: 42,
+                name: 'Jane',
+                identifier: 'iMessage;-;+15551234567',
+                guid: 'iMessage;-;+15551234567',
+                service: 'iMessage',
+                is_group: false,
+                participants: ['+15551234567'],
+                last_message: {
+                  id: 1,
+                  chat_id: 42,
+                  guid: 'm1',
+                  sender: '+15551234567',
+                  is_from_me: false,
+                  text: 'hi',
+                  created_at: '2026-06-24T00:00:00.000Z',
+                },
+              },
+              {
+                id: 43,
+                name: 'Crew',
+                identifier: 'iMessage;+;chat99',
+                guid: 'iMessage;+;chat99',
+                service: 'iMessage',
+                is_group: true,
+                participants: ['+15551111111', '+15552222222'],
+              },
+            ],
+          })
+        }
+      } else if (req.method === 'messages.history') {
+        reply({
+          messages: [
+            {
+              id: 2,
+              chat_id: 42,
+              guid: 'm2',
+              sender: '',
+              is_from_me: true,
+              text: 'yo',
+              created_at: '2026-06-24T00:01:00.000Z',
+            },
+            {
+              id: 1,
+              chat_id: 42,
+              guid: 'm1',
+              sender: '+15551234567',
+              is_from_me: false,
+              text: 'hi',
+              created_at: '2026-06-24T00:00:00.000Z',
+            },
+          ],
+        })
+      } else if (req.method === 'send') {
+        if (mode === 'send_fail') {
+          fail(-32603, 'Internal error', 'Messages accepted the chat send but wrote an unjoined empty outgoing row')
+        } else if (mode === 'automation_denied') {
+          fail(
+            -32603,
+            'Internal error',
+            'AppleScript error: Messages got an error: Not authorized to send Apple events',
+          )
+        } else {
+          reply({ ok: true, id: 99, guid: 'sent-guid', service: 'iMessage' })
+        }
+      } else if (req.method === 'watch.subscribe') {
+        reply({ subscription: 1 })
+        setTimeout(
+          () =>
+            process.stdout.write(
+              JSON.stringify({
+                jsonrpc: '2.0',
+                method: 'message',
+                params: {
+                  subscription: 1,
+                  message: {
+                    id: 3,
+                    chat_id: 42,
+                    guid: 'm3',
+                    sender: '+15551234567',
+                    is_from_me: false,
+                    text: 'new!',
+                    created_at: '2026-06-24T00:02:00.000Z',
+                  },
+                },
+              }) + '\n',
+            ),
+          30,
+        )
+      } else if (req.method === 'watch.unsubscribe') {
+        reply({ ok: true })
+      } else {
+        fail(-32601, 'Method not found')
+      }
+    }
+  })
+  process.stdin.on('end', () => process.exit(0))
+}

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'bun:test'
+
+import { createAccountId, IMessageError, type IMessageErrorCode } from './types'
+
+describe('createAccountId', () => {
+  it('slugifies deterministically and is filesystem-safe', () => {
+    expect(createAccountId('/opt/homebrew/bin/imsg')).toBe(createAccountId('/opt/homebrew/bin/imsg'))
+    expect(createAccountId('My Mac')).toBe('my-mac')
+  })
+
+  it('falls back to default for empty input', () => {
+    expect(createAccountId('   ')).toBe('default')
+  })
+})
+
+describe('IMessageError', () => {
+  const codes: IMessageErrorCode[] = [
+    'imsg_not_found',
+    'full_disk_access',
+    'automation_denied',
+    'rpc_error',
+    'send_failed',
+    'not_authenticated',
+    'invalid_limit',
+    'chat_not_found',
+    'private_api_required',
+    'imessage_error',
+  ]
+
+  it('is instantiable with every code and exposes .code', () => {
+    for (const code of codes) {
+      const err = new IMessageError('m', code)
+      expect(err.code).toBe(code)
+      expect(err).toBeInstanceOf(Error)
+    }
+  })
+
+  it('toJSON includes suggestion/doctorCommand only when present', () => {
+    expect(new IMessageError('m', 'rpc_error').toJSON()).toEqual({ error: 'm', code: 'rpc_error' })
+    expect(new IMessageError('m', 'imsg_not_found', { suggestion: 's', doctorCommand: 'd' }).toJSON()).toEqual({
+      error: 'm',
+      code: 'imsg_not_found',
+      suggestion: 's',
+      doctorCommand: 'd',
+    })
+  })
+})

package/src/platforms/imessage/types.ts

@@ -0,0 +1,95 @@
+export type IMessageProvider = 'imsg'
+
+export interface IMessageAccount {
+  account_id: string
+  provider: IMessageProvider
+  label?: string
+  binary_path?: string
+  region?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface IMessageConfig {
+  current: string | null
+  accounts: Record<string, IMessageAccount>
+}
+
+export interface IMessageChatSummary {
+  id: number
+  guid: string | null
+  identifier: string | null
+  name: string
+  service: string
+  is_group: boolean
+  participants: string[]
+  last_message?: IMessageMessageSummary
+}
+
+export interface IMessageMessageSummary {
+  id: number
+  guid: string
+  chat_id: number
+  from: string
+  from_name?: string
+  is_outgoing: boolean
+  timestamp: string
+  text?: string
+}
+
+export interface IMessageStatus {
+  imsg_version: string | null
+  binary_path: string
+  full_disk_access: boolean
+  automation: 'ok' | 'unknown' | 'denied'
+  bridge_available: boolean
+}
+
+export type IMessageErrorCode =
+  | 'imsg_not_found'
+  | 'full_disk_access'
+  | 'automation_denied'
+  | 'rpc_error'
+  | 'send_failed'
+  | 'not_authenticated'
+  | 'invalid_limit'
+  | 'chat_not_found'
+  | 'private_api_required'
+  | 'imessage_error'
+
+export class IMessageError extends Error {
+  code: IMessageErrorCode
+  suggestion?: string
+  doctorCommand?: string
+
+  constructor(
+    message: string,
+    code: IMessageErrorCode = 'imessage_error',
+    extra?: { suggestion?: string; doctorCommand?: string },
+  ) {
+    super(message)
+    this.name = 'IMessageError'
+    this.code = code
+    this.suggestion = extra?.suggestion
+    this.doctorCommand = extra?.doctorCommand
+  }
+
+  toJSON(): { error: string; code: IMessageErrorCode; suggestion?: string; doctorCommand?: string } {
+    return {
+      error: this.message,
+      code: this.code,
+      ...(this.suggestion ? { suggestion: this.suggestion } : {}),
+      ...(this.doctorCommand ? { doctorCommand: this.doctorCommand } : {}),
+    }
+  }
+}
+
+export function createAccountId(input: string): string {
+  const normalized = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized || 'default'
+}

package/src/platforms/instagram/client.ts

@@ -298,6 +298,24 @@ export class InstagramClient {
     return threads.map((t) => this.mapThread(t))
   }
 
+  async fetchIrisBootstrap(): Promise<{ seqId: number; snapshotAtMs: number }> {
+    this.ensureSession()
+    const { data } = await this.request('GET', '/direct_v2/inbox/?limit=1')
+
+    if (data['status'] !== 'ok') {
+      throw new InstagramError('Failed to fetch iris bootstrap', 'inbox_error')
+    }
+
+    const seqId = data['seq_id'] as number | undefined
+    const snapshotAtMs = data['snapshot_at_ms'] as number | undefined
+
+    if (typeof seqId !== 'number' || typeof snapshotAtMs !== 'number') {
+      throw new InstagramError('Iris bootstrap missing seq_id or snapshot_at_ms', 'iris_bootstrap_missing')
+    }
+
+    return { seqId, snapshotAtMs }
+  }
+
   async searchChats(query: string, limit = 20): Promise<InstagramChatSummary[]> {
     const allChats = await this.listChats(Math.max(limit, 50))
     const lower = query.toLowerCase()
@@ -405,6 +423,11 @@ export class InstagramClient {
     return this.userId
   }
 
+  getSessionState(): InstagramSessionState {
+    this.ensureSession()
+    return this.session!
+  }
+
   async getProfile(): Promise<{
     user_id: string
     username: string

package/src/platforms/instagram/hybrid-listener.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it, mock } from 'bun:test'
+import { EventEmitter } from 'node:events'
+
+import { InstagramHybridListener } from '@/platforms/instagram/hybrid-listener'
+import type { InstagramRealtimeListener } from '@/platforms/instagram/realtime-listener'
+
+function makeRealtimeFailingClient() {
+  return {
+    getUserId: () => '123',
+    getSessionState: () => {
+      throw new Error('realtime bootstrap failed')
+    },
+    fetchIrisBootstrap: async () => {
+      throw new Error('realtime bootstrap failed')
+    },
+    listChats: mock(async () => []),
+  } as never
+}
+
+class FakeRealtimeListener {
+  private emitter = new EventEmitter()
+  stopped = false
+
+  on(event: string, handler: (...args: unknown[]) => void) {
+    this.emitter.on(event, handler)
+    return this
+  }
+  off() {
+    return this
+  }
+  once() {
+    return this
+  }
+  async start() {
+    this.emitter.emit('connected', { userId: '123' })
+  }
+  stop() {
+    this.stopped = true
+    this.emitter.emit('disconnected')
+  }
+  fail() {
+    this.emitter.emit('error', new Error('realtime connection lost'))
+  }
+}
+
+class TestableHybridListener extends InstagramHybridListener {
+  lastFake: FakeRealtimeListener | null = null
+  protected override createRealtimeListener(): InstagramRealtimeListener {
+    const fake = new FakeRealtimeListener()
+    this.lastFake = fake
+    return fake as unknown as InstagramRealtimeListener
+  }
+}
+
+describe('InstagramHybridListener', () => {
+  let listener: InstagramHybridListener
+
+  afterEach(() => {
+    listener?.stop()
+  })
+
+  it('falls back to polling and emits a single error when realtime startup fails', async () => {
+    const client = makeRealtimeFailingClient()
+    listener = new InstagramHybridListener(client, {
+      pollInterval: 60_000,
+      realtimeRetryBaseMs: 60_000,
+      realtimeRetryMaxMs: 60_000,
+    })
+
+    const errors: Error[] = []
+    listener.on('error', (err) => errors.push(err))
+
+    const connected = new Promise<{ userId: string; transport: string }>((resolve) => {
+      listener.on('connected', resolve)
+    })
+
+    await listener.start()
+    const info = await connected
+
+    // given a realtime failure, when startup fails, then it falls back to polling
+    expect(info.transport).toBe('polling')
+    // and the failure is reported exactly once (no recursive re-entry)
+    expect(errors).toHaveLength(1)
+  })
+
+  it('falls back to polling exactly once when a connected realtime listener fails', async () => {
+    const client = {
+      getUserId: () => '123',
+      listChats: mock(async () => []),
+    } as never
+    const testable = new TestableHybridListener(client, {
+      pollInterval: 60_000,
+      realtimeRetryBaseMs: 60_000,
+      realtimeRetryMaxMs: 60_000,
+    })
+    listener = testable
+
+    const errors: Error[] = []
+    const transports: string[] = []
+    testable.on('error', (err) => errors.push(err))
+    testable.on('connected', ({ transport }) => transports.push(transport))
+
+    await testable.start()
+    // given an established realtime connection
+    expect(transports).toContain('realtime')
+
+    const pollingConnected = new Promise<void>((resolve) => {
+      testable.on('connected', ({ transport }) => {
+        if (transport === 'polling') resolve()
+      })
+    })
+
+    // when the connected realtime listener fails
+    testable.lastFake!.fail()
+    await pollingConnected
+
+    // then the failure is reported once and it falls back to polling without recursion
+    expect(errors).toHaveLength(1)
+    expect(transports.filter((t) => t === 'polling')).toHaveLength(1)
+  })
+
+  it('uses polling directly when realtime is disabled', async () => {
+    const client = makeRealtimeFailingClient()
+    listener = new InstagramHybridListener(client, { pollInterval: 60_000, disableRealtime: true })
+
+    const connected = new Promise<{ transport: string }>((resolve) => {
+      listener.on('connected', resolve)
+    })
+
+    await listener.start()
+    const info = await connected
+
+    expect(info.transport).toBe('polling')
+  })
+})

package/src/platforms/instagram/hybrid-listener.ts

@@ -0,0 +1,196 @@
+import { EventEmitter } from 'node:events'
+
+import type { InstagramClient } from './client'
+import { InstagramListener } from './listener'
+import { InstagramRealtimeListener } from './realtime-listener'
+import type { InstagramMessageSummary } from './types'
+
+export interface InstagramHybridListenerEventMap {
+  message: [InstagramMessageSummary]
+  error: [Error]
+  connected: [{ userId: string; transport: 'realtime' | 'polling' }]
+  disconnected: []
+}
+
+type EventKey = keyof InstagramHybridListenerEventMap
+
+const DEFAULT_REALTIME_RETRY_BASE_MS = 30_000
+const DEFAULT_REALTIME_RETRY_MAX_MS = 5 * 60_000
+
+export interface InstagramHybridListenerOptions {
+  pollInterval?: number
+  realtimeRetryBaseMs?: number
+  realtimeRetryMaxMs?: number
+  disableRealtime?: boolean
+  connackTimeoutMs?: number
+}
+
+export class InstagramHybridListener {
+  private client: InstagramClient
+  private emitter = new EventEmitter()
+  private realtime: InstagramRealtimeListener | null = null
+  private poller: InstagramListener | null = null
+  private options: Required<
+    Pick<InstagramHybridListenerOptions, 'realtimeRetryBaseMs' | 'realtimeRetryMaxMs' | 'disableRealtime'>
+  > &
+    Pick<InstagramHybridListenerOptions, 'pollInterval' | 'connackTimeoutMs'>
+  private running = false
+  private realtimeRetryTimer: ReturnType<typeof setTimeout> | null = null
+  private realtimeFailures = 0
+  private activeTransport: 'realtime' | 'polling' | null = null
+  private tearingDownRealtime = false
+
+  constructor(client: InstagramClient, options: InstagramHybridListenerOptions = {}) {
+    this.client = client
+    this.options = {
+      pollInterval: options.pollInterval,
+      realtimeRetryBaseMs: options.realtimeRetryBaseMs ?? DEFAULT_REALTIME_RETRY_BASE_MS,
+      realtimeRetryMaxMs: options.realtimeRetryMaxMs ?? DEFAULT_REALTIME_RETRY_MAX_MS,
+      disableRealtime: options.disableRealtime ?? false,
+      connackTimeoutMs: options.connackTimeoutMs,
+    }
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    this.running = true
+
+    if (this.options.disableRealtime) {
+      this.startPolling()
+      return
+    }
+
+    await this.tryRealtime()
+  }
+
+  stop(): void {
+    this.running = false
+    this.activeTransport = null
+    this.clearRealtimeRetry()
+    this.teardownRealtime()
+    this.teardownPolling()
+    this.emitter.emit('disconnected')
+  }
+
+  on<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.on(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  off<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.off(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  once<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.once(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  protected createRealtimeListener(): InstagramRealtimeListener {
+    return new InstagramRealtimeListener(this.client, { connackTimeoutMs: this.options.connackTimeoutMs })
+  }
+
+  private async tryRealtime(): Promise<void> {
+    const realtime = this.createRealtimeListener()
+    this.realtime = realtime
+
+    realtime.on('message', (message) => this.emitter.emit('message', message))
+    realtime.on('connected', ({ userId }) => {
+      this.realtimeFailures = 0
+      this.activeTransport = 'realtime'
+      this.teardownPolling()
+      this.emitter.emit('connected', { userId, transport: 'realtime' })
+    })
+    realtime.on('error', (error) => this.onRealtimeFailure(error))
+    realtime.on('disconnected', () => {
+      // Ignore the 'disconnected' that our own teardown triggers; only an
+      // unexpected close (still marked realtime-active) is a real failure.
+      if (this.tearingDownRealtime) return
+      if (this.running && this.activeTransport === 'realtime') {
+        this.onRealtimeFailure(new Error('Realtime connection closed'))
+      }
+    })
+
+    try {
+      await realtime.start()
+      // stop() may have run during the bootstrap await; if so, don't leave an MQTT
+      // connection alive after the hybrid listener was already torn down.
+      if (!this.running) {
+        realtime.stop()
+        if (this.realtime === realtime) this.realtime = null
+      }
+    } catch (error) {
+      this.onRealtimeFailure(error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+
+  private onRealtimeFailure(error: Error): void {
+    if (!this.running) return
+
+    this.activeTransport = null
+    this.emitter.emit('error', error)
+    this.realtimeFailures++
+    // teardownRealtime() suppresses the 'disconnected' it triggers, so this path
+    // does not re-enter via the realtime disconnected handler.
+    this.teardownRealtime()
+    this.startPolling()
+    this.scheduleRealtimeRetry()
+  }
+
+  private scheduleRealtimeRetry(): void {
+    if (!this.running || this.realtimeRetryTimer) return
+
+    const delay = Math.min(
+      this.options.realtimeRetryBaseMs * 2 ** (this.realtimeFailures - 1),
+      this.options.realtimeRetryMaxMs,
+    )
+
+    this.realtimeRetryTimer = setTimeout(() => {
+      this.realtimeRetryTimer = null
+      if (this.running) void this.tryRealtime()
+    }, delay)
+  }
+
+  private startPolling(): void {
+    if (this.poller) return
+
+    const poller = new InstagramListener(this.client, { pollInterval: this.options.pollInterval })
+    this.poller = poller
+
+    poller.on('message', (message) => this.emitter.emit('message', message))
+    poller.on('error', (error) => this.emitter.emit('error', error))
+    poller.on('connected', ({ userId }) => {
+      this.activeTransport = 'polling'
+      this.emitter.emit('connected', { userId, transport: 'polling' })
+    })
+
+    void poller.start()
+  }
+
+  private teardownRealtime(): void {
+    if (this.realtime) {
+      this.tearingDownRealtime = true
+      try {
+        this.realtime.stop()
+      } finally {
+        this.tearingDownRealtime = false
+      }
+      this.realtime = null
+    }
+  }
+
+  private teardownPolling(): void {
+    if (this.poller) {
+      this.poller.stop()
+      this.poller = null
+    }
+  }
+
+  private clearRealtimeRetry(): void {
+    if (this.realtimeRetryTimer) {
+      clearTimeout(this.realtimeRetryTimer)
+      this.realtimeRetryTimer = null
+    }
+  }
+}

package/src/platforms/instagram/index.ts

@@ -1,6 +1,16 @@
 export { InstagramClient } from './client'
 export { InstagramCredentialManager } from './credential-manager'
+export {
+  InstagramHybridListener,
+  type InstagramHybridListenerEventMap,
+  type InstagramHybridListenerOptions,
+} from './hybrid-listener'
 export { InstagramListener, type InstagramListenerEventMap } from './listener'
+export {
+  InstagramRealtimeListener,
+  type InstagramRealtimeListenerEventMap,
+  type InstagramRealtimeListenerOptions,
+} from './realtime-listener'
 export { InstagramTokenExtractor, type ExtractedInstagramCookies } from './token-extractor'
 export {
   createAccountId,