forked from cleveragents/cleveragents-core
freemo
61dc421975
Implement WebSocketClient for receiving real-time plan update events from a CleverAgents server via WebSocket connection: - Plan update subscription with reconnect/exponential backoff - Event schema for plan status, progress, and log stream updates - Heartbeat/ping handling that resets reconnect counter - Resume from last event ID on reconnect - Event version negotiation - Event de-duplication by event_id via LRU-bounded EventDeduplicator - Ordered delivery guarantees with thread-safe callback dispatch - Configurable reconnect backoff parameters (base, max, max_reconnects) - ConnectionState model tracking lifecycle state - websockets library added to pyproject.toml dependencies - Behave scenarios (16 scenarios, 62 steps) - Robot Framework smoke tests - ASV benchmark for message handling baseline - Reference documentation at docs/reference/server_websocket.md ISSUES CLOSED: #337
65 lines
1.9 KiB
Markdown
65 lines
1.9 KiB
Markdown
# Server WebSocket Client
|
|
|
|
The `WebSocketClient` receives real-time plan update events from a
|
|
CleverAgents server over a WebSocket connection. It supports automatic
|
|
reconnection with exponential backoff, heartbeat handling, resume from
|
|
last event ID, and event de-duplication.
|
|
|
|
## Event Types
|
|
|
|
| Event type | Description |
|
|
|---|---|
|
|
| `plan.status` | Plan lifecycle status change (e.g. running → completed) |
|
|
| `plan.progress` | Progress percentage or phase update |
|
|
| `plan.log` | Log stream entry from the server |
|
|
| `heartbeat` | Server heartbeat ping (resets reconnect counter) |
|
|
|
|
## Reconnect Policy
|
|
|
|
When the connection drops the client reconnects automatically using
|
|
exponential backoff. Parameters are configurable:
|
|
|
|
| Parameter | Default | Description |
|
|
|---|---|---|
|
|
| `backoff_base` | `1.0` | Base delay in seconds |
|
|
| `backoff_max` | `30.0` | Maximum delay in seconds |
|
|
| `max_reconnects` | `10` | Maximum reconnect attempts before giving up |
|
|
|
|
Successful heartbeat reception resets the reconnect attempt counter.
|
|
|
|
## Resume from Last Event ID
|
|
|
|
On reconnect the client sends the last received `event_id` to the
|
|
server so that missed events can be replayed. This ensures no updates
|
|
are lost during transient disconnections.
|
|
|
|
## Event De-duplication
|
|
|
|
The `EventDeduplicator` tracks recently seen `event_id` values in an
|
|
LRU-bounded set. Duplicate events (same `event_id` received more than
|
|
once) are silently dropped.
|
|
|
|
## Event Version Negotiation
|
|
|
|
The client sends its supported event schema version at connection time.
|
|
If the server returns an incompatible version the connection is rejected
|
|
with a `ServerVersionMismatchError`.
|
|
|
|
## Usage
|
|
|
|
```python
|
|
from cleveragents.client.ws_client import WebSocketClient
|
|
|
|
ws = WebSocketClient(
|
|
base_url="wss://server.example.com",
|
|
api_token="tok_...",
|
|
)
|
|
|
|
def on_event(event):
|
|
print(event["event_type"], event.get("data"))
|
|
|
|
ws.subscribe("PLAN001", on_event)
|
|
# Later:
|
|
ws.close()
|
|
```
|