agent-messenger 2.27.1 → 2.28.0

package/docs/content/docs/agent-skills.mdx

@@ -4,7 +4,7 @@ description: Teach your AI agent how to use Agent Messenger CLIs effectively.
 icon: Hexagon
 ---
 
-Agent Skills are instruction files that teach AI coding agents how to use tools effectively. Agent Messenger includes skills for Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta).
+Agent Skills are instruction files that teach AI coding agents how to use tools effectively. Agent Messenger includes skills for Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, iMessage (Mac-only), Instagram, KakaoTalk, and Channel Talk (beta).
 
 ## What Are Agent Skills?
 

package/docs/content/docs/cli/imessage.mdx

@@ -0,0 +1,99 @@
+---
+title: iMessage
+description: Complete reference for the agent-imessage CLI.
+---
+
+> **Tip**: After `npm install -g agent-messenger`, `agent-imessage` is available directly. For one-off execution without a global install you can use `npm exec --package agent-messenger agent-imessage ...`, `pnpm dlx --package agent-messenger agent-imessage ...`, `yarn dlx agent-messenger agent-imessage ...`, or `bunx --package agent-messenger agent-imessage ...`.
+
+## Requirements
+
+Apple provides no public iMessage API, so `agent-imessage` runs **on a Mac** and drives Messages through [imsg](https://github.com/openclaw/imsg), a native Swift CLI:
+
+- The agent must run **on the Mac itself** — imsg is local-only (no network, no server).
+- `agent-imessage` spawns `imsg` and communicates over JSON-RPC (stdin/stdout).
+- Requires macOS 14+, imsg installed (`brew install steipete/tap/imsg`), **Full Disk Access** (read), and **Automation → Messages** (send). macOS grants these to the launching parent process.
+- Basic send/read/watch/standard tapbacks need **no SIP changes**. Typing, edit/unsend, group management, and targeted/custom reactions require imsg's bridge (`imsg launch` + SIP) and are a later tier.
+
+See the [setup guide](https://github.com/agent-messenger/agent-messenger/blob/main/skills/agent-imessage/references/setup.md) and [permissions guide](https://github.com/agent-messenger/agent-messenger/blob/main/skills/agent-imessage/references/permissions.md).
+
+## Quick Start
+
+```bash
+agent-imessage setup                 # guided check + save account
+agent-imessage doctor                # diagnose imsg + permissions
+
+agent-imessage chat list             # chat ids/guids
+agent-imessage message send 42 "Hello"
+agent-imessage message send "+15551234567" "Hi"
+agent-imessage message list 42 --limit 20
+agent-imessage message watch --chat all --jsonl
+agent-imessage message react 42 love
+```
+
+## Chat references
+
+What a `<chat>` argument accepts depends on the command:
+
+- **`message send`** — a **chat id** (integer rowid), a portable **guid/identifier** (e.g. `iMessage;-;+15551234567`, passed straight through to imsg), or a **phone/email recipient**.
+- **`message list` / `message react` / `message watch --chat`** — a **chat id** is recommended. A guid/identifier also works as a convenience, but since imsg exposes no guid→id lookup it is resolved by scanning the **1000 most recent chats**; an older chat outside that window returns `chat_not_found`. Use the numeric chat id from `chat list` for those.
+
+Get chat ids and guids from `agent-imessage chat list`.
+
+## Authentication
+
+iMessage uses macOS permissions, not tokens. Configure the imsg binary/region:
+
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current
+agent-imessage auth list
+agent-imessage auth use <account-id>
+agent-imessage auth remove <account-id>
+agent-imessage auth logout
+```
+
+Environment overrides (runtime only, never persisted): `AGENT_IMESSAGE_BIN`, `AGENT_IMESSAGE_REGION`.
+
+## Commands
+
+### chat
+
+```bash
+agent-imessage chat list [--limit <n>]
+agent-imessage chat search <query> [--limit <n>]
+```
+
+### message
+
+```bash
+agent-imessage message list <chat> [--limit <n>] [--start <iso>]
+agent-imessage message send <chat> <text>
+agent-imessage message react <chat> <love|like|dislike|laugh|emphasis|question>
+agent-imessage message watch [--chat <ref|all>] [--since-rowid <n>] [--jsonl]
+```
+
+`message react` reacts to the **most recent incoming message** in the chat (an imsg limitation without the bridge). `message watch` streams new messages; pass `--since-rowid` to replay from a message rowid then continue live.
+
+### whoami / doctor / setup
+
+```bash
+agent-imessage whoami
+agent-imessage doctor [--account <id>] [--test-chat <chatId>]
+agent-imessage setup
+```
+
+All commands accept `--account <id>` and `--pretty`.
+
+## Output Format
+
+JSON by default; `--pretty` for indented output. `message watch --jsonl` emits one JSON object per line.
+
+## Feature Tiers
+
+| Feature                                                     | Available  | Requires                          |
+| ----------------------------------------------------------- | :--------: | --------------------------------- |
+| List/search chats, send text, read/watch, standard tapbacks |     ✅     | imsg core (no SIP)                |
+| Targeted/custom reactions, typing, edit/unsend, group mgmt  | ⏳ planned | imsg bridge (`imsg launch` + SIP) |
+
+## Notes
+
+`agent-imessage` is backend-agnostic by design (the credential record carries a `provider` field). Today the only provider is the local imsg tool. Networked backends are intentionally out of scope for this on-Mac integration.

package/docs/content/docs/cli/instagram.mdx

@@ -182,7 +182,7 @@ Thread IDs are numeric strings returned by `chat list` (e.g. `340282366841710300
 
 ## Limitations
 
-- **HTTP on demand**: Each command makes HTTP requests and returns. No persistent daemon or WebSocket connection.
+- **HTTP on demand**: Each command makes HTTP requests and returns. No persistent daemon or WebSocket connection. The CLI does not expose real-time events, but the SDK does — via `InstagramHybridListener` (realtime over MQTToT with polling fallback) and `InstagramRealtimeListener`. See the [SDK reference](../sdk/instagram#real-time-events).
 - **Ban risk**: Instagram monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
 - **No file uploads or downloads**
 - **No voice or video calls**

package/docs/content/docs/cli/meta.json

@@ -14,6 +14,7 @@
     "whatsappbot",
     "line",
     "wechatbot",
+    "imessage",
     "instagram",
     "kakaotalk",
     "channeltalk",

package/docs/content/docs/index.mdx

@@ -1,10 +1,10 @@
 ---
 title: What is Agent Messenger?
-description: Give your AI agent the power to read and send messages across Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, Channel Talk, and more
+description: Give your AI agent the power to read and send messages across Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, iMessage, Instagram, KakaoTalk, Channel Talk, and more
 icon: Info
 ---
 
-Agent Messenger is a unified, agent-friendly CLI for messaging platforms. Zero-config credential extraction from your desktop apps—no OAuth flows, no API keys, no admin approval needed. Works out of the box. Supports Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta).
+Agent Messenger is a unified, agent-friendly CLI for messaging platforms. Most platforms use zero-config credential extraction from your desktop apps or quick local auth—no OAuth flows, no API keys, no admin approval needed. Supports Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, iMessage (Mac-only via imsg setup), Instagram, KakaoTalk, and Channel Talk (beta).
 
 ## Why Agent Messenger?
 
@@ -12,14 +12,14 @@ Messaging platforms only offer Bot tokens for API access—your AI agent can nev
 
 - **Act as yourself, not a bot** — Extracted user tokens let your agent operate on your behalf
 - **No API keys needed** — Automatically extracts credentials from your installed desktop apps
-- **One interface, multiple platforms** — Learn once, use everywhere (Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, Channel Talk)
+- **One interface, multiple platforms** — Learn once, use everywhere (Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, iMessage, Instagram, KakaoTalk, Channel Talk)
 - **AI-agent friendly** — JSON output by default, perfect for LLM tool use
 - **Human friendly too** — Add `--pretty` for readable output
 - **Token efficient** — CLI, not MCP. Load only what you need
 
 ## How It Works
 
-Agent Messenger reads authentication tokens directly from your installed desktop apps (Slack, Discord, Teams, KakaoTalk, Channel Talk). Telegram uses TDLib with auto-provisioned API credentials. WhatsApp authenticates via pairing code. KakaoTalk supports both credential extraction and sub-device login. These apps store session tokens locally, and Agent Messenger safely extracts them.
+Agent Messenger reads authentication tokens directly from your installed desktop apps (Slack, Discord, Teams, KakaoTalk, Channel Talk). Telegram uses TDLib with auto-provisioned API credentials. WhatsApp authenticates via pairing code. KakaoTalk supports both credential extraction and sub-device login. iMessage is the exception — Apple has no API, so it runs locally on a Mac via the [imsg](https://github.com/openclaw/imsg) tool. These apps store session tokens locally, and Agent Messenger safely extracts them.
 
 ```bash
 # Extract credentials from Slack desktop app
@@ -36,7 +36,7 @@ No app creation. No admin approval. No waiting.
 | Feature             | Description                                                                                                                                                                                                        |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Auto-extraction** | Pulls tokens from desktop apps automatically                                                                                                                                                                       |
-| **Multi-platform**  | Slack, Discord, Microsoft Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta)                                                                                                           |
+| **Multi-platform**  | Slack, Discord, Microsoft Teams, Webex, Telegram, WhatsApp, LINE, iMessage (Mac-only), Instagram, KakaoTalk, and Channel Talk (beta)                                                                               |
 | **Multi-workspace** | Switch between workspaces/servers easily                                                                                                                                                                           |
 | **JSON output**     | Machine-readable by default, `--pretty` for humans                                                                                                                                                                 |
 | **Comprehensive**   | Messages, channels, users, reactions, files                                                                                                                                                                        |
@@ -95,7 +95,7 @@ Default output is JSON for machines. Add `--pretty` for humans. Both are first-c
 
 ### Unified Interface
 
-Learn once, use everywhere. The same commands work across Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk.
+Learn once, use everywhere. The same commands work across Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, iMessage, Instagram, KakaoTalk, and Channel Talk.
 
 ### Fail Fast, Fail Clear
 
@@ -113,11 +113,14 @@ Tokens stay on your machine. Nothing is sent to external servers. Your credentia
 - [Discord](/docs/cli/discord) - Full Discord command reference
 - [Discord Bot](/docs/cli/discordbot) - Bot token integration for server-side and CI/CD
 - [Teams](/docs/cli/teams) - Full Teams command reference
+- [Webex](/docs/cli/webex) - Full Webex command reference
+- [Webex Bot](/docs/cli/webexbot) - Bot token integration for server-side and CI/CD
 - [Telegram](/docs/cli/telegram) - TDLib setup and Telegram command reference
 - [Telegram Bot](/docs/cli/telegrambot) - Bot token integration for server-side and CI/CD
 - [WhatsApp](/docs/cli/whatsapp) - Full WhatsApp command reference
 - [WhatsApp Bot](/docs/cli/whatsappbot) - Cloud API integration for WhatsApp Business
 - [LINE](/docs/cli/line) - Full LINE command reference
+- [iMessage](/docs/cli/imessage) - iMessage on a Mac via the imsg tool
 - [Instagram](/docs/cli/instagram) - Instagram DM integration via private mobile API
 - [KakaoTalk](/docs/cli/kakaotalk) - Full KakaoTalk command reference
 - [Channel Talk](/docs/cli/channeltalk) - Full Channel Talk command reference (beta)

package/docs/content/docs/quick-start.mdx

@@ -35,6 +35,7 @@ This installs these CLI tools:
 - `agent-whatsapp` — WhatsApp CLI (user account via Baileys, pairing code auth)
 - `agent-whatsappbot` — WhatsApp Bot CLI (Cloud API, for server-side/CI/CD)
 - `agent-line` — LINE CLI (QR code login, Thrift protocol)
+- `agent-imessage` — iMessage CLI (runs on a Mac via the [imsg](https://github.com/openclaw/imsg) tool)
 - `agent-instagram` — Instagram DM CLI (user account via private mobile API)
 - `agent-kakaotalk` — KakaoTalk CLI (sub-device login, LOCO protocol)
 - `agent-channeltalk` — Channel Talk CLI (beta, zero-config, extracted cookies)
@@ -127,6 +128,7 @@ agent-slack workspace current
 - [Telegram Bot Reference](/docs/cli/telegrambot) - Bot token for server-side/CI/CD
 - [WhatsApp Reference](/docs/cli/whatsapp) - Full command reference
 - [WhatsApp Bot Reference](/docs/cli/whatsappbot) - Cloud API for WhatsApp Business
+- [iMessage Reference](/docs/cli/imessage) - iMessage on a Mac via the imsg tool
 - [KakaoTalk Reference](/docs/cli/kakaotalk) - Full command reference
 - [Channel Talk Reference](/docs/cli/channeltalk) - Full command reference (beta)
 - [Channel Talk Bot Reference](/docs/cli/channeltalkbot) - Bot API for Channel Talk (beta)

package/docs/content/docs/sdk/instagram.mdx

@@ -13,6 +13,8 @@ npm install agent-messenger
 import {
   InstagramClient,
   InstagramListener,
+  InstagramRealtimeListener,
+  InstagramHybridListener,
   InstagramError,
   InstagramCredentialManager,
 } from 'agent-messenger/instagram'
@@ -122,7 +124,83 @@ client.setDebugLog((msg) => console.error(`[debug] ${msg}`))
 
 ## Real-Time Events
 
-`InstagramListener` polls the Instagram inbox for new messages at a configurable interval.
+### InstagramHybridListener (Recommended)
+
+`InstagramHybridListener` tries to connect over Instagram's MQTToT transport first (a persistent TLS connection to `edge-mqtt.facebook.com` — the same protocol Instagram's own app uses). If that fails, it falls back to polling automatically and retries the realtime connection with capped exponential backoff.
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client, {
+  pollInterval: 5000, // fallback poll interval in ms (default: 5000)
+  realtimeRetryBaseMs: 2000, // backoff base for realtime reconnect attempts
+  realtimeRetryMaxMs: 60000, // backoff cap
+  disableRealtime: false, // set true to force polling-only mode
+})
+
+listener.on('message', (msg) => {
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('connected', ({ userId, transport }) => {
+  // transport is 'realtime' or 'polling'
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('error', (err) => console.error(err))
+listener.on('disconnected', () => console.log('Stopped'))
+
+await listener.start()
+// listener.stop() to disconnect
+```
+
+#### Events
+
+| Event          | Payload                                                  | Description                                   |
+| -------------- | -------------------------------------------------------- | --------------------------------------------- |
+| `message`      | `InstagramMessageSummary`                                | New message received                          |
+| `connected`    | `{ userId: string; transport: 'realtime' \| 'polling' }` | Listener active; `transport` shows which path |
+| `disconnected` | —                                                        | Listener stopped                              |
+| `error`        | `Error`                                                  | Network or API error                          |
+
+### InstagramRealtimeListener
+
+`InstagramRealtimeListener` connects directly over MQTToT with no polling fallback. Use this when you want pure realtime and prefer to handle reconnection yourself.
+
+```typescript
+import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramRealtimeListener(client)
+
+listener.on('message', (msg) => {
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('connected', ({ userId }) => {
+  console.log(`Listening as ${userId}`)
+})
+
+listener.on('error', (err) => console.error(err))
+listener.on('disconnected', () => console.log('Disconnected'))
+
+await listener.start()
+// listener.stop() to disconnect
+```
+
+#### Events
+
+| Event          | Payload                   | Description                   |
+| -------------- | ------------------------- | ----------------------------- |
+| `message`      | `InstagramMessageSummary` | New message received          |
+| `connected`    | `{ userId: string }`      | MQTToT connection established |
+| `disconnected` | —                         | Connection closed             |
+| `error`        | `Error`                   | Connection or protocol error  |
+
+### InstagramListener (Polling Only)
+
+`InstagramListener` polls the Instagram inbox for new messages at a configurable interval. It's the original listener and remains available for environments where a persistent connection isn't suitable.
 
 ```typescript
 import { InstagramClient, InstagramListener } from 'agent-messenger/instagram'
@@ -145,7 +223,7 @@ await listener.start()
 // listener.stop() to disconnect
 ```
 
-### Events
+#### Events
 
 | Event          | Payload                   | Description                             |
 | -------------- | ------------------------- | --------------------------------------- |
@@ -220,6 +298,9 @@ import type {
   InstagramMessageSummary,
   InstagramSessionState,
   InstagramListenerEventMap,
+  InstagramRealtimeListenerEventMap,
+  InstagramHybridListenerEventMap,
+  InstagramHybridListenerOptions,
 } from 'agent-messenger/instagram'
 ```
 
@@ -304,19 +385,23 @@ if (alice) {
 
 ### Message Monitor
 
-Watch for new DMs using the real-time listener.
+Watch for new DMs using the hybrid listener, which tries realtime first and falls back to polling automatically.
 
 ```typescript
-import { InstagramClient, InstagramListener } from 'agent-messenger/instagram'
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
 
 const client = await new InstagramClient().login()
-const listener = new InstagramListener(client, { pollInterval: 10_000 })
+const listener = new InstagramHybridListener(client)
 
 listener.on('message', (msg) => {
   if (msg.is_outgoing) return
   console.log(`New DM from ${msg.from}: ${msg.text ?? `[${msg.type}]`}`)
 })
 
+listener.on('connected', ({ userId, transport }) => {
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
 listener.on('error', (err) => {
   console.error('Listener error:', err.message)
 })

package/docs/content/docs/tui.mdx

@@ -4,11 +4,11 @@ description: A unified terminal interface for all your messaging platforms in on
 icon: Monitor
 ---
 
-> **Experimental** — The TUI is a showcase of what's possible with Agent Messenger's SDK. It's not intended for production use, but demonstrates the power of having a unified adapter layer across 10 messaging platforms.
+> **Experimental** — The TUI is a showcase of what's possible with Agent Messenger's SDK. It's not intended for production use, but demonstrates the power of having a unified adapter layer across 11 messaging platforms.
 
 ## What Is It?
 
-The TUI (Terminal User Interface) is a `blessed`-based interactive terminal app that unifies all your messaging platforms into a single screen. Navigate between Slack, Discord, Teams, Webex, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk — all from your terminal.
+The TUI (Terminal User Interface) is a `blessed`-based interactive terminal app that unifies all your messaging platforms into a single screen. Navigate between Slack, Discord, Teams, Webex, Telegram, WhatsApp, iMessage, LINE, Instagram, KakaoTalk, and Channel Talk — all from your terminal.
 
 ![Agent Messenger TUI](/tui.png)
 
@@ -30,7 +30,7 @@ The TUI has three navigation levels and three input modes.
 
 | Level         | What it shows                                              | How to enter                               |
 | ------------- | ---------------------------------------------------------- | ------------------------------------------ |
-| **Platform**  | All 10 platforms with online/offline status                | Launch or press `Esc` from workspace level |
+| **Platform**  | All 11 platforms with online/offline status                | Launch or press `Esc` from workspace level |
 | **Workspace** | Workspaces for the selected platform (skipped if only one) | Select a platform                          |
 | **Channel**   | Channels in the current workspace                          | Select a workspace                         |
 
@@ -128,6 +128,7 @@ src/tui/
 │   ├── webex-adapter.ts
 │   ├── telegram-adapter.ts
 │   ├── whatsapp-adapter.ts
+│   ├── imessage-adapter.ts
 │   ├── line-adapter.ts
 │   ├── instagram-adapter.ts
 │   ├── kakaotalk-adapter.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-messenger",
-  "version": "2.27.1",
-  "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams, Webex, Telegram, Telegram Bot, WhatsApp, LINE, Instagram, KakaoTalk, Channel Talk)",
+  "version": "2.28.0",
+  "description": "Multi-platform messaging CLI for AI agents (Slack, Discord, Teams, Webex, Telegram, Telegram Bot, WhatsApp, LINE, iMessage, Instagram, KakaoTalk, Channel Talk)",
   "repository": {
     "type": "git",
     "url": "https://github.com/agent-messenger/agent-messenger"
@@ -11,6 +11,7 @@
     "agent-channeltalkbot": "dist/src/platforms/channeltalkbot/cli.js",
     "agent-discord": "dist/src/platforms/discord/cli.js",
     "agent-discordbot": "dist/src/platforms/discordbot/cli.js",
+    "agent-imessage": "dist/src/platforms/imessage/cli.js",
     "agent-instagram": "dist/src/platforms/instagram/cli.js",
     "agent-kakaotalk": "dist/src/platforms/kakaotalk/cli.js",
     "agent-line": "dist/src/platforms/line/cli.js",
@@ -65,6 +66,9 @@
       "wechatbot": [
         "./dist/src/platforms/wechatbot/index.d.ts"
       ],
+      "imessage": [
+        "./dist/src/platforms/imessage/index.d.ts"
+      ],
       "instagram": [
         "./dist/src/platforms/instagram/index.d.ts"
       ],
@@ -132,6 +136,10 @@
       "types": "./dist/src/platforms/wechatbot/index.d.ts",
       "default": "./dist/src/platforms/wechatbot/index.js"
     },
+    "./imessage": {
+      "types": "./dist/src/platforms/imessage/index.d.ts",
+      "default": "./dist/src/platforms/imessage/index.js"
+    },
     "./instagram": {
       "types": "./dist/src/platforms/instagram/index.d.ts",
       "default": "./dist/src/platforms/instagram/index.js"

package/scripts/postbuild.ts

@@ -1,24 +1,21 @@
-import { cpSync, readFileSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
 
-const cliFiles = [
-  'dist/src/cli.js',
-  'dist/src/platforms/slack/cli.js',
-  'dist/src/platforms/discord/cli.js',
-  'dist/src/platforms/teams/cli.js',
-  'dist/src/platforms/slackbot/cli.js',
-  'dist/src/platforms/channeltalk/cli.js',
-  'dist/src/platforms/channeltalkbot/cli.js',
-  'dist/src/platforms/telegram/cli.js',
-  'dist/src/platforms/telegrambot/cli.js',
-]
+const pkg = JSON.parse(readFileSync('package.json', 'utf8')) as { bin?: Record<string, string> }
 
+const cliFiles = Object.values(pkg.bin ?? {}).map((entry) =>
+  entry.replace(/^\.\/src\//, 'dist/src/').replace(/\.ts$/, '.js'),
+)
+
+let updatedCount = 0
 for (const file of cliFiles) {
+  if (!existsSync(file)) continue
   const content = readFileSync(file, 'utf8')
-  const updated = content.replace('#!/usr/bin/env bun', '#!/usr/bin/env node')
-  writeFileSync(file, updated)
+  if (!content.startsWith('#!/usr/bin/env bun')) continue
+  writeFileSync(file, content.replace('#!/usr/bin/env bun', '#!/usr/bin/env node'))
+  updatedCount++
 }
 
-console.log(`Updated shebang in ${cliFiles.length} CLI files`)
+console.log(`Updated shebang in ${updatedCount} CLI files`)
 
 cpSync('src/vendor', 'dist/src/vendor', { recursive: true })
 

package/skills/agent-channeltalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-channeltalk
 description: Interact with Channel Talk using extracted desktop app or browser credentials - read chats, send messages, search messages, manage groups
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-channeltalk:*)
 metadata:
   openclaw:

package/skills/agent-channeltalkbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-channeltalkbot
 description: Interact with Channel Talk workspaces using API credentials - send messages, read chats, manage groups and bots
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-channeltalkbot:*)
 metadata:
   openclaw:

package/skills/agent-discord/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discord
 description: Interact with Discord servers - send messages, read channels, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-discord:*)
 metadata:
   openclaw:

package/skills/agent-discordbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discordbot
 description: Interact with Discord servers using bot tokens - send messages, read channels, manage reactions
-version: 2.27.1
+version: 2.28.0
 allowed-tools: Bash(agent-discordbot:*)
 metadata:
   openclaw:

package/skills/agent-imessage/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: agent-imessage
+description: Interact with iMessage on a Mac via the imsg tool - send messages, read chats, watch for new messages
+version: 2.28.0
+allowed-tools: Bash(agent-imessage:*)
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - agent-imessage
+    install:
+      - kind: node
+        package: agent-messenger
+        bins: [agent-imessage]
+---
+
+# Agent iMessage
+
+An iMessage CLI for AI agents, backed by [imsg](https://github.com/openclaw/imsg) — a native macOS tool that reads the local Messages database and sends through Messages.app. Apple has no public iMessage API, so this integration runs **on a Mac** and drives Messages locally. You act as yourself with your own Apple ID; nothing leaves the machine.
+
+Use one of these entrypoints:
+- Global install: `agent-imessage ...`
+- One-off execution: `bunx --package agent-messenger agent-imessage ...`
+
+## Key Concepts
+
+- **imsg** = a local Swift CLI (`brew install steipete/tap/imsg`). `agent-imessage` spawns it and talks to it over JSON-RPC (stdin/stdout). There is **no network and no server** — it must run on the Mac signed into iMessage.
+- **On-Mac only** = unlike other agent-messenger platforms, this one cannot run remotely or in a container. The agent runs on the Mac itself.
+- **Permissions** = imsg needs **Full Disk Access** (to read the Messages database) and **Automation → Messages** (to send). macOS grants these to the **parent process** — the app/terminal that launches agent-messenger.
+- **Chat reference** = for `message send`, a chat id (integer rowid), a portable `guid`/`identifier` (e.g. `iMessage;-;+15551234567`), or a phone/email recipient. For `message list`/`react`/`watch --chat`, prefer a **chat id** — a guid also works but (since imsg has no guid→id lookup) is resolved against the 1000 most recent chats only.
+- **Watch** = streams new messages via imsg; resumable from a message rowid with `--since-rowid`.
+- **Multi-account** = each account is an imsg configuration (binary path / region). Send is single-account (Messages has no from-selector).
+- **Private API tier** = typing, edit/unsend, group management, custom/targeted reactions require `imsg launch` (SIP disabled). Basic send/read/watch/standard tapbacks do NOT.
+
+## Quick Start
+
+```bash
+# Guided setup: checks imsg + permissions, saves an account
+agent-imessage setup
+
+# Diagnose anytime
+agent-imessage doctor
+
+# List chats (source of chat ids/guids)
+agent-imessage chat list
+
+# Send (to a chat id, guid, or a phone/email)
+agent-imessage message send 42 "Hello from agent-imessage"
+agent-imessage message send "+15551234567" "Hi"
+
+# Read recent messages
+agent-imessage message list 42 --limit 20
+
+# Watch for new messages (resumable, JSON lines)
+agent-imessage message watch --chat all --jsonl
+
+# React to the most recent incoming message (standard tapbacks)
+agent-imessage message react 42 love
+```
+
+## Setup & Permissions
+
+iMessage runs on the Mac via imsg. One-time setup:
+
+1. `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 launching 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).
+
+See [setup](references/setup.md) and [permissions](references/permissions.md) references for detail.
+
+Configuration is scriptable too:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current
+```
+Environment overrides (runtime only, not persisted): `AGENT_IMESSAGE_BIN`, `AGENT_IMESSAGE_REGION`.
+
+### Agent Behavior (MANDATORY)
+
+When a command fails, the agent MUST run `agent-imessage doctor` and act on the `suggestion`/`code` rather than telling the user to run commands. If `code` is `imsg_not_found`, guide installing imsg. If `full_disk_access` or `automation_denied`, surface the exact System Settings path (and that macOS grants to the parent process). Never silently retry the same failing call.
+
+## Commands
+
+- `setup` — guided check + save account.
+- `doctor [--account <id>] [--test-chat <chatId>]` — diagnose imsg + permissions.
+- `auth set|list|use|remove|logout` — manage accounts (binary path / region).
+- `chat list [--limit]` / `chat search <query> [--limit]`.
+- `message list <chat> [--limit] [--start <iso>]` — read history (oldest-last). `<chat>` = chat id (recommended) or recent-chat guid.
+- `message send <chat> <text>` — `<chat>` = chat id/guid or phone/email.
+- `message react <chat> <reaction>` — standard tapback to the **most recent incoming** message.
+- `message watch [--chat <ref|all>] [--since-rowid <n>] [--jsonl]` — stream new messages.
+- `whoami` — active account + imsg status.
+
+All commands accept `--account <id>` and `--pretty`.
+
+## Output Format
+
+JSON by default; `--pretty` for indented output. `message watch --jsonl` emits one JSON object per line.
+
+## Feature Tiers
+
+| Feature | Available | Requires |
+| --- | --- | --- |
+| List/search chats, send text, read/watch messages | ✅ | imsg core (no SIP) |
+| Standard tapbacks, to the most recent incoming message | ✅ | imsg core (no SIP) |
+| React to a specific message / custom-emoji tapbacks | ⏳ planned | imsg bridge (`imsg launch` + SIP) |
+| Typing, read receipts, edit/unsend, group management | ⏳ planned | imsg bridge (`imsg launch` + SIP) |
+
+## Error Handling
+
+Errors are JSON with a `code` and often a `suggestion`:
+
+| Code | Meaning | Action |
+| --- | --- | --- |
+| `imsg_not_found` | imsg binary not runnable | `brew install steipete/tap/imsg` (or set `--bin`/`AGENT_IMESSAGE_BIN`). |
+| `full_disk_access` | Can't read Messages DB | Grant Full Disk Access to the launching app (parent process). |
+| `automation_denied` | Can't control Messages | Grant Automation → Messages in System Settings. |
+| `not_authenticated` | No account configured | Run `agent-imessage setup`. |
+| `chat_not_found` | Unknown chat ref | Use a chat id/guid from `chat list`. |
+| `private_api_required` | Feature needs the bridge | Standard send/read/watch/tapbacks work without it; targeted/custom reactions need `imsg launch` (SIP off). |
+| `invalid_limit` | Bad `--limit`/`--since-rowid` | Use an integer 1–100 for `--limit`; non-negative integer for `--since-rowid`. |
+| `send_failed` | imsg could not send | Run `doctor`; on macOS 26 group sends can fail (imsg reports honestly). |
+| `rpc_error` | imsg rpc problem | Run `doctor`; check the imsg version. |
+
+## Troubleshooting
+
+- **`agent-imessage doctor`** is the fastest diagnostic — it reports imsg version, Full Disk Access, and the bridge tier.
+- **Permissions denied** — remember macOS grants Full Disk Access / Automation to the **parent** process (the terminal or agent runtime), not just `imsg`.
+- **Reactions only hit the latest message** — that's an imsg/AppleScript limitation without the bridge; reacting to a specific message needs `imsg launch` + SIP off.
+
+## Configuration
+
+Account config is stored in `~/.config/agent-messenger/imessage-credentials.json` (mode `0600`). Relocate via `AGENT_MESSENGER_CONFIG_DIR`. No secrets are stored — imsg uses macOS permissions, not tokens.