clawbrah 1.0.1

package/docs/channels/bluebubbles.md

@@ -0,0 +1,338 @@
+---
+summary: "iMessage via BlueBubbles macOS server (REST send/receive, typing, reactions, pairing, advanced actions)."
+read_when:
+  - Setting up BlueBubbles channel
+  - Troubleshooting webhook pairing
+  - Configuring iMessage on macOS
+title: "BlueBubbles"
+---
+
+# BlueBubbles (macOS REST)
+
+Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel.
+
+## Overview
+
+- Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)).
+- Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync.
+- OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
+- Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
+- Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
+- Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
+- Reactions are surfaced as system events just like Slack/Telegram so agents can "mention" them before replying.
+- Advanced features: edit, unsend, reply threading, message effects, group management.
+
+## Quick start
+
+1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
+2. In the BlueBubbles config, enable the web API and set a password.
+3. Run `openclaw onboard` and select BlueBubbles, or configure manually:
+   ```json5
+   {
+     channels: {
+       bluebubbles: {
+         enabled: true,
+         serverUrl: "http://192.168.1.100:1234",
+         password: "example-password",
+         webhookPath: "/bluebubbles-webhook",
+       },
+     },
+   }
+   ```
+4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
+5. Start the gateway; it will register the webhook handler and start pairing.
+
+## Keeping Messages.app alive (VM / headless setups)
+
+Some macOS VM / always-on setups can end up with Messages.app going “idle” (incoming events stop until the app is opened/foregrounded). A simple workaround is to **poke Messages every 5 minutes** using an AppleScript + LaunchAgent.
+
+### 1) Save the AppleScript
+
+Save this as:
+
+- `~/Scripts/poke-messages.scpt`
+
+Example script (non-interactive; does not steal focus):
+
+```applescript
+try
+  tell application "Messages"
+    if not running then
+      launch
+    end if
+
+    -- Touch the scripting interface to keep the process responsive.
+    set _chatCount to (count of chats)
+  end tell
+on error
+  -- Ignore transient failures (first-run prompts, locked session, etc).
+end try
+```
+
+### 2) Install a LaunchAgent
+
+Save this as:
+
+- `~/Library/LaunchAgents/com.user.poke-messages.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>com.user.poke-messages</string>
+
+    <key>ProgramArguments</key>
+    <array>
+      <string>/bin/bash</string>
+      <string>-lc</string>
+      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/poke-messages.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/poke-messages.err</string>
+  </dict>
+</plist>
+```
+
+Notes:
+
+- This runs **every 300 seconds** and **on login**.
+- The first run may trigger macOS **Automation** prompts (`osascript` → Messages). Approve them in the same user session that runs the LaunchAgent.
+
+Load it:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
+launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
+```
+
+## Onboarding
+
+BlueBubbles is available in the interactive setup wizard:
+
+```
+openclaw onboard
+```
+
+The wizard prompts for:
+
+- **Server URL** (required): BlueBubbles server address (e.g., `http://192.168.1.100:1234`)
+- **Password** (required): API password from BlueBubbles Server settings
+- **Webhook path** (optional): Defaults to `/bluebubbles-webhook`
+- **DM policy**: pairing, allowlist, open, or disabled
+- **Allow list**: Phone numbers, emails, or chat targets
+
+You can also add BlueBubbles via CLI:
+
+```
+openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
+```
+
+## Access control (DMs + groups)
+
+DMs:
+
+- Default: `channels.bluebubbles.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `openclaw pairing list bluebubbles`
+  - `openclaw pairing approve bluebubbles <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+
+Groups:
+
+- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
+- `channels.bluebubbles.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+
+### Mention gating (groups)
+
+BlueBubbles supports mention gating for group chats, matching iMessage/WhatsApp behavior:
+
+- Uses `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) to detect mentions.
+- When `requireMention` is enabled for a group, the agent only responds when mentioned.
+- Control commands from authorized senders bypass mention gating.
+
+Per-group configuration:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true }, // default for all groups
+        "iMessage;-;chat123": { requireMention: false }, // override for specific group
+      },
+    },
+  },
+}
+```
+
+### Command gating
+
+- Control commands (e.g., `/config`, `/model`) require authorization.
+- Uses `allowFrom` and `groupAllowFrom` to determine command authorization.
+- Authorized senders can run control commands even without mentioning in groups.
+
+## Typing + read receipts
+
+- **Typing indicators**: Sent automatically before and during response generation.
+- **Read receipts**: Controlled by `channels.bluebubbles.sendReadReceipts` (default: `true`).
+- **Typing indicators**: OpenClaw sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      sendReadReceipts: false, // disable read receipts
+    },
+  },
+}
+```
+
+## Advanced actions
+
+BlueBubbles supports advanced message actions when enabled in config:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      actions: {
+        reactions: true, // tapbacks (default: true)
+        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
+        unsend: true, // unsend messages (macOS 13+)
+        reply: true, // reply threading by message GUID
+        sendWithEffect: true, // message effects (slam, loud, etc.)
+        renameGroup: true, // rename group chats
+        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
+        addParticipant: true, // add participants to groups
+        removeParticipant: true, // remove participants from groups
+        leaveGroup: true, // leave group chats
+        sendAttachment: true, // send attachments/media
+      },
+    },
+  },
+}
+```
+
+Available actions:
+
+- **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`)
+- **edit**: Edit a sent message (`messageId`, `text`)
+- **unsend**: Unsend a message (`messageId`)
+- **reply**: Reply to a specific message (`messageId`, `text`, `to`)
+- **sendWithEffect**: Send with iMessage effect (`text`, `to`, `effectId`)
+- **renameGroup**: Rename a group chat (`chatGuid`, `displayName`)
+- **setGroupIcon**: Set a group chat's icon/photo (`chatGuid`, `media`) — flaky on macOS 26 Tahoe (API may return success but the icon does not sync).
+- **addParticipant**: Add someone to a group (`chatGuid`, `address`)
+- **removeParticipant**: Remove someone from a group (`chatGuid`, `address`)
+- **leaveGroup**: Leave a group chat (`chatGuid`)
+- **sendAttachment**: Send media/files (`to`, `buffer`, `filename`, `asVoice`)
+  - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
+
+### Message IDs (short vs full)
+
+OpenClaw may surface _short_ message IDs (e.g., `1`, `2`) to save tokens.
+
+- `MessageSid` / `ReplyToId` can be short IDs.
+- `MessageSidFull` / `ReplyToIdFull` contain the provider full IDs.
+- Short IDs are in-memory; they can expire on restart or cache eviction.
+- Actions accept short or full `messageId`, but short IDs will error if no longer available.
+
+Use full IDs for durable automations and storage:
+
+- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
+- Context: `MessageSidFull` / `ReplyToIdFull` in inbound payloads
+
+See [Configuration](/gateway/configuration) for template variables.
+
+## Block streaming
+
+Control whether responses are sent as a single message or streamed in blocks:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      blockStreaming: true, // enable block streaming (off by default)
+    },
+  },
+}
+```
+
+## Media + limits
+
+- Inbound attachments are downloaded and stored in the media cache.
+- Media cap via `channels.bluebubbles.mediaMaxMb` (default: 8 MB).
+- Outbound text is chunked to `channels.bluebubbles.textChunkLimit` (default: 4000 chars).
+
+## Configuration reference
+
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+
+- `channels.bluebubbles.enabled`: Enable/disable the channel.
+- `channels.bluebubbles.serverUrl`: BlueBubbles REST API base URL.
+- `channels.bluebubbles.password`: API password.
+- `channels.bluebubbles.webhookPath`: Webhook endpoint path (default: `/bluebubbles-webhook`).
+- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
+- `channels.bluebubbles.allowFrom`: DM allowlist (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`).
+- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
+- `channels.bluebubbles.groupAllowFrom`: Group sender allowlist.
+- `channels.bluebubbles.groups`: Per-group config (`requireMention`, etc.).
+- `channels.bluebubbles.sendReadReceipts`: Send read receipts (default: `true`).
+- `channels.bluebubbles.blockStreaming`: Enable block streaming (default: `false`; required for streaming replies).
+- `channels.bluebubbles.textChunkLimit`: Outbound chunk size in chars (default: 4000).
+- `channels.bluebubbles.chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking.
+- `channels.bluebubbles.mediaMaxMb`: Inbound media cap in MB (default: 8).
+- `channels.bluebubbles.historyLimit`: Max group messages for context (0 disables).
+- `channels.bluebubbles.dmHistoryLimit`: DM history limit.
+- `channels.bluebubbles.actions`: Enable/disable specific actions.
+- `channels.bluebubbles.accounts`: Multi-account configuration.
+
+Related global options:
+
+- `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`).
+- `messages.responsePrefix`.
+
+## Addressing / delivery targets
+
+Prefer `chat_guid` for stable routing:
+
+- `chat_guid:iMessage;-;+15555550123` (preferred for groups)
+- `chat_id:123`
+- `chat_identifier:...`
+- Direct handles: `+15555550123`, `user@example.com`
+  - If a direct handle does not have an existing DM chat, OpenClaw will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled.
+
+## Security
+
+- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
+- Keep the API password and webhook endpoint secret (treat them like credentials).
+- Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure `gateway.trustedProxies`. See [Gateway security](/gateway/security#reverse-proxy-configuration).
+- Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
+
+## Troubleshooting
+
+- If typing/read events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`.
+- Pairing codes expire after one hour; use `openclaw pairing list bluebubbles` and `openclaw pairing approve bluebubbles <code>`.
+- Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it.
+- Edit/unsend require macOS 13+ and a compatible BlueBubbles server version. On macOS 26 (Tahoe), edit is currently broken due to private API changes.
+- Group icon updates can be flaky on macOS 26 (Tahoe): the API may return success but the new icon does not sync.
+- OpenClaw auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
+- For status/health info: `openclaw status --all` or `openclaw status --deep`.
+
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugins) guide.

package/docs/channels/brah-sync.md

@@ -0,0 +1,92 @@
+---
+summary: "Brah-Sync channel — chat via brah-portal through the tracker"
+read_when:
+  - You want to use Agent Chat from the brah-portal with your own LLM
+  - You are setting up the brah-sync extension for claw-brah
+title: "Brah-Sync"
+---
+
+# Brah-Sync (Portal Chat)
+
+Status: production-ready when tracker chat API and extension are enabled. Uses polling (no webhooks). **Same setup on Windows (MSI) and macOS (DMG):** if you install Brah Sync via the MSI or DMG installer and run "Configure Brah (ClawBrah)", the brah-sync channel is configured automatically so Agent Chat works.
+
+## What it is
+
+Brah-Sync lets you chat with your agent from the **brah-portal** (the web UI). Messages flow: you type in the portal → tracker stores them → the brah-sync extension polls the tracker → your agent replies → the extension posts replies back to the tracker → the portal shows them. Same idea as linking Telegram or WhatsApp: your messages from one place, agent replies from your configured LLM.
+
+- **Portal:** User creates sessions and sends messages (authenticated with peer API key).
+- **Tracker:** Stores sessions and messages; exposes portal endpoints and extension-only endpoints (pending, reply).
+- **Extension:** Polls for pending messages, builds context, calls the agent via `dispatchReplyFromConfig`, and POSTs reply chunks to the tracker.
+
+## Quick setup
+
+1. **Tracker:** Ensure the tracker has run migrations (chat tables `chat_sessions`, `chat_messages`). No extra env vars.
+2. **API key:** Use the **peer API key** (returned on first tracker register). Chat does not accept guest keys; the portal and the extension must use the same peer key so they see the same sessions.
+3. **Claw-brah:** Enable the brah-sync plugin and set `channels.brah-sync` in config:
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "brah-sync": { "enabled": true }
+    }
+  },
+  "channels": {
+    "brah-sync": {
+      "enabled": true,
+      "trackerUrl": "http://localhost:7842",
+      "apiKey": "<your-peer-api-key>",
+      "pollIntervalMs": 3000
+    }
+  }
+}
+```
+
+4. Start the gateway; the extension will start polling. Open the portal, go to Agent Chat, create a session and send a message; the agent should reply.
+
+## Configuration
+
+| Field | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `enabled` | boolean | `true` | Turn the channel on or off. |
+| `trackerUrl` | string | `http://localhost:7842` | Base URL of the brah-sync tracker. |
+| `apiKey` | string | — | **Required.** Peer API key (from tracker register). Must match the portal; guest keys are not accepted for chat. |
+| `pollIntervalMs` | number | `3000` | How often (ms) the extension polls for pending messages. |
+
+The **peer API key** is returned by the tracker when the daemon first registers (`POST /api/v1/tracker/register`); the daemon or installer should persist it. Use that key in the portal and in `channels.brah-sync.apiKey`. A **guest key** (`POST /api/v1/portal/guest-key`) creates an account and grants default credits on the same ledger; it is used for Brah LLM completions and installer onboarding, not for chat.
+
+**Credit system:** Guest keys and peer keys share one credit ledger. The tracker exposes `POST /api/v1/brah/completions` for Brah LLM calls: send `X-API-Key` or `Authorization: Bearer <key>`, and the tracker resolves the key to an account, deducts credits, and proxies to the real LLM. On insufficient credits the tracker returns **402**; the client should prompt the user to top up (e.g. in Settings). The endpoint is rate-limited (e.g. 120 req/min per IP). Point claw-brah’s Brah provider `baseUrl` at the tracker (e.g. `http://localhost:7842/api/v1`) so completions hit the tracker directly.
+
+**Guest key vs peer key — two accounts:** A **guest key** (from `POST /api/v1/portal/guest-key`) is tied to a *guest* account. A **peer key** (from daemon registration) is tied to a *peer* account; the **portal** and daemon use it for balance, purchase, and Agent Chat. **MSI install:** The post-install script gets the daemon’s peer key (`GET /api/v1/installer/peer-key`, localhost-only) and runs ClawBrah onboard with it, so desktop Brah and portal share one account and one balance; reinstall does not create a new account or grant extra credits. If you onboard manually with a guest key instead, desktop and portal use two separate balances until linked.
+
+## Flow
+
+1. **Portal** → User sends message → `POST /api/chat/sessions/:id/messages` (with `X-API-Key`).
+2. **Tracker** → Stores message with `sender: "user"`, `status: "pending"`.
+3. **Extension** → Periodically calls `GET /api/chat/messages/pending?since=...` with `X-API-Key`.
+4. **Extension** → For each pending message, builds message context and calls `dispatchReplyFromConfig` with a reply dispatcher.
+5. **Agent** → Generates reply (streaming chunks).
+6. **Extension** → Dispatcher POSTs each chunk to `POST /api/chat/messages/:id/reply`.
+7. **Tracker** → Appends brah message and marks user message as `replied`.
+8. **Portal** → User refreshes or polls `GET /api/chat/sessions/:id/messages` and sees the reply.
+
+## Troubleshooting
+
+- **No replies in the portal:** Check that the extension is running (gateway channel status for brah-sync). Ensure `channels.brah-sync.apiKey` is the same peer API key the portal uses for that user.
+- **401 Unauthorized:** Missing or invalid `X-API-Key`. For the extension, set `apiKey` in config. For the portal, set the API key in the app config (e.g. installer or env).
+- **Tracker unreachable:** Confirm `trackerUrl` is correct and the tracker is running. Check CORS if the portal is on a different origin.
+- **Polling too slow:** Increase frequency by lowering `pollIntervalMs` (e.g. 2000). Very low values add load on the tracker.
+
+## Windows (MSI) and macOS (DMG)
+
+The same flow works on both platforms:
+
+- **Windows:** Install Brah Sync via the MSI, then run the "Configure Brah (ClawBrah)" shortcut. The script calls the daemon at `GET /api/v1/installer/peer-key` (localhost-only) to get the **peer API key** and tracker URL, then runs `npx clawbrah onboard --brah` with that key. ClawBrah is tied to the same peer profile as the portal (one account); reinstall does not grant extra credits.
+- **macOS:** Install Brah Sync via the DMG and run the install/configure step; same onboarding configures the channel. No platform-specific steps.
+
+The extension and tracker use no OS-specific paths; config is in the standard claw-brah config file (and auth store for the Brah model).
+
+## See also
+
+- [REST API (Chat API)](https://github.com/brahsync/brahsync/blob/main/docs/api/REST-API.md#chat-api) — Tracker chat endpoints.
+- [Brah-Sync extension README](/extensions/brah-sync/README.md) — Extension install and config summary.