BlueBubbles: native iMessage voice memo support + inbound webhook dedup

[cypres0099]

Summary

Three related fixes to the BlueBubbles adapter that together make iMessage voice memos work end-to-end and eliminate duplicate inbound turn processing. Each is a standalone commit so they can be cherry-picked or split during review.

The three changes

1. Route voice memos through the `private-api` send path

iMessage only renders an attachment as a voice bubble (waveform + play button) when the underlying IMCore send carries the voice-memo marker. The AppleScript send path in BlueBubbles-server doesn't set this marker -- only the Private API send path does. Setting `method="private-api"` in `_send_attachment` when `is_audio_message=True` fixes this.

Without this change, audio attachments always arrive as generic file attachments even with a correct codec and the `isAudioMessage` flag. See the BlueBubbles adapter source (`packages/server/src/server/api/apple/actions.ts`): the AppleScript `sendMessage` path never forwards `isAudioMessage` into the AppleScript itself.

2. Transcode audio to Opus-in-CAF before voice send

iMessage's voice-memo renderer specifically requires Opus codec inside a CAF container -- MP3, AAC, and PCM-in-CAF all fall back to generic file rendering. BlueBubbles-server's own `convertMp3ToCaf` helper currently produces PCM-in-CAF (tracked in BlueBubblesApp/bluebubbles-server#793), and callers shipping any other audio format (AAC, WAV, Opus-in-OGG) never trigger the converter at all.

This pre-converts anything non-.caf to Opus-in-CAF via `afconvert`, the native macOS tool. Ships on every macOS version BlueBubbles-server runs on, so no new dependency. On conversion failure, the original path is sent unchanged -- matches today's fallback behavior.

Mirrors the Opus-in-OGG transcode `tools/tts_tool.py` already does for Telegram voice messages, just targeting CAF instead of OGG.

3. Dedup inbound webhook events by message guid

BlueBubbles fires more than one webhook per iMessage in several conditions:

• A `new-message` event followed ~1s later by an `updated-message` event for the same guid (delivery receipt / edit / reaction notification).
• Group-chat fanout: when the local user participates in both a DM and a group, a single inbound can trigger webhooks carrying different chat GUIDs (e.g. `any;-;+phone` and `+phone`) but the same message guid.
• Reconnect / retry paths where BlueBubbles redelivers recent events.

Without dedup, each duplicate webhook produced an independent agent turn -- most visibly: a voice memo landing in the DM and a separate text reply landing in the group chat, both triggered by one user send.

This adds a small in-memory LRU (guid -> monotonic timestamp, 60s TTL) that short-circuits the handler if the guid has already been processed. At-least-once delivery is the norm for HTTP webhooks; idempotent handling on the receiver is the right place to solve this rather than trying to suppress duplicates upstream (which would also lose legitimate edit/receipt signal on future `updated-message` handling).

Testing

Verified end-to-end on Apple Silicon macOS 26.3, Hermes v0.10.0 native install, BlueBubbles-server v1.9.9 with Private API helper connected:

1. Send TTS-generated audio via adapter's `send_voice` → iMessage renders as a waveform voice bubble with play button on the receiving device.
2. Send user message from phone → one inbound turn, one agent response, even though BlueBubbles fires two webhooks (`new-message` + `updated-message`) ~1s apart. Debug log shows `dropping duplicate webhook for guid ...`.
3. Non-audio attachments (images, videos, documents) unchanged -- still use server-default send method.

Prerequisites for end users

Voice memos require the BlueBubbles Private API Helper to be connected (`helper_connected: true` in `/api/v1/server/info`). On Apple Silicon macOS 14+, this means:

1. Boot into 1 True Recovery (hold power button, Options → Continue while holding Left Shift)
2. Startup Security Utility → Reduced Security
3. Recovery Terminal: `csrutil enable --without debug`
4. In normal macOS: `sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true`
5. Quit and reopen BlueBubbles; it will inject the helper dylib into Messages.app

Users without Private API see the same fallback behavior as today (voice send lands as a file attachment), so there's no regression for the non-Private-API path.

Related

• BlueBubblesApp/bluebubbles-server#793 -- fixes the PCM-in-CAF codec bug in BB's own converter. This PR is still valuable after fix: Explicitly mention shell/terminal access in default identity #793 merges because it covers callers that ship non-MP3 audio and provides belt-and-suspenders on the codec.

[mwhuss]

Would love to get the de-dup fix here.

[cypres0099]

Closing this older bundled branch in favor of the dedup-only replacement in #47262. That keeps the maintainer-requested BlueBubbles webhook de-dup fix isolated from the unrelated voice-memo send/transcode work.