git:20260615.82ecab1 to git:20260819.4ca793d

8 added, 10 removed. Audit A to A.

---

name: setup-imessage-node

description: Guide setting up a Mac as an iMessage node — relays incoming texts to the main agent (trigger word) and answers iMessage searches.

---

Walk the user through turning a Mac (signed into iMessage) into an iMessage node. macOS-only, and it needs system permissions you can't grant for them — so produce clear, copy-pasteable steps and explain each grant. Substitute `<host>`, `<port>`, `<secret>`, `<TriggerWord>` for their values; never hardcode real numbers/tokens.

- Two processes (run from the openAGI repo on that Mac):

- - `openagi imessage-bridge --respond trigger --trigger <TriggerWord> --allow <handle,handle> --allow-chat <chatId> --capture all`

- Reads `~/Library/Messages/chat.db` read-only, relays messages containing the trigger to the main, and replies via Messages. Omit `--allow*` to respond to everyone; `--allow-chat` opts a group thread in.

- - `openagi imessage-server --token <secret> --port <port>` (optional)

- Serves iMessage SEARCH to the main, giving it a `search_imessages` tool.

+ The normal setup is one signed OpenAGI app process, not separate Node services:

+ - Set `OPENAGI_IMESSAGE_BRIDGE=1`, `IMESSAGE_RESPOND=trigger`, and `IMESSAGE_TRIGGER=<TriggerWord>` on the Messages Mac. Optional `IMESSAGE_ALLOW=<handle,handle>` and `IMESSAGE_ALLOW_CHAT=<chatId>` narrow who can invoke it. Ambient capture stays off unless explicitly enabled.

+ - Set `OPENAGI_IMESSAGE_SEARCH=1` only when the user wants the paired main to perform bounded read-only searches. Search travels over the authenticated outbound node relay; do not open an inbound iMessage port.

Steps to give the user:

- 1. Clone/run the openAGI repo on the Mac.

- 2. System Settings → Privacy & Security: grant the runtime that launches these (the `node` binary; Terminal while testing) **Full Disk Access** (read chat.db) and **Automation → Messages** (send replies).

- 3. Run the bridge (and optionally the search server). For persistence install a launchd USER agent (`RunAtLoad` + `KeepAlive`) that runs the command; restart it with `launchctl kickstart -k gui/$(id -u)/<label>`.

- 4. On the MAIN agent host, point at the node: `OPENAGI_IMESSAGE_NODE=http://<host>:<port>` and `OPENAGI_IMESSAGE_NODE_TOKEN=<secret>`, then restart.

+ 1. Install and launch the signed OpenAGI app on the Mac, then pair it to the HTTPS main with `openagi pair <main>` using the documented hidden token input.

+ 2. In OpenAGI Setup, enable the signed-app bridge and optionally history search. Restart OpenAGI so the daemon loads the settings and enrolls its scoped node credential.

+ 3. System Settings → Privacy & Security: grant **OpenAGI.app** Full Disk Access (read chat.db) and **Automation → Messages** (send replies), then restart OpenAGI once more.

+ 4. On the main, verify one fresh node heartbeat and the nested `imessage-search` capability. Send a harmless trigger message and confirm the bridge status records a successful poll before relying on it.

Gotchas to mention:

- chat.db MUST be opened read-only — a read-write connection on the live WAL database can hang/crash Messages.

- On recent macOS the message text often lives only in `attributedBody` (the `text` column is NULL); the bridge decodes that typedstream blob.

- - A process launched by launchd needs its OWN TCC grant — granting Terminal is not enough; the launchd-spawned `node` must be approved separately.

+ - Full Disk Access belongs to a code-signing identity. Do not replace the signed-app bridge with a checkout-specific Node LaunchAgent; that recreates the permission-loss bug on updates.

- Track messages by date, not ROWID (a chat.db rebuild renumbers ROWIDs non-chronologically).

User asked: {{input}}