WebSocket Protocol

All real-time communication in MiraBridge uses WebSocket with a typed message protocol.

Connection Lifecycle#

1. Connect — client establishes WebSocket connection to Gateway
2. Hello — client sends authentication message with JWT token and device info
3. Acknowledged — Gateway validates token and registers the device
4. Active — bidirectional message exchange
5. Disconnect — graceful close or timeout

Message Format#

Every message follows this structure:

{
  "type": "ai.chat.stream",
  "payload": { ... },
  "messageId": "uuid-v4",
  "timestamp": 1711234567890
}

Key Message Types#

| Category | Types | Purpose | |----------|-------|---------| | Streaming | ai.chat.stream, ai.stream.chunk, ai.stream.complete | AI responses | | Plan Mode | ai.plan.generate, ai.plan.generated, ai.plan.accept | Planning | | Tools | tool.execute, tool.result, tool.approval | Tool execution | | Cascade | cascade.flow.start, cascade.step.complete | Multi-step flows | | Debug | debug.start, debug.step, debug.complete | Debug mode | | Arena | arena.start, arena.result | Model comparison |

Authentication#

WebSocket connections authenticate via a hello message containing the JWT access token. The Gateway validates the token and associates the connection with the user's device registry.

Next Steps#

• API Reference — REST API endpoints
• Codex Bridge — Codex protocol translation