agent-messenger 2.27.1 → 2.28.0

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

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'bun:test'
+
+import * as imessage from './index'
+
+describe('imessage SDK barrel', () => {
+  it('exports client, rpc, credential manager, error, helper', () => {
+    expect(typeof imessage.ImsgClient).toBe('function')
+    expect(typeof imessage.ImsgRpc).toBe('function')
+    expect(typeof imessage.IMessageCredentialManager).toBe('function')
+    expect(typeof imessage.IMessageError).toBe('function')
+    expect(typeof imessage.createAccountId).toBe('function')
+  })
+})

package/src/platforms/imessage/index.ts

@@ -0,0 +1,16 @@
+export { ImsgClient } from './client'
+export type { OneShotRunner } from './client'
+export { ImsgRpc } from './rpc'
+export { IMessageCredentialManager } from './credential-manager'
+export type { ResolvedAccount } from './credential-manager'
+export {
+  createAccountId,
+  IMessageError,
+  type IMessageAccount,
+  type IMessageChatSummary,
+  type IMessageConfig,
+  type IMessageErrorCode,
+  type IMessageMessageSummary,
+  type IMessageProvider,
+  type IMessageStatus,
+} from './types'

package/src/platforms/imessage/rpc.ts

@@ -0,0 +1,157 @@
+import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process'
+import { createInterface, type Interface } from 'node:readline'
+
+import { classifyImsgFailure } from './errors'
+import { IMessageError } from './types'
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id?: string | number
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+  method?: string
+  params?: { subscription?: number; message?: unknown; error?: { message?: string } }
+}
+
+type Pending = { resolve: (value: unknown) => void; reject: (err: Error) => void }
+type MessageHandler = (message: unknown) => void
+type ErrorHandler = (message: string) => void
+
+function normalizeRpcError(error: { code: number; message: string; data?: unknown }): IMessageError {
+  const detail = typeof error.data === 'string' ? error.data : error.message
+  const text = `${error.message}${typeof error.data === 'string' ? `: ${error.data}` : ''}`
+  return classifyImsgFailure(detail.length > 0 ? `${detail} ${text}` : text, 'rpc_error')
+}
+
+export class ImsgRpc {
+  private child: ChildProcessWithoutNullStreams | null = null
+  private reader: Interface | null = null
+  private nextId = 1
+  private pending = new Map<string | number, Pending>()
+  private subscriptions = new Map<number, { onMessage: MessageHandler; onError?: ErrorHandler }>()
+  private stderrBuffer = ''
+
+  async start(binaryPath = 'imsg'): Promise<void> {
+    if (this.child) return
+
+    const child = await new Promise<ChildProcessWithoutNullStreams>((resolve, reject) => {
+      let proc: ChildProcessWithoutNullStreams
+      try {
+        proc = spawn(binaryPath, ['rpc'], { stdio: ['pipe', 'pipe', 'pipe'] })
+      } catch {
+        reject(this.spawnError(binaryPath))
+        return
+      }
+      proc.once('error', (err: NodeJS.ErrnoException) => {
+        reject(err.code === 'ENOENT' ? this.spawnError(binaryPath) : err)
+      })
+      proc.once('spawn', () => resolve(proc))
+    })
+
+    this.child = child
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => {
+      this.stderrBuffer = (this.stderrBuffer + chunk).slice(-4096)
+    })
+
+    this.reader = createInterface({ input: child.stdout })
+    this.reader.on('line', (line: string) => this.handleLine(line))
+
+    child.once('exit', () => this.handleExit())
+  }
+
+  private spawnError(binaryPath: string): IMessageError {
+    return new IMessageError(`Could not run "${binaryPath}".`, 'imsg_not_found', {
+      suggestion: 'Install imsg: "brew install steipete/tap/imsg", or set --bin / AGENT_IMESSAGE_BIN.',
+      doctorCommand: 'agent-imessage doctor',
+    })
+  }
+
+  private handleLine(line: string): void {
+    const trimmed = line.trim()
+    if (!trimmed) return
+
+    let frame: JsonRpcResponse
+    try {
+      frame = JSON.parse(trimmed) as JsonRpcResponse
+    } catch {
+      return
+    }
+
+    if (frame.method === 'message' && frame.params?.subscription !== undefined) {
+      this.subscriptions.get(frame.params.subscription)?.onMessage(frame.params.message)
+      return
+    }
+    if (frame.method === 'error' && frame.params?.subscription !== undefined) {
+      this.subscriptions.get(frame.params.subscription)?.onError?.(frame.params.error?.message ?? 'watch error')
+      return
+    }
+
+    if (frame.id === undefined) return
+    const pending = this.pending.get(frame.id)
+    if (!pending) return
+    this.pending.delete(frame.id)
+
+    if (frame.error) {
+      pending.reject(normalizeRpcError(frame.error))
+    } else {
+      pending.resolve(frame.result)
+    }
+  }
+
+  private handleExit(): void {
+    const err = new IMessageError(
+      `imsg rpc process exited.${this.stderrBuffer ? ` ${this.stderrBuffer.trim()}` : ''}`,
+      'rpc_error',
+    )
+    for (const pending of this.pending.values()) pending.reject(err)
+    this.pending.clear()
+    this.child = null
+    this.reader?.close()
+    this.reader = null
+  }
+
+  async request<T>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    if (!this.child) throw new IMessageError('imsg rpc is not running. Call start() first.', 'rpc_error')
+    const id = this.nextId++
+    const frame = `${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`
+
+    return await new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject })
+      this.child!.stdin.write(frame, (err) => {
+        if (err) {
+          this.pending.delete(id)
+          reject(err)
+        }
+      })
+    })
+  }
+
+  async subscribe(params: Record<string, unknown>, onMessage: MessageHandler, onError?: ErrorHandler): Promise<number> {
+    const result = await this.request<{ subscription: number }>('watch.subscribe', params)
+    this.subscriptions.set(result.subscription, { onMessage, onError })
+    return result.subscription
+  }
+
+  async unsubscribe(subscription: number): Promise<void> {
+    this.subscriptions.delete(subscription)
+    try {
+      await this.request('watch.unsubscribe', { subscription })
+    } catch {
+      this.subscriptions.delete(subscription)
+    }
+  }
+
+  close(): void {
+    const err = new IMessageError('imsg rpc connection closed.', 'rpc_error')
+    for (const pending of this.pending.values()) pending.reject(err)
+    this.pending.clear()
+    this.subscriptions.clear()
+    if (this.child) {
+      this.child.stdin.end()
+      this.child = null
+    }
+    this.reader?.close()
+    this.reader = null
+  }
+}

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')
+  })
+})