agent-messenger 2.27.2 → 2.28.0

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

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