Files

Move troubleshooting and implementation docs to docs/

Relocate 30 non-essential .md files (investigation notes, fix summaries,
implementation details, status reports) from the project root into docs/
to reduce clutter. Core operational docs (README, quickstart guides,
configuration references) remain in the root.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-07 13:40:46 -05:00

2.2 KiB

Raw Permalink Blame History

Kosmi WebSocket Protocol Findings

Key Discoveries from Browser Monitoring

Room ID Format

Browser uses "@hyperspaceout" (WITH @ symbol) for all operations
Our script was using "hyperspaceout" (WITHOUT @) - this is why joinRoom failed with ROOM_NOT_FOUND

Page Load Sequence

The browser does NOT call joinRoom mutation. Instead, it:

Connects to WebSocket at wss://engine.kosmi.io/gql-ws
Sends connection_init with auth token
Immediately starts subscribing to various topics:
- OnNewMessage(roomId: "@hyperspaceout") - for chat messages
- OnLinkedMembers(roomId: "@hyperspaceout") - for room members
- OnMediaPlayerUpdateState(roomId: "@hyperspaceout") - for media player
- OnMediaPlayerUpdateSubtitles(roomId: "@hyperspaceout") - for subtitles
- OnMediasoupUpdate(roomId: "@hyperspaceout") - for WebRTC
- OnRoomUpdate(roomId: "@hyperspaceout") - for room state
- OnMessageReadersUpdate(roomId: "@hyperspaceout") - for read receipts

Sending Messages

To send a message, the browser likely uses:

mutation SendMessage($body: String!, $roomId: String!) {
  sendMessage(body: $body, roomId: $roomId) {
    ok
  }
}

With variables:

{
  "body": "message text",
  "roomId": "@hyperspaceout"
}

Authentication

The connection_init payload includes:

token: JWT from anonLogin mutation
ua: Base64-encoded User-Agent
v: App version "4364"
r: Empty string for anonymous users

Next Steps

✅ Use "@hyperspaceout" (with @) instead of "hyperspaceout"
✅ Skip the joinRoom mutation entirely
✅ Just send the sendMessage mutation directly after connection_ack
Test if the message appears in chat

Important Note

The sendMessage mutation returns { ok: true } even when the message doesn't appear in chat. This suggests that:

The mutation succeeds on the server side
But the message might be filtered or not broadcast
Possibly because we're not "subscribed" to the room's message feed
Or because anonymous users have restrictions

We should subscribe to OnNewMessage to see if our sent messages come back through the subscription.

2.2 KiB Raw Permalink Blame History