pi-imessage 0.2.0

package/README.md

@@ -0,0 +1,84 @@
+# iMessage
+
+Connect iMessage to your Pi assistant. Reads `~/Library/Messages/chat.db` directly for history, search, and new-message detection; sends via AppleScript to Messages.app. No external server, no background process to keep alive.
+
+macOS only.
+
+## Quick setup
+> Default: text yourself. Other senders are dropped silently (no auto-reply) until you allowlist them. See [ACCESS.md](./ACCESS.md) for groups and multi-user setups.
+
+**1. Grant Full Disk Access.**
+
+`chat.db` is protected by macOS TCC. The first time the server reads it, macOS pops a prompt asking if your terminal can access Messages — click **Allow**. The prompt names whatever app launched bun (Terminal.app, iTerm, Ghostty, your IDE).
+
+If you click Don't Allow, or the prompt never appears, grant it manually: **System Settings → Privacy & Security → Full Disk Access** → add your terminal. Without this the server exits immediately with `authorization denied`.
+
+**2. Install the plugin.**
+
+These are Pi commands — run `pi` to start a session first.
+
+Install the plugin. No env vars required.
+```
+/plugin install imessage
+```
+
+**3. Relaunch with the channel flag.**
+
+The server won't connect without this — exit your session and start a new one:
+
+```sh
+pi --channels plugin:imessage
+```
+
+Check that `/imessage:status` tab-completes.
+
+**4. Text yourself.**
+
+iMessage yourself from any device. It reaches the assistant immediately — self-chat bypasses access control.
+
+> The first outbound reply triggers an **Automation** permission prompt ("Terminal wants to control Messages"). Click OK.
+
+**5. Decide who else gets in.**
+
+Nobody else's texts reach the assistant until you add their handle:
+
+```
+/imessage:access allow +15551234567
+```
+
+Handles are phone numbers (`+15551234567`) or Apple ID emails (`them@icloud.com`). If you're not sure what you want, ask iMessage to review your setup.
+
+## How it works
+
+| | |
+| --- | --- |
+| **Inbound** | Polls `chat.db` once a second for `ROWID > watermark`. Watermark initializes to `MAX(ROWID)` at boot — old messages aren't replayed on restart. |
+| **Outbound** | `osascript` with `tell application "Messages" to send …`. Text and chat GUID pass through argv so there's no escaping footgun. |
+| **History & search** | Direct SQLite queries against `chat.db`. Full history — not just messages since the server started. |
+| **Attachments** | `chat.db` stores absolute filesystem paths. The first inbound image per message is surfaced to the assistant as a local path it can `Read`. Outbound attachments send as separate messages after the text. |
+
+## Environment variables
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `IMESSAGE_APPEND_SIGNATURE` | `true` | Appends `\nSent by iMessage` to outbound messages. Set to `false` to disable. |
+| `IMESSAGE_ALLOW_SMS` | `false` | Accept inbound SMS/RCS in addition to iMessage. **Off by default because SMS sender IDs are spoofable** — a forged SMS from your own number would otherwise bypass access control. Only enable if you understand the risk. |
+| `IMESSAGE_ACCESS_MODE` | — | Set to `static` to disable runtime pairing and read `access.json` only. |
+| `IMESSAGE_STATE_DIR` | `~/.pi/agent/imessage` | Override where `access.json` and pairing state live. |
+
+## Access control
+
+See **[ACCESS.md](./ACCESS.md)** for DM policies, groups, self-chat, delivery config, skill commands, and the `access.json` schema.
+
+Quick reference: IDs are **handle addresses** (`+15551234567` or `someone@icloud.com`). Default policy is `allowlist` — this reads your personal `chat.db`. Self-chat always bypasses the gate.
+
+## Tools exposed to the assistant
+
+| Tool | Purpose |
+| --- | --- |
+| `reply` | Send to a chat. `chat_id` + `text`, optional `files` (absolute paths). Auto-chunks text; files send as separate messages. |
+| `chat_messages` | Fetch recent history as conversation threads. Each thread is labelled **DM** or **Group** with its participant list, then timestamped messages (oldest-first). Omit `chat_guid` to see every allowlisted chat at once, or pass one to drill in. Default 100 messages per chat. Reads `chat.db` directly — full native history. |
+
+## What you don't get
+
+AppleScript can send messages but not tapback, edit, or thread — those require Apple's private API. If you need them, look at [BlueBubbles](https://bluebubbles.app) (requires disabling SIP).

package/dist/ACCESS.md

@@ -0,0 +1,142 @@
+# iMessage — Access & Delivery
+
+This channel reads your Messages database (`~/Library/Messages/chat.db`) directly. Every text to this Mac — from any contact, in any chat — reaches the gate. Access control selects which conversations the assistant should see.
+
+Texting yourself always works. **Self-chat bypasses the gate** with no setup: the server learns your own addresses at boot and lets them through unconditionally. For other senders, the default policy is **`allowlist`**: nothing passes until you add the handle with `/imessage:access allow <address>`.
+
+All state lives in `~/.pi/agent/imessage/access.json`. The `/imessage:access` skill commands edit this file; the server re-reads it on every inbound message, so changes take effect without a restart. Set `IMESSAGE_ACCESS_MODE=static` to pin config to what was on disk at boot.
+
+## At a glance
+
+| | |
+| --- | --- |
+| Default policy | `allowlist` |
+| Self-chat | Bypasses the gate; no config needed |
+| Sender ID | Handle address: `+15551234567` or `someone@icloud.com` |
+| Group key | Chat GUID: `iMessage;+;chat…` |
+| Mention quirk | Regex only; iMessage has no structured @mentions |
+| Config file | `~/.pi/agent/imessage/access.json` |
+
+## Self-chat
+
+Open Messages on any device signed into your Apple ID, start a conversation with yourself, and text. It reaches the assistant.
+
+The server identifies your addresses at boot by reading `message.account` and `chat.last_addressed_handle` from `chat.db`. Messages from those addresses skip the gate entirely. To distinguish your input from its own replies — both appear in `chat.db` as from-me — it maintains a 15-second window of recently sent text and matches against it.
+
+## DM policies
+
+`dmPolicy` controls how texts from senders other than you, not on the allowlist, are handled.
+
+| Policy | Behavior |
+| --- | --- |
+| `allowlist` (default) | Drop silently. Safe default for a personal account. |
+| `pairing` | Reply with a pairing code, drop the message. Every contact who texts this Mac will receive one; only use this if very few people have the number. |
+| `disabled` | Drop everything except self-chat, which always bypasses. |
+
+```
+/imessage:access policy pairing
+```
+
+## Handle addresses
+
+iMessage identifies senders by **handle addresses**: either a phone number in `+country` format or the Apple ID email. The form matches what appears at the top of the conversation in Messages.app.
+
+| Contact shown as | Handle address |
+| --- | --- |
+| Phone number | `+15551234567` (keep the `+`, no spaces or dashes) |
+| Email | `someone@icloud.com` |
+
+If the exact form is unclear, check the `chat_messages` tool output or (under `pairing` policy) the pending entry in `access.json`.
+
+```
+/imessage:access allow +15551234567
+/imessage:access allow friend@icloud.com
+/imessage:access remove +15551234567
+```
+
+## Groups
+
+Groups are off by default. Opt each one in individually, keyed on the chat GUID.
+
+Chat GUIDs look like `iMessage;+;chat123456789012345678`. They're not exposed in Messages.app; get them from the `chat_id` field in `chat_messages` tool output or from the server's stderr log when it drops a group message.
+
+```
+/imessage:access group add "iMessage;+;chat123456789012345678"
+```
+
+Quote the GUID; the semicolons are shell metacharacters.
+
+iMessage has **no structured @mentions**. The `@Name` highlight in group chats is presentational styling — nothing in `chat.db` marks it as a mention. With the default `requireMention: true`, the only trigger is a `mentionPatterns` regex match. Set at least one pattern before opting a group in, or no message will ever match.
+
+```
+/imessage:access set mentionPatterns '["^pi\\b", "@assistant"]'
+```
+
+Pass `--no-mention` to process every message in the group, or `--allow addr1,addr2` to restrict which members can trigger it.
+
+```
+/imessage:access group add "iMessage;+;chat123456789012345678" --no-mention
+/imessage:access group add "iMessage;+;chat123456789012345678" --allow +15551234567,friend@icloud.com
+/imessage:access group rm "iMessage;+;chat123456789012345678"
+```
+
+## Delivery
+
+AppleScript can send messages but cannot tapback, edit, or thread-reply; those require private API. Delivery config is correspondingly limited. Set with `/imessage:access set <key> <value>`.
+
+**`textChunkLimit`** sets the split threshold. iMessage has no length cap; chunking is for readability. Defaults to 10000.
+
+**`chunkMode`** chooses the split strategy: `length` cuts exactly at the limit; `newline` prefers paragraph boundaries.
+
+There is no `ackReaction` or `replyToMode` on this channel.
+
+## Skill reference
+
+| Command | Effect |
+| --- | --- |
+| `/imessage:access` | Print current state: policy, allowlist, pending pairings, enabled groups. |
+| `/imessage:access pair a4f91c` | Approve a pending code (relevant only under `pairing` policy). |
+| `/imessage:access deny a4f91c` | Discard a pending code. |
+| `/imessage:access allow +15551234567` | Add a handle. The primary entry point under the default `allowlist` policy. |
+| `/imessage:access remove +15551234567` | Remove from the allowlist. |
+| `/imessage:access policy pairing` | Set `dmPolicy`. Values: `pairing`, `allowlist`, `disabled`. |
+| `/imessage:access group add "iMessage;+;chat…"` | Enable a group. Quote the GUID. Flags: `--no-mention`, `--allow a,b`. |
+| `/imessage:access group rm "iMessage;+;chat…"` | Disable a group. |
+| `/imessage:access set textChunkLimit 5000` | Set a config key: `textChunkLimit`, `chunkMode`, `mentionPatterns`. |
+
+## Config file
+
+`~/.pi/agent/imessage/access.json`. Absent file is equivalent to `allowlist` policy with empty lists: only self-chat passes.
+
+```jsonc
+{
+  // Handling for texts from senders not in allowFrom.
+  // Defaults to allowlist since this reads your personal chat.db.
+  // Self-chat bypasses regardless.
+  "dmPolicy": "allowlist",
+
+  // Handle addresses allowed to reach the assistant.
+  "allowFrom": ["+15551234567", "friend@icloud.com"],
+
+  // Group chats the assistant participates in. Empty object = DM-only.
+  "groups": {
+    "iMessage;+;chat123456789012345678": {
+      // true: respond only on mentionPatterns match.
+      // iMessage has no structured @mentions; regex is the only trigger.
+      "requireMention": true,
+      // Restrict triggers to these senders. Empty = any member (subject to requireMention).
+      "allowFrom": []
+    }
+  },
+
+  // Case-insensitive regexes that count as a mention.
+  // Required for groups with requireMention, since there are no structured mentions.
+  "mentionPatterns": ["^pi\\b", "@assistant"],
+
+  // Split threshold. No length cap; this is about readability.
+  "textChunkLimit": 10000,
+
+  // length = cut at limit. newline = prefer paragraph boundaries.
+  "chunkMode": "newline"
+}
+```