agent-messenger 2.27.1 → 2.28.0

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

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

@@ -0,0 +1,76 @@
+import { Command } from 'commander'
+
+import { formatOutput } from '@/shared/utils/output'
+
+import { IMessageCredentialManager } from '../credential-manager'
+import { createAccountId } from '../types'
+import { runDoctor } from './doctor'
+
+const CHECKLIST = `iMessage runs on THIS Mac through the "imsg" tool. One-time setup:
+  1. Install imsg:  brew install steipete/tap/imsg
+  2. Sign Messages.app into your Apple ID (a dedicated Apple ID is recommended).
+  3. Grant Full Disk Access to the app/terminal that launches agent-messenger
+     (System Settings > Privacy & Security > Full Disk Access). macOS grants to the parent process.
+  4. Grant Automation > Messages when first prompted (needed to send).
+
+Basic send / read / watch / standard tapbacks need NO SIP changes.
+Typing, edit/unsend, group management need "imsg launch" (SIP disabled) — a later tier.`
+
+export async function performSetup(options: {
+  bin?: string
+  region?: string
+  manager?: IMessageCredentialManager
+}): Promise<{ ok: boolean; report: Awaited<ReturnType<typeof runDoctor>>; account_id?: string }> {
+  const report = await runDoctor({ bin: options.bin, region: options.region })
+  if (!report.ok) {
+    return { ok: false, report }
+  }
+
+  const manager = options.manager ?? new IMessageCredentialManager()
+  const now = new Date().toISOString()
+  const accountId = createAccountId(options.bin ?? 'default')
+  await manager.setAccount({
+    account_id: accountId,
+    provider: 'imsg',
+    binary_path: options.bin,
+    region: options.region,
+    created_at: now,
+    updated_at: now,
+  })
+  await manager.setCurrent(accountId)
+
+  return { ok: true, report, account_id: accountId }
+}
+
+async function runSetup(options: { bin?: string; region?: string; pretty?: boolean }): Promise<void> {
+  console.error(CHECKLIST)
+  console.error('')
+
+  const result = await performSetup({ bin: options.bin, region: options.region })
+  if (!result.ok) {
+    console.log(formatOutput(result.report, options.pretty))
+    process.exit(1)
+  }
+
+  console.log(
+    formatOutput(
+      {
+        success: true,
+        account_id: result.account_id,
+        imsg_version: result.report.imsg_version,
+        full_disk_access: result.report.full_disk_access,
+      },
+      options.pretty,
+    ),
+  )
+  process.exit(0)
+}
+
+export const setupCommand = new Command('setup')
+  .description('Guided setup: verify imsg + permissions and save an account')
+  .option('--bin <path>', 'Path to the imsg binary (default: imsg on PATH)')
+  .option('--region <code>', 'Default region for local-format phone numbers')
+  .option('--pretty', 'Pretty print JSON output')
+  .action(async (opts: { bin?: string; region?: string; pretty?: boolean }) => runSetup(opts))
+
+export { runSetup }

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

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'bun:test'
+
+import { resolveChatTarget } from './shared'
+
+describe('resolveChatTarget', () => {
+  it('treats a digits-only ref as a chat id (rowid)', () => {
+    expect(resolveChatTarget('42')).toEqual({ chatId: 42 })
+  })
+
+  it('passes a portable guid/identifier through as chat_guid', () => {
+    expect(resolveChatTarget('iMessage;-;+15551234567')).toEqual({ chatGuid: 'iMessage;-;+15551234567' })
+    expect(resolveChatTarget('iMessage;+;chat99')).toEqual({ chatGuid: 'iMessage;+;chat99' })
+  })
+
+  it('treats a non-numeric, non-guid ref as a recipient handle', () => {
+    expect(resolveChatTarget('+15551234567')).toEqual({ to: '+15551234567' })
+    expect(resolveChatTarget('jane@icloud.com')).toEqual({ to: 'jane@icloud.com' })
+  })
+})

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

@@ -0,0 +1,69 @@
+import { formatOutput } from '@/shared/utils/output'
+
+import { ImsgClient, type SendTarget } from '../client'
+import { IMessageCredentialManager } from '../credential-manager'
+import { IMessageError } from '../types'
+
+export interface AccountOption {
+  account?: string
+  pretty?: boolean
+}
+
+export function parseLimitOption(rawLimit: string | undefined, defaultValue: number, maxValue = 100): number {
+  const trimmed = (rawLimit ?? `${defaultValue}`).trim()
+  if (!/^\d+$/.test(trimmed)) {
+    throw new IMessageError(`--limit must be an integer between 1 and ${maxValue}.`, 'invalid_limit')
+  }
+  const parsed = Number.parseInt(trimmed, 10)
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > maxValue) {
+    throw new IMessageError(`--limit must be an integer between 1 and ${maxValue}.`, 'invalid_limit')
+  }
+  return parsed
+}
+
+export function resolveChatTarget(chatRef: string): SendTarget {
+  if (/^\d+$/.test(chatRef)) return { chatId: Number.parseInt(chatRef, 10) }
+  if (chatRef.includes(';')) return { chatGuid: chatRef }
+  return { to: chatRef }
+}
+
+const CHAT_RESOLVE_LIMIT = 1000
+
+export async function resolveChatId(client: ImsgClient, chatRef: string): Promise<number> {
+  if (/^\d+$/.test(chatRef)) return Number.parseInt(chatRef, 10)
+
+  if (chatRef.includes(';')) {
+    const chats = await client.listChats(CHAT_RESOLVE_LIMIT)
+    const match = chats.find((c) => c.guid === chatRef || c.identifier === chatRef)
+    if (match) return match.id
+  }
+
+  throw new IMessageError(
+    `Could not resolve "${chatRef}" to a chat id (searched the ${CHAT_RESOLVE_LIMIT} most recent chats). Use a numeric chat id from "agent-imessage chat list".`,
+    'chat_not_found',
+  )
+}
+
+export async function withImsgClient<T>(options: AccountOption, fn: (client: ImsgClient) => Promise<T>): Promise<T> {
+  const resolved = await new IMessageCredentialManager().resolveAccount(options.account)
+  if (!resolved) {
+    console.log(
+      formatOutput(
+        {
+          error: 'Not configured. Run "agent-imessage setup" first.',
+          code: 'not_authenticated',
+        },
+        options.pretty,
+      ),
+    )
+    process.exit(1)
+  }
+
+  const client = await new ImsgClient().login({ binaryPath: resolved.binary_path, region: resolved.region })
+  try {
+    await client.connect()
+    return await fn(client)
+  } finally {
+    await client.close()
+  }
+}

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

@@ -0,0 +1,22 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { withImsgClient } from './shared'
+
+async function whoamiAction(options: { account?: string; pretty?: boolean }): Promise<void> {
+  try {
+    const status = await withImsgClient(options, (client) => client.getStatus())
+    console.log(formatOutput(status, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+export const whoamiCommand = new Command('whoami')
+  .description('Show the active iMessage account and imsg status')
+  .option('--account <id>', 'Use a specific iMessage account')
+  .option('--pretty', 'Pretty print JSON output')
+  .action(whoamiAction)

package/src/platforms/imessage/credential-manager.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { IMessageCredentialManager } from './credential-manager'
+import type { IMessageAccount } from './types'
+
+const testDirs: string[] = []
+const saved: Record<string, string | undefined> = {}
+
+function setup(): IMessageCredentialManager {
+  const dir = join(import.meta.dir, `.test-imsg-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  testDirs.push(dir)
+  return new IMessageCredentialManager(dir)
+}
+
+function makeAccount(overrides?: Partial<IMessageAccount>): IMessageAccount {
+  const now = new Date().toISOString()
+  return {
+    account_id: 'home',
+    provider: 'imsg',
+    binary_path: '/opt/homebrew/bin/imsg',
+    region: 'US',
+    created_at: now,
+    updated_at: now,
+    ...overrides,
+  }
+}
+
+function clearEnv(): void {
+  for (const k of ['AGENT_IMESSAGE_BIN', 'AGENT_IMESSAGE_REGION']) {
+    saved[k] = process.env[k]
+    delete process.env[k]
+  }
+}
+
+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('IMessageCredentialManager', () => {
+  it('persists provider-aware schema with enforced 0600', async () => {
+    clearEnv()
+    const manager = setup()
+    await manager.setAccount(makeAccount())
+    const path = join(testDirs[testDirs.length - 1]!, 'imessage-credentials.json')
+    expect(existsSync(path)).toBe(true)
+    expect(statSync(path).mode & 0o777).toBe(0o600)
+    const config = await manager.loadConfig()
+    expect(config.accounts.home?.provider).toBe('imsg')
+  })
+
+  it('resolveAccount: env AGENT_IMESSAGE_BIN/REGION override stored, not persisted', async () => {
+    clearEnv()
+    const manager = setup()
+    await manager.setAccount(makeAccount({ binary_path: '/stored/imsg', region: 'GB' }))
+
+    expect(await manager.resolveAccount()).toEqual({ binary_path: '/stored/imsg', region: 'GB' })
+
+    process.env.AGENT_IMESSAGE_BIN = '/env/imsg'
+    process.env.AGENT_IMESSAGE_REGION = 'US'
+    expect(await manager.resolveAccount()).toEqual({ binary_path: '/env/imsg', region: 'US' })
+
+    const fresh = await manager.getAccount('home')
+    expect(fresh?.binary_path).toBe('/stored/imsg')
+  })
+
+  it('resolveAccount returns env-only when no account but AGENT_IMESSAGE_BIN set', async () => {
+    clearEnv()
+    const manager = setup()
+    expect(await manager.resolveAccount()).toBeNull()
+    process.env.AGENT_IMESSAGE_BIN = '/env/imsg'
+    expect(await manager.resolveAccount()).toEqual({ binary_path: '/env/imsg', region: undefined })
+  })
+
+  it('coerces malformed config and drops invalid accounts', async () => {
+    clearEnv()
+    const dir = join(import.meta.dir, `.test-imsg-bad-${Date.now()}`)
+    testDirs.push(dir)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'imessage-credentials.json'),
+      JSON.stringify({ current: 'missing', accounts: { good: { account_id: 'good' }, junk: 'x' } }),
+    )
+    const config = await new IMessageCredentialManager(dir).loadConfig()
+    expect(Object.keys(config.accounts)).toEqual(['good'])
+    expect(config.current).toBe('good')
+  })
+
+  it('re-indexes accounts by validated account_id when the persisted key differs', async () => {
+    clearEnv()
+    const dir = join(import.meta.dir, `.test-imsg-reindex-${Date.now()}`)
+    testDirs.push(dir)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'imessage-credentials.json'),
+      JSON.stringify({
+        current: 'home',
+        accounts: { 'stale-key': { account_id: 'home', server_url: undefined, binary_path: '/x/imsg' } },
+      }),
+    )
+    const manager = new IMessageCredentialManager(dir)
+    const config = await manager.loadConfig()
+    expect(Object.keys(config.accounts)).toEqual(['home'])
+    expect(config.current).toBe('home')
+    expect((await manager.getAccount('home'))?.binary_path).toBe('/x/imsg')
+  })
+
+  it('removeAccount reassigns current; setCurrent false for unknown', async () => {
+    clearEnv()
+    const manager = setup()
+    await manager.setAccount(makeAccount({ account_id: 'a' }))
+    await manager.setAccount(makeAccount({ account_id: 'b' }))
+    expect(await manager.removeAccount('a')).toBe(true)
+    expect((await manager.getAccount())?.account_id).toBe('b')
+    expect(await manager.setCurrent('ghost')).toBe(false)
+  })
+})

package/src/platforms/imessage/credential-manager.ts

@@ -0,0 +1,123 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { getConfigDir } from '../../shared/utils/config-dir'
+import { createAccountId, type IMessageAccount, type IMessageConfig } from './types'
+
+export interface ResolvedAccount {
+  binary_path: string
+  region?: string
+}
+
+function coerceConfig(raw: unknown): IMessageConfig {
+  if (typeof raw !== 'object' || raw === null) return { current: null, accounts: {} }
+
+  const obj = raw as Record<string, unknown>
+  const accounts: Record<string, IMessageAccount> = {}
+
+  if (typeof obj.accounts === 'object' && obj.accounts !== null) {
+    for (const value of Object.values(obj.accounts as Record<string, unknown>)) {
+      if (typeof value !== 'object' || value === null) continue
+      const a = value as Record<string, unknown>
+      if (typeof a.account_id !== 'string' || a.account_id.length === 0) continue
+      accounts[a.account_id] = {
+        account_id: a.account_id,
+        provider: 'imsg',
+        label: typeof a.label === 'string' ? a.label : undefined,
+        binary_path: typeof a.binary_path === 'string' ? a.binary_path : undefined,
+        region: typeof a.region === 'string' ? a.region : undefined,
+        created_at: typeof a.created_at === 'string' ? a.created_at : new Date().toISOString(),
+        updated_at: typeof a.updated_at === 'string' ? a.updated_at : new Date().toISOString(),
+      }
+    }
+  }
+
+  const current =
+    typeof obj.current === 'string' && accounts[obj.current] ? obj.current : (Object.keys(accounts)[0] ?? null)
+  return { current, accounts }
+}
+
+export class IMessageCredentialManager {
+  private configDir: string
+  private credentialsPath: string
+
+  constructor(configDir?: string) {
+    this.configDir = configDir ?? getConfigDir()
+    this.credentialsPath = join(this.configDir, 'imessage-credentials.json')
+  }
+
+  async loadConfig(): Promise<IMessageConfig> {
+    if (!existsSync(this.credentialsPath)) return { current: null, accounts: {} }
+    try {
+      return coerceConfig(JSON.parse(await readFile(this.credentialsPath, 'utf-8')))
+    } catch {
+      return { current: null, accounts: {} }
+    }
+  }
+
+  async saveConfig(config: IMessageConfig): Promise<void> {
+    await mkdir(this.configDir, { recursive: true })
+    await writeFile(this.credentialsPath, JSON.stringify(config, null, 2), { mode: 0o600 })
+    await chmod(this.credentialsPath, 0o600)
+  }
+
+  async getAccount(accountId?: string): Promise<IMessageAccount | null> {
+    const config = await this.loadConfig()
+    if (!accountId) return config.current ? (config.accounts[config.current] ?? null) : null
+    return config.accounts[accountId] ?? config.accounts[createAccountId(accountId)] ?? null
+  }
+
+  async listAccounts(): Promise<Array<IMessageAccount & { is_current: boolean }>> {
+    const config = await this.loadConfig()
+    return Object.values(config.accounts).map((account) => ({
+      ...account,
+      is_current: account.account_id === config.current,
+    }))
+  }
+
+  async setAccount(account: IMessageAccount): Promise<void> {
+    const config = await this.loadConfig()
+    config.accounts[account.account_id] = account
+    if (!config.current) config.current = account.account_id
+    await this.saveConfig(config)
+  }
+
+  async setCurrent(accountId: string): Promise<boolean> {
+    const config = await this.loadConfig()
+    const account = config.accounts[accountId] ?? config.accounts[createAccountId(accountId)]
+    if (!account) return false
+    config.current = account.account_id
+    await this.saveConfig(config)
+    return true
+  }
+
+  async removeAccount(accountId: string): Promise<boolean> {
+    const config = await this.loadConfig()
+    const account = config.accounts[accountId] ?? config.accounts[createAccountId(accountId)]
+    if (!account) return false
+    delete config.accounts[account.account_id]
+    if (config.current === account.account_id) {
+      config.current = Object.keys(config.accounts)[0] ?? null
+    }
+    await this.saveConfig(config)
+    return true
+  }
+
+  async clearCredentials(): Promise<void> {
+    if (existsSync(this.credentialsPath)) await rm(this.credentialsPath, { force: true })
+  }
+
+  async resolveAccount(accountId?: string): Promise<ResolvedAccount | null> {
+    const envBin = process.env.AGENT_IMESSAGE_BIN
+    const envRegion = process.env.AGENT_IMESSAGE_REGION
+
+    const account = await this.getAccount(accountId)
+    if (!account && !envBin) return null
+
+    return {
+      binary_path: envBin ?? account?.binary_path ?? 'imsg',
+      region: envRegion ?? account?.region,
+    }
+  }
+}

package/src/platforms/imessage/ensure-auth.ts

@@ -0,0 +1,18 @@
+import { formatOutput } from '@/shared/utils/output'
+
+import { IMessageCredentialManager } from './credential-manager'
+
+export async function ensureIMessageAuth(): Promise<void> {
+  const resolved = await new IMessageCredentialManager().resolveAccount()
+
+  if (!resolved) {
+    console.log(
+      formatOutput({
+        error:
+          'Not configured. iMessage runs on this Mac via the "imsg" tool. Run "agent-imessage setup" for a guided walkthrough, or "agent-imessage doctor" to check requirements.',
+        code: 'not_authenticated',
+      }),
+    )
+    process.exit(1)
+  }
+}

package/src/platforms/imessage/errors.ts

@@ -0,0 +1,27 @@
+import { IMessageError, type IMessageErrorCode } from './types'
+
+const FULL_DISK_ACCESS = /full disk access|cannot access messages database|unable to open database/i
+const AUTOMATION_DENIED = /automation|not authorized|not allowed to send/i
+const APPLESCRIPT_SEND = /unjoined empty outgoing row|delivery to the target chat was not confirmed|applescript/i
+
+export function classifyImsgFailure(text: string, fallback: IMessageErrorCode = 'rpc_error'): IMessageError {
+  if (FULL_DISK_ACCESS.test(text)) {
+    return new IMessageError('imsg cannot read the Messages database.', 'full_disk_access', {
+      suggestion:
+        'Grant Full Disk Access to the app/terminal that launches agent-messenger (System Settings → Privacy & Security → Full Disk Access).',
+      doctorCommand: 'agent-imessage doctor',
+    })
+  }
+  if (AUTOMATION_DENIED.test(text)) {
+    return new IMessageError('imsg is not allowed to control Messages.app.', 'automation_denied', {
+      suggestion: 'Grant Automation → Messages in System Settings → Privacy & Security.',
+      doctorCommand: 'agent-imessage doctor',
+    })
+  }
+  if (APPLESCRIPT_SEND.test(text)) {
+    return new IMessageError(text || 'imsg could not send the message.', 'send_failed', {
+      doctorCommand: 'agent-imessage doctor',
+    })
+  }
+  return new IMessageError(text || 'imsg request failed.', fallback, { doctorCommand: 'agent-imessage doctor' })
+}