# 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()
```