WebSocket Protocols

Archety/Ikiro uses two WebSocket protocols:

1. Edge Agent WebSocket (/edge/ws) — backend ↔ Mac mini edge relay (../archety-edge)
2. MiniApp WebSocket (/ws/miniapp/{session_id}) — backend ↔ browser MiniApp UI (../archety-web)

---

1) Edge Agent WebSocket (/edge/ws)

Purpose

• Real-time command delivery to the Mac mini edge relay (reflex bubbles, scheduling, context updates, etc.).
• Reduces latency vs HTTP polling via /edge/sync.

Connection

wss://<backend>/edge/ws?edge_agent_id=<edge_agent_id>

Required headers

Authorization: Bearer <edge_token>
X-Edge-Agent-Id: <edge_agent_id>

<edge_token> options (backend: app/edge/auth.py): - Recommended: HMAC-derived Base64 token created by generate_edge_token(edge_agent_id, user_phone). - Legacy fallback: raw EDGE_SECRET (only accepted when ENVIRONMENT != production).

Transport envelope

All messages are JSON:

{ "type": "message_type", "data": { } }

Backend → edge message types

• command — deliver an EdgeCommand
• pong — keepalive response

Edge → backend message types

• ping — keepalive (typically every 30s)
• command_ack — acknowledge a command
• status — periodic health/status update

command payload

Backend sends:

{
  "type": "command",
  "data": {
    "command_id": "uuid",
    "command_type": "send_message_now",
    "payload": {},
    "priority": "immediate",
    "timestamp": "2026-02-16T00:00:00Z"
  }
}

Current command types are defined in app/edge/schemas.py: - send_message_now - schedule_message - set_rule - cancel_scheduled - context_update - context_reset - upload_retry - emit_event

command_ack payload

Edge sends:

{
  "type": "command_ack",
  "data": {
    "command_id": "uuid",
    "status": "completed",
    "error": null
  }
}

Allowed status values: received, executing, completed, failed.

HTTP fallback

If WebSocket is unavailable, edge agents can poll: - POST /edge/sync (see app/api/edge_routes.py)

---

2) MiniApp WebSocket (/ws/miniapp/{session_id})

Purpose

Real-time updates for multiplayer MiniApp sessions in the web UI.

Connection

wss://<backend>/ws/miniapp/<session_id>?token=<jwt>

Authentication

The backend currently requires token=<jwt> as a query parameter and validates it via Supabase JWT verification: - Backend: app/api/websocket_routes.py - JWT verifier: app/dependencies.py::verify_jwt_token

Message types

Backend sends: - connected — initial confirmation + connection count - presence — peers joined/left - state_update — state diffs (server or peer sourced) - action — peer actions (for optimistic sync) - pong — heartbeat response

Client sends: - ping - state_update - action - typing