WebSocket Endpoints
Connection Parameters
Browser Extension / Desktop App
Client ID. Format:
user_{user_id} (browser extension) or desktop_{user_id} (desktop app). The server automatically parses and extracts the user_id.Node ID that uniquely identifies the device. If not provided, the server auto-generates one (
ext_{user_id} or desktop_{user_id}).Web Client
Connection Lifecycle
Message Types
1. Node Registration (register)
After connecting, browser extensions and desktop apps should send aregister message to register node information:
Client → Server:
2. Heartbeat
Nodes send periodic heartbeats to maintain connection status. The server updates the node state in NodeManager. Client → Server:3. Ping/Pong Keepalive
All three client types (Extension, Desktop, Web) support ping/pong keepalive: Client → Server:For Extension and Desktop clients,
ping messages also trigger a NodeManager heartbeat update.4. Tool Calls (JSON-RPC 2.0)
The server sends JSON-RPC 2.0 requests to nodes via WebSocket to invoke tools. This follows the MCP (Model Context Protocol) format. Server → Client (Request):MCP Result Content Types
Each item in theresult.content array can be:
When parsing responses, the server extracts
text, image, and _screenshot fields, and maps isError to a success status. Default timeout is 60 seconds.5. Legacy MCP Response (mcp_response)
6. Status Update
Clients can send status update messages:7. Workflow Execution
Web Client Requests Workflow List
Web Client → Server:workflows_list response from the extension is automatically relayed to the web client. If the extension is not connected:
Web Client Executes Workflow
Web Client → Server:task_complete message, the server notifies the web client:
Extension Workflow Completion
Extension → Server:Default timeout for workflow execution is 300 seconds (5 minutes).
Error Handling
Connection Rejection
The server closes the connection when required parameters are missing:Disconnection Handling
When a WebSocket connection drops, the server automatically:- Removes the connection from ConnectionManager
- Unregisters the node from NodeManager (Extension/Desktop)
- Cleans up all pending requests
ConnectionManager API
ConnectionManager is the core singleton of the WebSocket Gateway, managing the lifecycle of all connections.
Connection Management
Connection Queries
Message Sending
Tool Calls
Connection Stats (get_stats)
Data Structures
Multi-Node Connection Model
ConnectionManager uses nested dictionaries to manage connections, supporting multiple nodes per user:- Extension / Desktop: Each user can connect multiple nodes (multiple devices), distinguished by
node_id - Web: Each user can have multiple web client connections (multiple tabs), stored in a Set