fix(sdk): reconnect remote conversation websocket

[bozhnyukAlex]

HUMAN:
This fixes a issue in RemoteConversation observed in production: after a transient events WebSocket disconnect, our SDK client stopped receiving live events because WebSocketCallbackClient exited permanently instead of reconnecting.

---

AGENT:

Why

WebSocketCallbackClient used to exit permanently after any ConnectionClosed. For transient WebSocket closes, a RemoteConversation could silently stop receiving live events and only catch up later through REST polling or manual reconciliation.

Summary

• Retry transient WebSocket ConnectionClosed failures with the existing backoff flow instead of exiting the client loop.
• Treat server-side fatal close codes 4001 (auth failure) and 4004 (conversation not found) as non-retryable.
• Reconcile remote events after a replacement WebSocket subscription becomes ready, so events missed while disconnected are merged into the local cache.
• Add regression coverage for retryable close, fatal close, and reconnect reconciliation callback behavior.

Issue Number

Fixes #3983

How to Test

Environment setup:

make build

Targeted WebSocket/reconciliation tests:

uv run pytest tests/sdk/conversation/remote/test_websocket_client.py tests/sdk/conversation/remote/test_websocket_subscription_ready.py

Broader remote conversation SDK tests:

uv run pytest tests/sdk/conversation/remote

Lint/type checks on changed files:

uv run pre-commit run --files openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py tests/sdk/conversation/remote/test_websocket_client.py

Repo lint target:

make lint

Live reconnect smoke test:

I also ran a local smoke script that starts a real websockets.serve(...) server, sends an initial state update, closes the first connection with code 1000, accepts the SDK client's reconnect, sends a second state update, and asserts:

• the server saw two WebSocket connections;
• the SDK callback received state-1 and state-2;
• on_reconnect ran exactly once.

The script printed:

live websocket reconnect smoke passed

Video/Screenshots

N/A. This is SDK transport behavior covered by automated tests and the live reconnect smoke above.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

This PR does not change the agent-server WebSocket API. It uses the existing REST event reconciliation path after reconnect rather than resend_mode=all/since, avoiding duplicate delivery through user callbacks while still repairing the remote event cache.

No docs update: this is an internal SDK transport reliability fix with no user-facing API or configuration changes.

[all-hands-bot]

[Automatic Post]: I have assigned @neubig as a reviewer based on the repository MAINTAINERS file. Thanks in advance for the help!

This comment was posted by an AI agent (OpenHands) on behalf of the user.

[neubig]

Thanks a bunch, I took a look at the code and did some tests, it seems to be working properly.