agent-messenger 2.27.2 → 2.28.0

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.2",
-  "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.2
+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.2
+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.2
+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.2
+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.

package/skills/agent-imessage/references/authentication.md

@@ -0,0 +1,66 @@
+# Authentication
+
+iMessage authentication is unlike the other platforms: there are **no tokens, cookies, or login flow**. `agent-imessage` drives the local [imsg](https://github.com/openclaw/imsg) tool, which relies on **macOS permissions** (Full Disk Access + Automation) granted to the process that launches it. "Authentication" here means: imsg is installed, Messages.app is signed into your Apple ID, and the permissions are granted.
+
+## What gets stored
+
+The credential manager stores an **account record with no secrets** in `~/.config/agent-messenger/imessage-credentials.json` (mode `0600`):
+
+```jsonc
+{
+  "current": "default",
+  "accounts": {
+    "default": {
+      "account_id": "default",
+      "provider": "imsg",          // backend-agnostic discriminator
+      "binary_path": "/opt/homebrew/bin/imsg",  // optional; defaults to "imsg" on PATH
+      "region": "US",               // optional; default region for local-format phone numbers
+      "created_at": "…",
+      "updated_at": "…"
+    }
+  }
+}
+```
+
+There is no password/token field — access is governed entirely by macOS TCC permissions.
+
+## Configuring an account
+
+Guided:
+```bash
+agent-imessage setup            # verifies imsg + permissions (honors --bin/--region), then saves
+```
+
+Scriptable:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current
+agent-imessage auth status      # via: agent-imessage doctor
+agent-imessage auth list
+agent-imessage auth use <account-id>
+agent-imessage auth remove <account-id>
+agent-imessage auth logout      # clears all stored accounts
+```
+
+## Credential resolution order
+
+When a command runs, the active configuration is resolved as:
+
+1. `--account <id>` (explicit account selection), then
+2. `AGENT_IMESSAGE_BIN` / `AGENT_IMESSAGE_REGION` environment variables (runtime override — **never persisted to disk**), then
+3. the stored **current** account, then
+4. defaults (`imsg` on PATH, no region).
+
+If nothing resolves, commands exit with `{ "code": "not_authenticated" }` and point to `agent-imessage setup`.
+
+## Permissions (the real "auth")
+
+imsg needs two macOS permissions, granted to the **parent process** (the terminal / agent runtime that launches `agent-messenger`), not to `imsg` in isolation:
+
+- **Full Disk Access** — to read `~/Library/Messages/chat.db`. Missing → `{ "code": "full_disk_access" }`.
+- **Automation → Messages** — to send. Missing → `{ "code": "automation_denied" }`.
+
+These are user-consent TCC grants and **cannot be scripted**. See [permissions](permissions.md) for the exact steps and the parent-process caveat. Run `agent-imessage doctor` to check status.
+
+## Multi-account
+
+Each account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account per Mac**; multiple accounts are only meaningful if you run distinct imsg setups.

package/skills/agent-imessage/references/permissions.md

@@ -0,0 +1,31 @@
+# macOS Permissions for imsg
+
+`agent-imessage` drives [imsg](https://github.com/openclaw/imsg), which needs two macOS permissions. These are TCC (Transparency, Consent, and Control) grants that **cannot be scripted** — a human must approve them once in System Settings.
+
+## Full Disk Access (required for everything)
+
+imsg reads the Messages database at `~/Library/Messages/chat.db`, which macOS protects behind Full Disk Access.
+
+- **Grant to:** the app/terminal/agent-runtime that launches `agent-messenger` — **the parent process**, not `imsg` alone.
+- **Where:** System Settings → Privacy & Security → Full Disk Access → enable your terminal/app → restart it.
+- **Symptom when missing:** `agent-imessage doctor` reports `full_disk_access: denied`; commands return `{ "code": "full_disk_access" }`.
+
+## Automation → Messages (required to send)
+
+Sending uses AppleScript automation of Messages.app.
+
+- **Grant to:** same parent process.
+- **Where:** System Settings → Privacy & Security → Automation → (your app) → enable **Messages**. macOS prompts automatically on the first send attempt.
+- **Symptom when missing:** sends fail with `{ "code": "automation_denied" }`.
+
+## Contacts (optional)
+
+Used only to resolve sender names. Nothing breaks without it; `from_name` is simply absent.
+
+## Why these can't be automated
+
+TCC grants are deliberately user-consent-only. `tccutil` can reset permissions but cannot grant them, and the TCC database is protected by SIP. There is no supported way to grant Full Disk Access or Automation programmatically on an unmanaged Mac — plan for a one-time manual approval (a quick Screen Sharing/VNC session works for a headless Mac).
+
+## SIP and the advanced bridge
+
+Core features (send/read/watch/standard tapbacks) need **no SIP changes**. Only the advanced bridge (`imsg launch`: typing, edit/unsend, group management, targeted/custom reactions) requires **disabling SIP**, which is a separate, deliberate step and out of scope for the core `agent-imessage` features.

package/skills/agent-imessage/references/setup.md

@@ -0,0 +1,49 @@
+# imsg Setup (Operator Guide)
+
+iMessage has no public API. `agent-imessage` runs **on a Mac** and uses [imsg](https://github.com/openclaw/imsg) — a native Swift CLI — to read the local Messages database and send through Messages.app. The agent must run on the same Mac (imsg is local-only; there is no network/server).
+
+## Requirements
+
+- **macOS 14+** (Sonoma or newer). imsg supports macOS 26/Tahoe with caveats (group sends via AppleScript can fail; imsg reports the failure honestly rather than lying).
+- **Messages.app signed in** to your Apple ID. A **dedicated Apple ID** is recommended to avoid mixing automated traffic with your personal account.
+- **imsg installed**: `brew install steipete/tap/imsg`.
+- **Full Disk Access** and **Automation → Messages** permissions (see below).
+
+## One-time setup
+
+1. **Install imsg**
+   ```bash
+   brew install steipete/tap/imsg
+   imsg --version
+   ```
+2. **Sign Messages.app into iMessage** with your (dedicated) Apple ID.
+3. **Grant Full Disk Access** — System Settings → Privacy & Security → Full Disk Access → add the app/terminal that will launch `agent-messenger`. This is required to read `~/Library/Messages/chat.db`.
+4. **Grant Automation → Messages** — triggered on first send; approve the prompt (System Settings → Privacy & Security → Automation → Messages).
+5. **Verify and save an account**
+   ```bash
+   agent-imessage setup      # guided: checks imsg + permissions, saves account
+   agent-imessage doctor     # re-check anytime
+   ```
+
+### The parent-process permission caveat (important)
+
+macOS grants Full Disk Access and Automation to the **process that launches imsg** — i.e. the terminal, IDE, or agent runtime that runs `agent-imessage`, not `imsg` in isolation. If `doctor` reports `full_disk_access: denied`, grant Full Disk Access to **that launching app** and restart it.
+
+## Feature tiers
+
+- **Core (no SIP):** list/search chats, read history, send text, watch new messages, standard tapbacks (to the most recent incoming message). This is all that `agent-imessage` v1 uses.
+- **Bridge (advanced):** typing indicators, read receipts, edit/unsend, group create/rename/members, and reacting to a *specific* message or with custom emoji. These require `imsg launch` (which injects into IMCore) and **disabling SIP**. Not used by v1; documented for completeness.
+
+## Multi-account
+
+Each `agent-imessage` account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account** per Mac. Configure additional accounts only if you run multiple imsg binaries/setups:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --account home --current
+agent-imessage auth use home
+```
+
+## Reliability notes
+
+- The Mac must stay awake and logged in for live `watch` to keep receiving.
+- imsg's watcher uses filesystem events + polling and re-arms across Messages database (WAL) rotation, so it keeps up on busy/iCloud-synced databases.
+- Pin macOS updates if stability matters — major updates can change AppleScript/IMCore behavior.

package/skills/agent-instagram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-instagram
 description: Interact with Instagram DMs - send messages, read conversations, manage accounts
-version: 2.27.2
+version: 2.28.0
 allowed-tools: Bash(agent-instagram:*)
 metadata:
   openclaw:
@@ -27,7 +27,7 @@ Use one of these entrypoints:
 - **Thread ID** = Instagram's identifier for a DM conversation. Numeric string returned by `chat list`.
 - **Browser cookie extraction** = recommended auth method. Extracts cookies from Chromium browsers (Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium) where you're logged into instagram.com. Zero-config.
 - **Username/password auth** = fallback method. Authenticates using Instagram credentials. Supports two-factor authentication via SMS or authenticator app.
-- **HTTP-based** = each command makes HTTP requests and returns. No persistent connection or background process.
+- **HTTP-based** = each CLI command makes HTTP requests and returns. No persistent connection or background process. The SDK additionally offers real-time listeners (`InstagramHybridListener`, `InstagramRealtimeListener`) for streaming DMs — see [SDK: Real-Time Events](#sdk-real-time-events) below.
 - **Multi-account** = multiple Instagram accounts can be stored. Use `auth list` and `auth use` to switch between them.
 - **DM-only** = this CLI focuses on Instagram Direct Messages. It does not manage posts, stories, or followers.
 
@@ -440,3 +440,73 @@ Instagram invalidates sessions based on device fingerprinting and activity patte
 1. Avoid frequent re-authentication
 2. Space out API calls
 3. Don't switch between multiple IP addresses rapidly
+
+## SDK: Real-Time Events
+
+`InstagramHybridListener` connects over Instagram's MQTToT transport (a persistent TLS connection to `edge-mqtt.facebook.com`) and falls back to polling automatically if the connection fails. It retries realtime with capped exponential backoff. This is the recommended listener for most use cases.
+
+`InstagramRealtimeListener` is the pure-realtime option with no polling fallback — use it when you want direct MQTToT and prefer to handle reconnection yourself.
+
+Both use the unofficial private API, the same risk surface as the existing polling listener.
+
+### Setup
+
+```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
+  realtimeRetryBaseMs: 2000,  // backoff base for realtime reconnect
+  realtimeRetryMaxMs: 60000,  // backoff cap
+})
+```
+
+Or for pure realtime:
+
+```typescript
+import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramRealtimeListener(client)
+```
+
+### Listening for Events
+
+```typescript
+listener.on('connected', ({ userId, transport }) => {
+  // transport is 'realtime' or 'polling' (hybrid only)
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  // msg.id, msg.thread_id, msg.from, msg.timestamp
+  // msg.is_outgoing, msg.type, msg.text, msg.media_url
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('error', (err) => {
+  console.error(err.message)
+})
+
+listener.on('disconnected', () => {
+  // hybrid listener retries realtime automatically
+})
+```
+
+### Lifecycle
+
+```typescript
+await listener.start()  // connects via MQTToT (or starts polling fallback)
+listener.stop()         // clean shutdown
+```
+
+### Event Types
+
+| Event          | Payload (Hybrid)                                          | Payload (Realtime / Polling) | Description                    |
+| -------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------ |
+| `message`      | `InstagramMessageSummary`                                 | `InstagramMessageSummary`    | New DM received                |
+| `connected`    | `{ userId: string; transport: 'realtime' \| 'polling' }` | `{ userId: string }`         | Listener active                |
+| `disconnected` | —                                                         | —                            | Connection closed              |
+| `error`        | `Error`                                                   | `Error`                      | Connection or API error        |