Summary

This PR delivers a comprehensive BlueBubbles channel integration for iMessage on macOS, making it the recommended approach over the legacy imsg channel. BlueBubbles provides a richer API with full support for modern iMessage features.

BlueBubbles Extension — New Features

Core Messaging

• Full send/receive via BlueBubbles REST API with webhook-based inbound
• Reply threading with replyToMessageGuid support
• Message effects (slam, loud, gentle, invisible-ink, confetti, lasers, fireworks, balloons, heart)
• Typing indicators and read receipts (configurable via sendReadReceipts)
• Text chunking with configurable textChunkLimit (default 4000)
• Block streaming support for response delivery

Advanced Message Actions

• react — Add/remove tapback reactions with emoji mapping
• edit — Edit sent messages (macOS 13+ only, broken on macOS 26 Tahoe)
• unsend — Retract/unsend messages (macOS 13+)
• reply — Reply to specific messages with threading
• sendWithEffect — Send with iMessage effects
• renameGroup — Rename group chats
• setGroupIcon — Set group chat icon/photo (flaky on macOS 26 Tahoe)
• addParticipant / removeParticipant — Manage group members
• leaveGroup — Leave group chats
• sendAttachment — Send media/attachments with multipart upload

Target Addressing

• Phone numbers and email handles (+15555550123, [email protected])
• Chat GUID format (chat_guid:iMessage;-;+15555550123)
• Chat ID format (chat_id:123)
• Chat identifier format (chat_identifier:...)
• UUID and hex chat identifier patterns
• Automatic normalization and DM extraction from chat GUIDs

Access Control

• DM policy: pairing, allowlist, open, disabled
• Group policy: open, allowlist, disabled
• Mention gating for group chats with requireMention
• Command gating for control commands from authorized senders
• Per-group configuration overrides

macOS Version Awareness

• Server info caching with 10-minute TTL
• Auto-detection of macOS 26 (Tahoe) to disable broken edit action
• Graceful degradation for unsupported features

New Files

BlueBubbles Extension (extensions/bluebubbles/src/)

• chat.ts — Edit, unsend, rename, group icon, participant management, typing, read receipts
• attachments.ts — Attachment download and multipart upload send
• media-send.ts — Unified media delivery (URL, path, buffer)
• onboarding.ts — Interactive setup wizard adapter
• probe.ts — Health check probes and server info caching
• targets.ts — Target parsing and normalization (chat_guid, chat_id, handles)

Core Infrastructure

• src/channels/plugins/status-issues/bluebubbles.ts — Status issue detection for clawdbot status
• src/channels/plugins/message-action-names.ts — Added new action names

Test Coverage (4,124 lines of new tests)

• actions.test.ts — 511 lines
• attachments.test.ts — 240 lines
• chat.test.ts — 462 lines
• monitor.test.ts — 1,644 lines
• reactions.test.ts — 393 lines
• send.test.ts — 690 lines
• targets.test.ts — 184 lines

Core Infrastructure Enhancements

Message Action Runner (src/infra/outbound/message-action-runner.ts)

• Added sendAttachment action hydration with base64/URL/path support
• Added setGroupIcon action hydration with media loading
• Filename inference from media source or MIME type
• Data URL normalization for base64 payloads

Message Tool (src/agents/tools/message-tool.ts)

• Dynamic action filtering based on current channel context
• BlueBubbles group actions only shown for group targets
• Channel-specific action descriptions in tool schema

Channel Capabilities (src/channels/plugins/types.core.ts)

• Added edit, unsend, reply, effects, groupManagement capability flags

Config Schema

• Full BlueBubbles provider schema in zod-schema.providers-core.ts
• Actions config with individual toggle flags
• Multi-account support with per-account overrides

UI Updates

macOS App

• BlueBubbles in channel list (ChannelsSettings+ChannelState.swift)
• BlueBubbles in cron job editor channel picker (CronJobEditor.swift)
• GatewayAgentChannel.bluebubbles enum case

Web UI

• BlueBubbles in default channel order
• BlueBubbles in cron job channel dropdown
• Activity-based status detection (shows "Active" when recent inbound)
• Improved checkbox styling in config forms
• anyOf/oneOf schema handling for primitive unions

Documentation

docs/channels/bluebubbles.md — Complete rewrite with:

• Quick start guide with interactive onboarding
• Access control (DMs + groups) with mention gating
• Typing and read receipt configuration
• Advanced actions reference with all parameters
• Configuration reference with all provider options
• Addressing/delivery target formats
• Security notes and troubleshooting

docs/channels/index.md

• BlueBubbles now listed as "Recommended for iMessage"
• iMessage (imsg) marked as legacy

Other Changes

• Reply context formatting — Inbound messages include reply metadata ([Replying to sender id:msgId])
• Outbound message ID tracking — Sent message IDs enqueued as system events
• Group members formatting — Participants shown as name (id) or just id
• Plugin auto-enable — src/config/plugin-auto-enable.ts for channel detection
• Channel dock — src/channels/dock.ts BlueBubbles registration
• Image ops — src/media/image-ops.ts for icon processing
• MIME extensions — src/media/mime.ts extensionForMime helper

Test plan

• pnpm lint && pnpm build — no errors
• pnpm test — all tests pass
• Manual: Configure BlueBubbles via clawdbot onboard
• Manual: Send/receive DM messages
• Manual: Send/receive group messages with mention gating
• Manual: Test reactions (tapbacks)
• Manual: Test reply threading
• Manual: Test message effects
• Manual: Test edit/unsend (macOS 13-15)
• Manual: Verify macOS app shows BlueBubbles
• Manual: Verify web UI shows BlueBubbles status

🤖 Generated with Claude Code