| .. | .. |
|---|
| 2 | 2 | |
|---|
| 3 | 3 | ## High Priority |
|---|
| 4 | 4 | |
|---|
| 5 | | -### Message Send Queue (reliability) |
|---|
| 6 | | -- Queue outgoing messages locally until WebSocket confirms delivery |
|---|
| 7 | | -- Retry on reconnect — messages sent during disconnection/restart aren't lost |
|---|
| 8 | | -- Visual indicator on messages: sending → sent (currently fire-and-forget) |
|---|
| 9 | | -- Daemon restart drops in-flight messages — need client-side persistence |
|---|
| 5 | +### MQTT Protocol Migration — NEXT MAJOR TASK |
|---|
| 6 | +Replace ad-hoc WebSocket protocol with MQTT for reliable, ordered messaging. |
|---|
| 7 | + |
|---|
| 8 | +**Why:** Current protocol has no delivery guarantees, no message ordering, no offline queuing. |
|---|
| 9 | +Messages get lost on daemon restart, duplicated on catch_up, and arrive out of order. |
|---|
| 10 | + |
|---|
| 11 | +**Server (AIBroker):** |
|---|
| 12 | +- Embed MQTT broker (aedes) in daemon alongside existing WebSocket |
|---|
| 13 | +- Topics: `pailot/{sessionId}/out` (server→app), `pailot/{sessionId}/in` (app→server) |
|---|
| 14 | +- System topics: `pailot/sessions`, `pailot/status`, `pailot/typing/{sessionId}` |
|---|
| 15 | +- QoS 1 (at-least-once) for messages, QoS 0 for typing indicators |
|---|
| 16 | +- Retained messages for session list and last screenshot |
|---|
| 17 | +- Clean session=false so broker queues messages for offline clients |
|---|
| 18 | +- Bridge MQTT messages to/from existing AIBP routing |
|---|
| 19 | + |
|---|
| 20 | +**Flutter App:** |
|---|
| 21 | +- Replace WebSocket client with mqtt_client package |
|---|
| 22 | +- Subscribe to `pailot/+/out` for all session messages |
|---|
| 23 | +- Publish to `pailot/{sessionId}/in` for user messages |
|---|
| 24 | +- Message ID-based dedup (MQTT can deliver duplicates with QoS 1) |
|---|
| 25 | +- Ordered by broker — no client-side sorting needed |
|---|
| 26 | +- Offline messages delivered automatically on reconnect |
|---|
| 27 | + |
|---|
| 28 | +**Migration:** |
|---|
| 29 | +- Phase 1: Add MQTT alongside WebSocket, dual-publish |
|---|
| 30 | +- Phase 2: Flutter app switches to MQTT |
|---|
| 31 | +- Phase 3: Remove WebSocket from PAILot gateway |
|---|
| 10 | 32 | |
|---|
| 11 | 33 | ## Pending Features |
|---|
| 12 | 34 | |
|---|
