agent-messenger 2.27.2 → 2.28.0

package/src/platforms/imessage/commands/auth.ts

@@ -0,0 +1,142 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { IMessageCredentialManager } from '../credential-manager'
+import { createAccountId } from '../types'
+
+async function guard(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn()
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+interface SetOptions {
+  bin?: string
+  region?: string
+  account?: string
+  label?: string
+  current?: boolean
+  pretty?: boolean
+  _manager?: IMessageCredentialManager
+}
+
+async function runSet(options: SetOptions): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const now = new Date().toISOString()
+  const accountId = createAccountId(options.account ?? options.label ?? options.bin ?? 'default')
+
+  await manager.setAccount({
+    account_id: accountId,
+    provider: 'imsg',
+    label: options.label,
+    binary_path: options.bin,
+    region: options.region,
+    created_at: now,
+    updated_at: now,
+  })
+  if (options.current) await manager.setCurrent(accountId)
+
+  console.log(
+    formatOutput({ success: true, account_id: accountId, binary_path: options.bin ?? 'imsg' }, options.pretty),
+  )
+  process.exit(0)
+}
+
+async function runList(options: { pretty?: boolean; _manager?: IMessageCredentialManager }): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const accounts = await manager.listAccounts()
+  console.log(
+    formatOutput(
+      accounts.map((a) => ({
+        account_id: a.account_id,
+        label: a.label,
+        binary_path: a.binary_path ?? 'imsg',
+        region: a.region,
+        is_current: a.is_current,
+      })),
+      options.pretty,
+    ),
+  )
+  process.exit(0)
+}
+
+async function runUse(
+  accountId: string,
+  options: { pretty?: boolean; _manager?: IMessageCredentialManager },
+): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const found = await manager.setCurrent(accountId)
+  if (!found) {
+    console.log(formatOutput({ error: `Account "${accountId}" not found. Run "auth list".` }, options.pretty))
+    process.exit(1)
+  }
+  console.log(formatOutput({ success: true, account_id: createAccountId(accountId) }, options.pretty))
+  process.exit(0)
+}
+
+async function runRemove(
+  accountId: string,
+  options: { pretty?: boolean; _manager?: IMessageCredentialManager },
+): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const removed = await manager.removeAccount(accountId)
+  if (!removed) {
+    console.log(formatOutput({ error: `Account "${accountId}" not found. Run "auth list".` }, options.pretty))
+    process.exit(1)
+  }
+  console.log(formatOutput({ success: true }, options.pretty))
+  process.exit(0)
+}
+
+async function runLogout(options: { pretty?: boolean; _manager?: IMessageCredentialManager }): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  await manager.clearCredentials()
+  console.log(formatOutput({ success: true }, options.pretty))
+  process.exit(0)
+}
+
+export const authCommand = new Command('auth')
+  .description('Account configuration commands')
+  .addCommand(
+    new Command('set')
+      .description('Configure an iMessage account (imsg binary path / region)')
+      .option('--bin <path>', 'Path to the imsg binary (default: imsg on PATH)')
+      .option('--region <code>', 'Default region for local-format phone numbers (e.g. US)')
+      .option('--account <id>', 'Account id/alias')
+      .option('--label <label>', 'Human-friendly label')
+      .option('--current', 'Set as the active account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: SetOptions) => guard(() => runSet(opts))),
+  )
+  .addCommand(
+    new Command('list')
+      .description('List configured accounts')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: { pretty?: boolean }) => guard(() => runList(opts))),
+  )
+  .addCommand(
+    new Command('use')
+      .description('Switch the active account')
+      .argument('<account-id>', 'Account id')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (accountId: string, opts: { pretty?: boolean }) => guard(() => runUse(accountId, opts))),
+  )
+  .addCommand(
+    new Command('remove')
+      .description('Remove a configured account')
+      .argument('<account-id>', 'Account id')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (accountId: string, opts: { pretty?: boolean }) => guard(() => runRemove(accountId, opts))),
+  )
+  .addCommand(
+    new Command('logout')
+      .description('Clear all stored accounts')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: { pretty?: boolean }) => guard(() => runLogout(opts))),
+  )
+
+export { runSet, runList, runUse, runRemove, runLogout }

package/src/platforms/imessage/commands/chat.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { parseLimitOption, withImsgClient } from './shared'
+
+async function listAction(options: { account?: string; pretty?: boolean; limit?: string }): Promise<void> {
+  try {
+    const limit = parseLimitOption(options.limit, 25)
+    const chats = await withImsgClient(options, (client) => client.listChats(limit))
+    console.log(formatOutput(chats, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+async function searchAction(
+  query: string,
+  options: { account?: string; pretty?: boolean; limit?: string },
+): Promise<void> {
+  try {
+    const limit = parseLimitOption(options.limit, 25)
+    const chats = await withImsgClient(options, (client) => client.searchChats(query, limit))
+    console.log(formatOutput(chats, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+export const chatCommand = new Command('chat')
+  .description('iMessage chat commands')
+  .addCommand(
+    new Command('list')
+      .description('List chats')
+      .option('--limit <n>', 'Number of chats to fetch', '25')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(listAction),
+  )
+  .addCommand(
+    new Command('search')
+      .description('Search chats by name or identifier')
+      .argument('<query>', 'Search query')
+      .option('--limit <n>', 'Number of results to return', '25')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(searchAction),
+  )

package/src/platforms/imessage/commands/doctor.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { join } from 'node:path'
+
+import { runDoctor } from './doctor'
+
+const STUB = join(import.meta.dir, '..', 'test-stub-imsg.mjs')
+const saved: Record<string, string | undefined> = {}
+
+function setMode(mode: string, bin = STUB): void {
+  saved.IMSG_STUB_MODE = process.env.IMSG_STUB_MODE
+  saved.AGENT_IMESSAGE_BIN = process.env.AGENT_IMESSAGE_BIN
+  process.env.IMSG_STUB_MODE = mode
+  process.env.AGENT_IMESSAGE_BIN = bin
+}
+
+afterEach(() => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k]
+    else process.env[k] = v
+  }
+})
+
+describe('runDoctor', () => {
+  it('reports imsg_not_found when the binary is missing', async () => {
+    setMode('ok', '/nonexistent/imsg-xyz')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.code).toBe('imsg_not_found')
+    expect(report.suggestion).toContain('brew install')
+  })
+
+  it('reports full_disk_access denied with Settings guidance', async () => {
+    setMode('fda_denied')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.full_disk_access).toBe('denied')
+    expect(report.code).toBe('full_disk_access')
+    expect(report.suggestion).toContain('Full Disk Access')
+  })
+
+  it('reports healthy with version, FDA ok, and bridge note', async () => {
+    setMode('ok')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(true)
+    expect(report.imsg).toBe('found')
+    expect(report.imsg_version).toBe('0.11.1')
+    expect(report.full_disk_access).toBe('ok')
+    expect(report.bridge).toBe('disabled')
+    expect(report.warnings.some((w) => w.includes('Private API bridge'))).toBe(true)
+  })
+
+  it('does not mislabel a non-FDA connect failure as Full Disk Access denied', async () => {
+    setMode('connect_rpc_fail')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.full_disk_access).toBe('unknown')
+    expect(report.code).toBe('rpc_error')
+  })
+
+  it('honors an explicit --bin override (verifies the supplied binary, not the default)', async () => {
+    setMode('ok', '/nonexistent/default-imsg')
+    const report = await runDoctor({ bin: STUB })
+    expect(report.ok).toBe(true)
+    expect(report.binary_path).toBe(STUB)
+  })
+
+  it('fails on an invalid --bin even when the default/env binary is valid', async () => {
+    setMode('ok', STUB)
+    const report = await runDoctor({ bin: '/nonexistent/custom-imsg' })
+    expect(report.ok).toBe(false)
+    expect(report.code).toBe('imsg_not_found')
+    expect(report.binary_path).toBe('/nonexistent/custom-imsg')
+  })
+
+  it('runs a test-chat send when requested', async () => {
+    setMode('ok')
+    const report = await runDoctor({ testChat: 42 })
+    expect(report.test_chat).toBe('sent')
+  })
+})

package/src/platforms/imessage/commands/doctor.ts

@@ -0,0 +1,139 @@
+import { Command } from 'commander'
+
+import { formatOutput } from '@/shared/utils/output'
+
+import { ImsgClient } from '../client'
+import { IMessageCredentialManager } from '../credential-manager'
+import { IMessageError } from '../types'
+
+export interface DoctorReport {
+  ok: boolean
+  imsg: 'found' | 'missing'
+  imsg_version?: string | null
+  binary_path: string
+  full_disk_access: 'ok' | 'denied' | 'unknown'
+  automation: string
+  bridge: 'enabled' | 'disabled'
+  test_chat?: string
+  warnings: string[]
+  error?: string
+  code?: string
+  suggestion?: string
+}
+
+export async function runDoctor(options: {
+  account?: string
+  bin?: string
+  region?: string
+  testChat?: number
+  client?: ImsgClient
+}): Promise<DoctorReport> {
+  const resolved = await new IMessageCredentialManager().resolveAccount(options.account)
+  const binaryPath = options.bin ?? resolved?.binary_path ?? process.env.AGENT_IMESSAGE_BIN ?? 'imsg'
+  const region = options.region ?? resolved?.region
+
+  const client = options.client ?? new ImsgClient()
+  await client.login({ binaryPath, region })
+
+  const warnings: string[] = []
+
+  let version: string | null = null
+  let versionError: IMessageError | undefined
+  try {
+    version = await client.getVersion()
+  } catch (error) {
+    versionError = error as IMessageError
+  }
+
+  if (version === null) {
+    const code = versionError?.code ?? 'imsg_not_found'
+    return {
+      ok: false,
+      imsg: 'missing',
+      binary_path: binaryPath,
+      full_disk_access: 'unknown',
+      automation: 'unknown',
+      bridge: 'disabled',
+      warnings,
+      error: versionError?.message ?? `Could not run "${binaryPath} --version".`,
+      code,
+      suggestion:
+        versionError?.suggestion ??
+        (code === 'imsg_not_found' ? 'Install imsg: "brew install steipete/tap/imsg".' : undefined),
+    }
+  }
+
+  let connectError: IMessageError | undefined
+  try {
+    await client.connect()
+  } catch (error) {
+    connectError = error as IMessageError
+  }
+
+  if (connectError) {
+    await client.close()
+    const isFda = connectError.code === 'full_disk_access'
+    return {
+      ok: false,
+      imsg: 'found',
+      imsg_version: version,
+      binary_path: binaryPath,
+      full_disk_access: isFda ? 'denied' : 'unknown',
+      automation: 'unknown',
+      bridge: 'disabled',
+      warnings,
+      error: connectError.message,
+      code: connectError.code,
+      suggestion:
+        connectError.suggestion ??
+        (isFda
+          ? 'Grant Full Disk Access to the app/terminal launching agent-messenger (System Settings → Privacy & Security → Full Disk Access). macOS grants to the parent process.'
+          : undefined),
+    }
+  }
+
+  warnings.push(
+    'Automation (Messages) is verified on first send. If sends fail, grant Privacy → Automation → Messages.',
+  )
+  warnings.push(
+    'Private API bridge disabled — send/read/watch/standard tapbacks work; typing/edit/group mgmt need "imsg launch" (SIP off).',
+  )
+
+  let testChatResult: string | undefined
+  if (options.testChat !== undefined) {
+    try {
+      await client.sendMessage({ chatId: options.testChat }, 'agent-imessage doctor test message')
+      testChatResult = 'sent'
+    } catch (error) {
+      testChatResult = `failed: ${(error as Error).message}`
+    }
+  }
+
+  await client.close()
+
+  return {
+    ok: true,
+    imsg: 'found',
+    imsg_version: version,
+    binary_path: binaryPath,
+    full_disk_access: 'ok',
+    automation: 'unknown',
+    bridge: 'disabled',
+    test_chat: testChatResult,
+    warnings,
+  }
+}
+
+export const doctorCommand = new Command('doctor')
+  .description('Diagnose imsg availability and macOS permissions')
+  .option('--account <id>', 'Check a specific account (default: current)')
+  .option('--bin <path>', 'Check a specific imsg binary path')
+  .option('--region <code>', 'Default region for local-format phone numbers')
+  .option('--test-chat <chatId>', 'Send a test message to this chat id')
+  .option('--pretty', 'Pretty print JSON output')
+  .action(async (opts: { account?: string; bin?: string; region?: string; testChat?: string; pretty?: boolean }) => {
+    const testChat = opts.testChat && /^\d+$/.test(opts.testChat) ? Number.parseInt(opts.testChat, 10) : undefined
+    const report = await runDoctor({ account: opts.account, bin: opts.bin, region: opts.region, testChat })
+    console.log(formatOutput(report, opts.pretty))
+    process.exit(report.ok ? 0 : 1)
+  })

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

@@ -0,0 +1,6 @@
+export { authCommand } from './auth'
+export { chatCommand } from './chat'
+export { doctorCommand } from './doctor'
+export { messageCommand } from './message'
+export { setupCommand } from './setup'
+export { whoamiCommand } from './whoami'

package/src/platforms/imessage/commands/message.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'bun:test'
+
+import { IMessageError } from '../types'
+import { parseRowId } from './message'
+
+describe('parseRowId', () => {
+  it('parses a non-negative integer', () => {
+    expect(parseRowId('9000')).toBe(9000)
+    expect(parseRowId('0')).toBe(0)
+  })
+
+  it('returns undefined when absent', () => {
+    expect(parseRowId(undefined)).toBeUndefined()
+  })
+
+  it('rejects non-integers', () => {
+    expect(() => parseRowId('abc')).toThrow(IMessageError)
+    expect(() => parseRowId('-5')).toThrow(IMessageError)
+  })
+})

package/src/platforms/imessage/commands/message.ts

@@ -0,0 +1,151 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { IMessageError, type IMessageMessageSummary } from '../types'
+import { parseLimitOption, resolveChatId, resolveChatTarget, withImsgClient } from './shared'
+
+async function listAction(
+  chat: string,
+  options: { account?: string; pretty?: boolean; limit?: string; start?: string },
+): Promise<void> {
+  try {
+    const limit = parseLimitOption(options.limit, 25)
+    const messages = await withImsgClient(options, async (client) => {
+      const chatId = await resolveChatId(client, chat)
+      return client.getMessages(chatId, limit, options.start)
+    })
+    console.log(formatOutput(messages, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+async function sendAction(chat: string, text: string, options: { account?: string; pretty?: boolean }): Promise<void> {
+  try {
+    const message = await withImsgClient(options, (client) => client.sendMessage(resolveChatTarget(chat), text))
+    console.log(formatOutput(message, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+async function reactAction(
+  chat: string,
+  reaction: string,
+  options: { account?: string; pretty?: boolean },
+): Promise<void> {
+  try {
+    await withImsgClient(options, async (client) => {
+      const chatId = await resolveChatId(client, chat)
+      await client.sendReaction(chatId, reaction)
+    })
+    console.log(formatOutput({ success: true, chat, reaction }, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+function parseRowId(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  if (!/^\d+$/.test(raw.trim())) {
+    throw new IMessageError('--since-rowid must be a non-negative integer.', 'invalid_limit')
+  }
+  return Number.parseInt(raw.trim(), 10)
+}
+
+async function watchAction(options: {
+  account?: string
+  pretty?: boolean
+  chat?: string
+  sinceRowid?: string
+  jsonl?: boolean
+}): Promise<void> {
+  try {
+    const sinceRowId = parseRowId(options.sinceRowid)
+    await withImsgClient(options, async (client) => {
+      const chatId = options.chat && options.chat !== 'all' ? await resolveChatId(client, options.chat) : undefined
+      const seen = new Set<string>()
+      const SEEN_CAP = 2000
+      let running = true
+
+      const emit = (msg: IMessageMessageSummary): void => {
+        if (msg.guid) {
+          if (seen.has(msg.guid)) return
+          seen.add(msg.guid)
+          if (seen.size > SEEN_CAP) {
+            const oldest = seen.values().next().value
+            if (oldest !== undefined) seen.delete(oldest)
+          }
+        }
+        console.log(options.jsonl ? JSON.stringify(msg) : formatOutput(msg, options.pretty))
+      }
+
+      const stop = await client.watch(emit, {
+        chatId,
+        sinceRowId,
+        onError: (m) => console.error(JSON.stringify({ warning: m })),
+      })
+
+      await new Promise<void>((resolve) => {
+        const shutdown = (): void => {
+          if (!running) return
+          running = false
+          void stop().finally(resolve)
+        }
+        process.on('SIGINT', shutdown)
+        process.on('SIGTERM', shutdown)
+      })
+    })
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+export const messageCommand = new Command('message')
+  .description('iMessage message commands')
+  .addCommand(
+    new Command('list')
+      .description('List messages from a chat')
+      .argument('<chat>', 'Chat id, guid, or identifier')
+      .option('--limit <n>', 'Number of messages to fetch', '25')
+      .option('--start <iso>', 'Only messages on/after this ISO timestamp')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(listAction),
+  )
+  .addCommand(
+    new Command('send')
+      .description('Send a text message to a chat or recipient')
+      .argument('<chat>', 'Chat id/guid, or a phone/email recipient')
+      .argument('<text>', 'Message text')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(sendAction),
+  )
+  .addCommand(
+    new Command('react')
+      .description('React to the most recent incoming message in a chat (standard tapbacks)')
+      .argument('<chat>', 'Chat id, guid, or identifier')
+      .argument('<reaction>', 'love | like | dislike | laugh | emphasis | question')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(reactAction),
+  )
+  .addCommand(
+    new Command('watch')
+      .description('Stream new messages via imsg (resumable with --since-rowid)')
+      .option('--chat <ref|all>', 'Watch a specific chat or "all"', 'all')
+      .option('--since-rowid <n>', 'Replay messages after this message rowid, then stream live')
+      .option('--jsonl', 'Emit one JSON object per line')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(watchAction),
+  )
+
+export { parseRowId }

package/src/platforms/imessage/commands/setup.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { existsSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { IMessageCredentialManager } from '../credential-manager'
+import { performSetup } from './setup'
+
+const STUB = join(import.meta.dir, '..', 'test-stub-imsg.mjs')
+const testDirs: string[] = []
+const saved: Record<string, string | undefined> = {}
+
+function freshManager(): { manager: IMessageCredentialManager; dir: string } {
+  const dir = join(import.meta.dir, `.test-setup-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  testDirs.push(dir)
+  return { manager: new IMessageCredentialManager(dir), dir }
+}
+
+function setEnv(bin?: string): void {
+  saved.IMSG_STUB_MODE = process.env.IMSG_STUB_MODE
+  saved.AGENT_IMESSAGE_BIN = process.env.AGENT_IMESSAGE_BIN
+  process.env.IMSG_STUB_MODE = 'ok'
+  if (bin === undefined) delete process.env.AGENT_IMESSAGE_BIN
+  else process.env.AGENT_IMESSAGE_BIN = bin
+}
+
+afterEach(() => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k]
+    else process.env[k] = v
+  }
+  for (const dir of testDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+describe('performSetup', () => {
+  it('saves the account when the supplied --bin verifies', async () => {
+    setEnv()
+    const { manager, dir } = freshManager()
+    const result = await performSetup({ bin: STUB, manager })
+    expect(result.ok).toBe(true)
+    expect(existsSync(join(dir, 'imessage-credentials.json'))).toBe(true)
+    expect((await manager.resolveAccount())?.binary_path).toBe(STUB)
+  })
+
+  it('does NOT persist an account when an invalid --bin fails, even if the default binary is valid', async () => {
+    setEnv(STUB)
+    const { manager, dir } = freshManager()
+    const result = await performSetup({ bin: '/nonexistent/custom-imsg', manager })
+    expect(result.ok).toBe(false)
+    expect(result.report.code).toBe('imsg_not_found')
+    expect(existsSync(join(dir, 'imessage-credentials.json'))).toBe(false)
+  })
+})