Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: keep the events socket alive across refetches and bound hung handshakes (#16732)

Hiep Lec59a28a2455c
diff --git a/__tests__/contexts/conversation-websocket-context.test.tsx b/__tests__/contexts/conversation-websocket-context.test.tsx
index 3d544c311e..e73cba07ab 100644
--- a/__tests__/contexts/conversation-websocket-context.test.tsx
+++ b/__tests__/contexts/conversation-websocket-context.test.tsx
@@ -10,6 +10,7 @@ import { useBrowserStore } from "#/stores/browser-store";
import { useCommandStore } from "#/stores/command-store";
import { useErrorMessageStore } from "#/stores/error-message-store";
import { useUserConversation } from "#/hooks/query/use-user-conversation";
+import { useWebSocket } from "#/hooks/use-websocket";
import EventService from "#/api/event-service/event-service.api";
import {
getStoredConversationMetadata,
@@ -218,6 +219,83 @@ describe("ConversationWebSocketProvider β€” conversation-scoped event store", ()
);
});
+ it("keeps the events socket up, with its `since` anchor, across background history refetches", async () => {
+ // Arrange: the initial history load resolves; the background refetch stays
+ // in flight so the query sits in `isFetching` while the socket is already
+ // established β€” the state that used to tear the socket down and leave the
+ // conversation stuck at "Connecting".
+ const historyPage = () => ({
+ items: [createUserMessageEvent("user-msg-conv-refetch")],
+ next_page_id: null,
+ });
+ let resolveRefetch!: (
+ page: Awaited<ReturnType<typeof EventService.searchEvents>>,
+ ) => void;
+ vi.spyOn(EventService, "searchEvents")
+ .mockResolvedValueOnce(historyPage())
+ .mockImplementationOnce(
+ () =>
+ new Promise<Awaited<ReturnType<typeof EventService.searchEvents>>>(
+ (resolve) => {
+ resolveRefetch = resolve;
+ },
+ ),
+ );
+
+ render(
+ <QueryClientProvider client={queryClient}>
+ <ConversationWebSocketProvider
+ conversationId="conv-refetch"
+ conversationUrl="http://localhost/api"
+ >
+ <div />
+ </ConversationWebSocketProvider>
+ </QueryClientProvider>,
+ );
+ await waitFor(() => expect(wsCapture.mainOptions).not.toBeNull());
+
+ // Every render's main-socket call (the one carrying `resend_mode`),
+ // including any teardown call with an empty URL.
+ const mainCalls = () =>
+ vi
+ .mocked(useWebSocket)
+ .mock.calls.filter(
+ ([, options]) =>
+ options?.queryParams && "resend_mode" in options.queryParams,
+ );
+ const connectedAt = mainCalls().length;
+ const anchor = wsCapture.mainOptions?.queryParams?.after_timestamp;
+ expect(anchor).toBeTruthy();
+
+ // Act: a background refetch starts (as `refetchOnMount: "always"` fires
+ // when returning to a conversation) and stays in flight.
+ act(() => {
+ void queryClient.refetchQueries({ queryKey: ["conversation-history"] });
+ });
+ await waitFor(() =>
+ expect(
+ queryClient.isFetching({ queryKey: ["conversation-history"] }),
+ ).toBe(1),
+ );
+
+ // Assert: since the socket connected, no render tore it down (empty URL)
+ // and none degraded the `since` anchor to a full resend.
+ for (const [url, options] of mainCalls().slice(connectedAt - 1)) {
+ expect(url).toContain("/sockets/events/conv-refetch");
+ expect(options?.queryParams).toMatchObject({
+ resend_mode: "since",
+ after_timestamp: anchor,
+ });
+ }
+
+ // The refetch settling must not churn the socket either.
+ await act(async () => {
+ resolveRefetch(historyPage());
+ });
+ const [urlAfterRefetch] = mainCalls().at(-1)!;
+ expect(urlAfterRefetch).toContain("/sockets/events/conv-refetch");
+ });
+
it("uses the planning sub-conversation session key", async () => {
const mainSessionApiKey = `sk-oh-main-${"m".repeat(48)}`;
const planningSessionApiKey = `sk-oh-plan-${"p".repeat(48)}`;
diff --git a/__tests__/hooks/query/use-conversation-history.test.tsx b/__tests__/hooks/query/use-conversation-history.test.tsx
index 998e06cf97..39b5810a8e 100644
--- a/__tests__/hooks/query/use-conversation-history.test.tsx
+++ b/__tests__/hooks/query/use-conversation-history.test.tsx
@@ -1,7 +1,11 @@
import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
import React from "react";
-import { renderHook, waitFor } from "@testing-library/react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import {
+ QueryClient,
+ QueryClientProvider,
+ onlineManager,
+} from "@tanstack/react-query";
import {
INITIAL_HISTORY_PAGE_SIZE,
@@ -193,15 +197,85 @@ describe("useConversationHistory", () => {
{ wrapper },
);
- await waitFor(() => {
- expect(result.current.error).toBeInstanceOf(Error);
- });
+ // The hook sets `retry: 1` (overriding this file's `retry: false` client
+ // default), so the error only settles after one ~1s retry delay.
+ await waitFor(
+ () => {
+ expect(result.current.error).toBeInstanceOf(Error);
+ },
+ { timeout: 5000 },
+ );
expect((result.current.error as Error).message).toBe(
"Invalid conversation history response: expected page.items to be an array.",
);
});
+ it("retries a failed initial load exactly once before surfacing the error", async () => {
+ vi.mocked(useUserConversation).mockReturnValue({
+ data: makeConversation("V1"),
+ isLoading: false,
+ isPending: false,
+ isError: false,
+ error: null,
+ refetch: vi.fn(),
+ } as any);
+
+ const searchEventsSpy = vi
+ .spyOn(EventService, "searchEvents")
+ .mockRejectedValue(new Error("network down"));
+
+ const { result } = renderHook(() => useConversationHistory("conv-retry"), {
+ wrapper,
+ });
+
+ await waitFor(
+ () => {
+ expect(result.current.isError).toBe(true);
+ },
+ { timeout: 5000 },
+ );
+
+ // Exactly one retry: enough to absorb a transient blip, but a bad first
+ // load can't hold the WebSocket gate closed for a long retry chain.
+ expect(searchEventsSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it("does not refetch when the browser comes back online", async () => {
+ vi.mocked(useUserConversation).mockReturnValue({
+ data: makeConversation("V1"),
+ isLoading: false,
+ isPending: false,
+ isError: false,
+ error: null,
+ refetch: vi.fn(),
+ } as any);
+
+ const searchEventsSpy = vi
+ .spyOn(EventService, "searchEvents")
+ .mockResolvedValue(makePage([makeEvent()]));
+
+ const { result } = renderHook(
+ () => useConversationHistory("conv-online-flap"),
+ { wrapper },
+ );
+ await waitFor(() => {
+ expect(result.current.data).toBeDefined();
+ });
+
+ // Act: an online/offline flap, as flaky links produce continuously. The
+ // events missed while offline arrive over the WebSocket `since` replay,
+ // so the query must not refetch (each refetch used to drop the socket).
+ await act(async () => {
+ onlineManager.setOnline(false);
+ onlineManager.setOnline(true);
+ await new Promise((resolve) => {
+ setTimeout(resolve, 150);
+ });
+ });
+
+ expect(searchEventsSpy).toHaveBeenCalledTimes(1);
+ });
});
describe("useConversationHistory cache key stability", () => {
diff --git a/__tests__/hooks/use-bash-command-runner.test.ts b/__tests__/hooks/use-bash-command-runner.test.ts
index 8f9b86c772..368f71db56 100644
--- a/__tests__/hooks/use-bash-command-runner.test.ts
+++ b/__tests__/hooks/use-bash-command-runner.test.ts
@@ -131,4 +131,65 @@ describe("useBashCommandRunner", () => {
unmount();
});
+
+ it("closes a handshake stuck in CONNECTING at the timeout", () => {
+ // Arrange: the server never completes the 101 upgrade. Left alone, this
+ // socket would hold the browser's per-host handshake lock and block the
+ // conversation's events socket indefinitely.
+ vi.stubGlobal("WebSocket", MockWebSocket);
+ vi.useFakeTimers();
+
+ try {
+ const { unmount } = renderHook(() =>
+ useBashCommandRunner(
+ "http://runtime.example.com/api/conversations/conv-1",
+ null,
+ true,
+ ),
+ );
+ const socket = MockWebSocket.instance!;
+ const closeSpy = vi.spyOn(socket, "close");
+
+ // Act/Assert: untouched just before the timeout, closed right at it.
+ vi.advanceTimersByTime(9_999);
+ expect(closeSpy).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(closeSpy).toHaveBeenCalledOnce();
+ expect(socket.readyState).toBe(MockWebSocket.CLOSED);
+
+ unmount();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("does not close a socket that finished its handshake in time", () => {
+ vi.stubGlobal("WebSocket", MockWebSocket);
+ vi.useFakeTimers();
+
+ try {
+ const { unmount } = renderHook(() =>
+ useBashCommandRunner(
+ "http://runtime.example.com/api/conversations/conv-1",
+ null,
+ true,
+ ),
+ );
+ const socket = MockWebSocket.instance!;
+ const closeSpy = vi.spyOn(socket, "close");
+
+ // Act: the handshake completes, then the watchdog window elapses.
+ socket.open();
+ vi.advanceTimersByTime(60_000);
+
+ // Assert: the cleared watchdog never touched the healthy socket.
+ expect(closeSpy).not.toHaveBeenCalled();
+ expect(socket.readyState).toBe(MockWebSocket.OPEN);
+
+ unmount();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
});
diff --git a/__tests__/hooks/use-websocket.test.ts b/__tests__/hooks/use-websocket.test.ts
index 5f7f49ec47..bbba20a619 100644
--- a/__tests__/hooks/use-websocket.test.ts
+++ b/__tests__/hooks/use-websocket.test.ts
@@ -530,6 +530,311 @@ describe("useWebSocket", () => {
expect(sendSpy).toHaveBeenCalledWith("Hello WebSocket!");
});
+ it("closes a handshake stuck in CONNECTING at the timeout and retries", async () => {
+ // Arrange: a socket whose handshake never completes. Closing it while
+ // CONNECTING fires error + close(1006), as browsers do.
+ class MockWebSocket {
+ static readonly CONNECTING = 0;
+ static readonly OPEN = 1;
+ static readonly CLOSING = 2;
+ static readonly CLOSED = 3;
+ static readonly instances: MockWebSocket[] = [];
+
+ readonly url: string;
+ readyState = MockWebSocket.CONNECTING;
+ onopen: ((event: Event) => void) | null = null;
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ onclose: ((event: CloseEvent) => void) | null = null;
+ onerror: ((event: Event) => void) | null = null;
+
+ constructor(url: string) {
+ this.url = url;
+ MockWebSocket.instances.push(this);
+ }
+
+ send() {}
+
+ close() {
+ this.readyState = MockWebSocket.CLOSED;
+ this.onerror?.(new Event("error"));
+ this.onclose?.(
+ new CloseEvent("close", { code: 1006, reason: "", wasClean: false }),
+ );
+ }
+ }
+
+ const originalWebSocket = globalThis.WebSocket;
+ vi.stubGlobal("WebSocket", MockWebSocket);
+ vi.useFakeTimers();
+ vi.spyOn(Math, "random").mockReturnValue(0); // deterministic backoff
+
+ try {
+ const { unmount } = renderHook(() =>
+ useWebSocket("ws://acme.com/ws", { reconnect: { enabled: true } }),
+ );
+ const firstSocket = MockWebSocket.instances[0];
+
+ // Act/Assert: just before the timeout the handshake is still pending.
+ await act(async () => {
+ vi.advanceTimersByTime(9_999);
+ });
+ expect(firstSocket.readyState).toBe(MockWebSocket.CONNECTING);
+ expect(MockWebSocket.instances).toHaveLength(1);
+
+ // At the timeout the stuck socket is closed (releasing the browser's
+ // per-host handshake lock)...
+ await act(async () => {
+ vi.advanceTimersByTime(1);
+ });
+ expect(firstSocket.readyState).toBe(MockWebSocket.CLOSED);
+
+ // ...and a fresh attempt follows after the first backoff delay.
+ await act(async () => {
+ vi.advanceTimersByTime(1_000);
+ });
+ expect(MockWebSocket.instances).toHaveLength(2);
+
+ unmount();
+ } finally {
+ vi.useRealTimers();
+ globalThis.WebSocket = originalWebSocket;
+ MockWebSocket.instances.length = 0;
+ }
+ });
+
+ it("does not close a socket that finished its handshake in time", async () => {
+ class MockWebSocket {
+ static readonly CONNECTING = 0;
+ static readonly OPEN = 1;
+ static readonly CLOSING = 2;
+ static readonly CLOSED = 3;
+ static instance: MockWebSocket | null = null;
+
+ readonly url: string;
+ readyState = MockWebSocket.CONNECTING;
+ onopen: ((event: Event) => void) | null = null;
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ onclose: ((event: CloseEvent) => void) | null = null;
+ onerror: ((event: Event) => void) | null = null;
+
+ constructor(url: string) {
+ this.url = url;
+ MockWebSocket.instance = this;
+ }
+
+ send() {}
+
+ close() {
+ this.readyState = MockWebSocket.CLOSED;
+ }
+ }
+
+ const originalWebSocket = globalThis.WebSocket;
+ vi.stubGlobal("WebSocket", MockWebSocket);
+ vi.useFakeTimers();
+
+ try {
+ const { unmount } = renderHook(() => useWebSocket("ws://acme.com/ws"));
+ const socket = MockWebSocket.instance!;
+ const closeSpy = vi.spyOn(socket, "close");
+
+ // Act: the handshake completes, then the watchdog window elapses.
+ await act(async () => {
+ socket.readyState = MockWebSocket.OPEN;
+ socket.onopen?.(new Event("open"));
+ });
+ await act(async () => {
+ vi.advanceTimersByTime(60_000);
+ });
+
+ // Assert: the cleared watchdog never touched the healthy socket.
+ expect(closeSpy).not.toHaveBeenCalled();
+ expect(socket.readyState).toBe(MockWebSocket.OPEN);
+
+ unmount();
+ } finally {
+ vi.useRealTimers();
+ globalThis.WebSocket = originalWebSocket;
+ MockWebSocket.instance = null;
+ }
+ });
+
+ it("spaces reconnect attempts with exponential backoff capped at 30s", async () => {
+ // Arrange: every connection attempt fails immediately.
+ class MockWebSocket {
+ static readonly CONNECTING = 0;
+ static readonly OPEN = 1;
+ static readonly CLOSING = 2;
+ static readonly CLOSED = 3;
+ static readonly instances: MockWebSocket[] = [];
+
+ readonly url: string;
+ readyState = MockWebSocket.CONNECTING;
+ onopen: ((event: Event) => void) | null = null;
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ onclose: ((event: CloseEvent) => void) | null = null;
+ onerror: ((event: Event) => void) | null = null;
+
+ constructor(url: string) {
+ this.url = url;
+ MockWebSocket.instances.push(this);
+ queueMicrotask(() => {
+ this.readyState = MockWebSocket.CLOSED;
+ this.onclose?.(
+ new CloseEvent("close", {
+ code: 1006,
+ reason: "",
+ wasClean: false,
+ }),
+ );
+ });
+ }
+
+ send() {}
+
+ close() {
+ this.readyState = MockWebSocket.CLOSED;
+ }
+ }
+
+ const originalWebSocket = globalThis.WebSocket;
+ vi.stubGlobal("WebSocket", MockWebSocket);
+ vi.useFakeTimers();
+ vi.spyOn(Math, "random").mockReturnValue(0); // strip the jitter
+
+ const expectInstancesAfter = async (
+ advanceMs: number,
+ expected: number,
+ ) => {
+ await act(async () => {
+ vi.advanceTimersByTime(advanceMs);
+ });
+ expect(MockWebSocket.instances).toHaveLength(expected);
+ };
+
+ try {
+ const { unmount } = renderHook(() =>
+ useWebSocket("ws://acme.com/ws", { reconnect: { enabled: true } }),
+ );
+ // Flush the first attempt's immediate failure.
+ await act(async () => {});
+ expect(MockWebSocket.instances).toHaveLength(1);
+
+ // Act/Assert: retries land at 1s, then 2s, then 4s after each failure.
+ await expectInstancesAfter(999, 1);
+ await expectInstancesAfter(1, 2);
+ await expectInstancesAfter(1_999, 2);
+ await expectInstancesAfter(1, 3);
+ await expectInstancesAfter(3_999, 3);
+ await expectInstancesAfter(1, 4);
+ await expectInstancesAfter(7_999, 4);
+ await expectInstancesAfter(1, 5);
+ await expectInstancesAfter(15_999, 5);
+ await expectInstancesAfter(1, 6);
+
+ // The sixth failure would double to 32s; the cap holds it at 30s...
+ await expectInstancesAfter(29_999, 6);
+ await expectInstancesAfter(1, 7);
+
+ // ...and every failure after that stays at 30s rather than growing.
+ await expectInstancesAfter(29_999, 7);
+ await expectInstancesAfter(1, 8);
+
+ unmount();
+ } finally {
+ vi.useRealTimers();
+ globalThis.WebSocket = originalWebSocket;
+ MockWebSocket.instances.length = 0;
+ }
+ });
+
+ it("ignores close/error events from a socket that was replaced", async () => {
+ // Arrange: sockets that only emit events when the test fires them, so the
+ // old socket's close can land *after* its replacement is open β€” the race
+ // that used to overwrite the new socket's OPEN state.
+ class MockWebSocket {
+ static readonly CONNECTING = 0;
+ static readonly OPEN = 1;
+ static readonly CLOSING = 2;
+ static readonly CLOSED = 3;
+ static readonly instances: MockWebSocket[] = [];
+
+ readonly url: string;
+ readyState = MockWebSocket.CONNECTING;
+ onopen: ((event: Event) => void) | null = null;
+ onmessage: ((event: MessageEvent) => void) | null = null;
+ onclose: ((event: CloseEvent) => void) | null = null;
+ onerror: ((event: Event) => void) | null = null;
+
+ constructor(url: string) {
+ this.url = url;
+ MockWebSocket.instances.push(this);
+ }
+
+ send() {}
+
+ close() {
+ this.readyState = MockWebSocket.CLOSED;
+ }
+
+ emitOpen() {
+ this.readyState = MockWebSocket.OPEN;
+ this.onopen?.(new Event("open"));
+ }
+
+ emitFailure() {
+ this.onerror?.(new Event("error"));
+ this.emitClose();
+ }
+
+ emitClose() {
+ this.onclose?.(
+ new CloseEvent("close", { code: 1006, reason: "", wasClean: false }),
+ );
+ }
+ }
+
+ const originalWebSocket = globalThis.WebSocket;
+ vi.stubGlobal("WebSocket", MockWebSocket);
+
+ const onCloseSpy = vi.fn();
+ const onErrorSpy = vi.fn();
+
+ try {
+ const { result, unmount } = renderHook(() =>
+ useWebSocket("ws://acme.com/ws", {
+ onClose: onCloseSpy,
+ onError: onErrorSpy,
+ }),
+ );
+ const staleSocket = MockWebSocket.instances[0];
+ act(() => staleSocket.emitOpen());
+
+ // Act: replace the socket, open the replacement, then let the stale
+ // socket's error + close events land late.
+ act(() => {
+ result.current.reconnect();
+ });
+ const currentSocket = MockWebSocket.instances[1];
+ act(() => currentSocket.emitOpen());
+ act(() => staleSocket.emitFailure());
+
+ // Assert: the stale socket's events reach neither handler...
+ expect(onCloseSpy).not.toHaveBeenCalled();
+ expect(onErrorSpy).not.toHaveBeenCalled();
+
+ // ...while the current socket's close still notifies as before.
+ act(() => currentSocket.emitClose());
+ expect(onCloseSpy).toHaveBeenCalledOnce();
+ expect(onErrorSpy).toHaveBeenCalledOnce();
+
+ unmount();
+ } finally {
+ globalThis.WebSocket = originalWebSocket;
+ MockWebSocket.instances.length = 0;
+ }
+ });
+
it("should not send message when WebSocket is not connected", () => {
const { result } = renderHook(() => useWebSocket("ws://acme.com/ws"));
diff --git a/src/contexts/conversation-websocket-context.tsx b/src/contexts/conversation-websocket-context.tsx
index 7b7f5ed57c..9aa9bd2441 100644
--- a/src/contexts/conversation-websocket-context.tsx
+++ b/src/contexts/conversation-websocket-context.tsx
@@ -280,17 +280,14 @@ export function ConversationWebSocketProvider({
// user scrolls to the top of the chat. The WebSocket connection waits for
// this query so it can subscribe with `resend_mode='since'` and avoid
// re-streaming everything REST already returned.
- const {
- data: preloadedHistory,
- isPending: isPreloadingHistory,
- isFetching: isFetchingHistory,
- isError: isPreloadHistoryError,
- } = useConversationHistory(conversationId);
+ const { data: preloadedHistory, isPending: isPreloadingHistory } =
+ useConversationHistory(conversationId);
// Skeleton only on the genuine first load (no cached data yet). On return the
// cached page is present, so `isPending` is false and we render the
// last-known discussion immediately while the tail refetch runs in the
- // background β€” see the socket gate below, which waits on `isFetching`.
+ // background β€” the socket gate below also keys on `isPending`, so that
+ // refetch never drops a live socket.
const isLoadingHistoryMain = !!conversationId && isPreloadingHistory;
// Clear the (global, not conversation-scoped) event store when the active
@@ -362,48 +359,45 @@ export function ConversationWebSocketProvider({
/**
* Timestamp of the latest event we already have from REST. Used as
* `after_timestamp` when opening the WebSocket so the server only resends
- * events strictly after this point. `null` until the REST query settles
- * (we hold the WS connection open until then to avoid an `all` resend).
+ * events strictly after this point. `null` until the first REST page lands
+ * (the WS connection is gated on that β€” see `wsUrl` below). During
+ * background refetches `preloadedHistory` keeps the last-known page, so the
+ * anchor holds steady instead of flipping to null; reconnects read the
+ * freshest value from the options ref at connect time.
*/
const initialAfterTimestamp = useMemo<string | null>(() => {
- // Wait for the history query to settle β€” including the refetch fired when
- // returning to a conversation β€” so we anchor `since` to the freshest event
- // we have rather than a stale cached tail.
- if (isFetchingHistory) return null;
const events = preloadedHistory?.events ?? [];
const latest = events[events.length - 1];
if (!latest || !("timestamp" in latest) || !latest.timestamp) return null;
return latest.timestamp;
- }, [preloadedHistory, isFetchingHistory]);
+ }, [preloadedHistory]);
// Build WebSocket URL from props.
//
- // We deliberately wait for the history fetch to settle before opening the
- // socket so the WS subscription can use `resend_mode='since'` with a
- // meaningful `after_timestamp`. This gate is on `isFetching`, not just the
- // first-load `isPending`, so the refetch fired when returning to a
- // conversation also completes first: the socket bakes `after_timestamp` into
- // its URL at connect time and will NOT re-subscribe when the value changes
- // later (see use-websocket β€” options live in a ref, reconnect keys on the URL
- // only). Connecting mid-fetch would therefore pin `since` to the stale cached
- // tail and replay the entire backlog over the socket. Without any gate the WS
- // would instead fall back to `resend_mode='all'`. If the REST query errored we
- // fall through and connect with `resend_mode='all'` so the user still sees
- // live events.
+ // We deliberately wait for the FIRST history load (`isPending`: no data for
+ // this query key yet) before opening the socket, so the WS subscription can
+ // use `resend_mode='since'` with a meaningful `after_timestamp` instead of
+ // falling back to `resend_mode='all'`. The gate is intentionally NOT on
+ // `isFetching`: background refetches (e.g. the `refetchOnMount` fired when
+ // returning to a conversation) must never tear a live socket down β€” on a
+ // flaky link that caused a refetch β†’ teardown β†’ reconnect β†’ refetch loop
+ // that kept the conversation stuck at "Connecting" for minutes. Connecting
+ // during a background refetch anchors `since` to the cached tail; the
+ // overlap with the refetched page is deduped by the event store and the
+ // `isDuplicateEvent` guards in the message handlers. A query-key reset
+ // (backend swap / new session key) makes `isPending` true again, so a
+ // genuine reset still re-gates. If the initial load errors, `isPending`
+ // flips false and we fall through to connect with `resend_mode='all'` so
+ // the user still sees live events.
const wsUrl = useMemo(() => {
if (!conversationId || !conversationUrl) {
return null;
}
- if (isFetchingHistory && !isPreloadHistoryError) {
+ if (isPreloadingHistory) {
return null;
}
return buildWebSocketUrl(conversationId, conversationUrl);
- }, [
- conversationId,
- conversationUrl,
- isFetchingHistory,
- isPreloadHistoryError,
- ]);
+ }, [conversationId, conversationUrl, isPreloadingHistory]);
const planningAgentWsUrl = useMemo(() => {
if (!subConversations?.length) {
diff --git a/src/hooks/query/use-backends-health.ts b/src/hooks/query/use-backends-health.ts
index ded3c0b571..7526fcfdcb 100644
--- a/src/hooks/query/use-backends-health.ts
+++ b/src/hooks/query/use-backends-health.ts
@@ -28,7 +28,10 @@ import {
} from "#/api/backend-registry/health-store";
import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage";
-const REFRESH_INTERVAL_MS = 10000;
+// 30s: each tick costs two sequential requests per backend (settings +
+// server_info), which on slow links measurably competes with conversation
+// traffic for the browser's per-origin HTTP/1.1 connection pool.
+const REFRESH_INTERVAL_MS = 30000;
const PROBE_TIMEOUT_MS = 4000;
export const INVALID_BACKEND_API_KEY_ERROR = "Invalid API key";
export const MISSING_BACKEND_API_KEY_ERROR = "API key required";
@@ -142,10 +145,10 @@ const PROBE_RETRY_DELAY_MS = 300;
*
* The connectivity indicator (and the onboarding "backend connected" banner)
* only flips green once a probe succeeds. With `retry: false` at the query
- * level and a REFRESH_INTERVAL_MS (10s) poll, a single transient first-probe
+ * level and a REFRESH_INTERVAL_MS (30s) poll, a single transient first-probe
* miss β€” the agent-server still warming up right after navigation, a momentary
- * proxy 5xx, a dropped connection β€” would otherwise leave the banner stuck for
- * a full 10s until the next scheduled refetch. That is the root cause of the
+ * proxy 5xx, a dropped connection β€” would otherwise leave the banner stuck
+ * until the next scheduled refetch. That is the root cause of the
* flaky onboarding e2e "backend health probe should report connected" timeout.
*
* Retrying here, inside the query function rather than via React Query's
diff --git a/src/hooks/query/use-conversation-history.ts b/src/hooks/query/use-conversation-history.ts
index 397529c4ba..2c8c9f44f5 100644
--- a/src/hooks/query/use-conversation-history.ts
+++ b/src/hooks/query/use-conversation-history.ts
@@ -80,12 +80,19 @@ export const useConversationHistory = (conversationId?: string) => {
// refetch every return replays the entire post-first-load history over the
// socket (and it gets worse the longer the goal has been running).
//
- // refetchOnWindowFocus is disabled because the WebSocket connection is
- // gated on this query settling (see conversation-websocket-context.tsx); a
- // focus-driven refetch would otherwise needlessly drop and reconnect it.
+ // refetchOnWindowFocus and refetchOnReconnect are disabled: focus changes
+ // and online/offline flapping (frequent on flaky links) would refetch this
+ // query in a loop, and events missed while offline arrive over the
+ // WebSocket `since` replay on reconnect anyway. retry is capped at 1 so a
+ // slow or failing initial load (60s HTTP timeout per attempt) can't hold
+ // the initial WebSocket gate (see conversation-websocket-context.tsx)
+ // closed for minutes β€” on failure the socket connects with
+ // `resend_mode='all'` instead.
staleTime: 0,
gcTime: 30 * 60 * 1000, // 30 minutes β€” keep cached data to render instantly on return
refetchOnMount: "always",
refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ retry: 1,
});
};
diff --git a/src/hooks/query/use-paginated-conversations.ts b/src/hooks/query/use-paginated-conversations.ts
index a6d60be0f6..50f087ed67 100644
--- a/src/hooks/query/use-paginated-conversations.ts
+++ b/src/hooks/query/use-paginated-conversations.ts
@@ -34,12 +34,15 @@ export const usePaginatedConversations = (limit: number = 20) => {
enabled: !!userIsAuthenticated && hasBackend,
getNextPageParam: (lastPage: AppConversationPage) => lastPage.next_page_id,
initialPageParam: undefined as string | undefined,
- // Poll every 10s so titles, execution status, and timestamps stay fresh
- // without requiring the user to refresh. Consumers must gate initial-load
- // UI (e.g. skeletons) on `isLoading`, not `isFetching` β€” `isFetching`
- // flips back to true on every background refetch, which would cause the
- // skeleton to flicker every 10s when the list is empty.
- refetchInterval: 10_000,
+ // Poll every 30s so titles, execution status, and timestamps stay fresh
+ // without requiring the user to refresh. Each response carries the full
+ // conversation objects, so on slow links a tighter interval degrades into
+ // a continuous download that starves the rest of the app (including the
+ // events WebSocket handshake). Consumers must gate initial-load UI (e.g.
+ // skeletons) on `isLoading`, not `isFetching` β€” `isFetching` flips back to
+ // true on every background refetch, which would cause the skeleton to
+ // flicker on each poll when the list is empty.
+ refetchInterval: 30_000,
// A successful fetch proves the backend is reachable. The global
// QueryCache onSuccess handler reads this to clear any persisted
// failure state, re-arming the status dot without user intervention.
diff --git a/src/hooks/use-bash-command-runner.ts b/src/hooks/use-bash-command-runner.ts
index 2167c834f2..f4df6b5093 100644
--- a/src/hooks/use-bash-command-runner.ts
+++ b/src/hooks/use-bash-command-runner.ts
@@ -7,6 +7,7 @@ import type {
} from "@openhands/typescript-client";
import type { CommandResult } from "#/api/runtime-service/agent-server-runtime-service";
import { sendWebSocketAuth } from "#/utils/websocket-auth";
+import { startHandshakeWatchdog } from "#/utils/websocket-handshake";
import { buildBashWebSocketUrl } from "#/utils/websocket-url";
interface WaitingCommand {
@@ -78,7 +79,13 @@ export function useBashCommandRunner(
wsRef.current = ws;
readyWsRef.current = null;
+ // Abort a handshake stuck in CONNECTING β€” a hung bash-events handshake
+ // would also block the conversation's events socket (the one the chat
+ // needs) until it settles.
+ const cancelHandshakeWatchdog = startHandshakeWatchdog(ws);
+
ws.onopen = () => {
+ cancelHandshakeWatchdog();
sendWebSocketAuth(ws, sessionApiKey);
readyWsRef.current = ws;
for (const {
@@ -142,6 +149,7 @@ export function useBashCommandRunner(
}
ws.onclose = () => {
+ cancelHandshakeWatchdog();
wsRef.current = null;
readyWsRef.current = null;
rejectAll("Bash WebSocket closed");
@@ -154,6 +162,8 @@ export function useBashCommandRunner(
};
return () => {
+ // The close handler is nulled below, so cancel the watchdog here.
+ cancelHandshakeWatchdog();
// Prevent the close/error handlers from double-rejecting after unmount
ws.onclose = null;
ws.onerror = null;
diff --git a/src/hooks/use-websocket.ts b/src/hooks/use-websocket.ts
index 66516207ea..b483108a2e 100644
--- a/src/hooks/use-websocket.ts
+++ b/src/hooks/use-websocket.ts
@@ -1,5 +1,6 @@
import React from "react";
import { sendWebSocketAuth } from "#/utils/websocket-auth";
+import { startHandshakeWatchdog } from "#/utils/websocket-handshake";
export interface WebSocketHookOptions {
queryParams?: Record<string, string | boolean>;
@@ -14,6 +15,10 @@ export interface WebSocketHookOptions {
};
}
+// Reconnect backoff bounds: 1s, 2s, 4s, … capped at 30s.
+const RECONNECT_BASE_DELAY_MS = 1_000;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+
export const useWebSocket = (url: string, options?: WebSocketHookOptions) => {
const [isConnected, setIsConnected] = React.useState(false);
const [error, setError] = React.useState<Error | null>(null);
@@ -53,7 +58,13 @@ export const useWebSocket = (url: string, options?: WebSocketHookOptions) => {
// Mark this WebSocket instance as allowed to reconnect
allowedToReconnectRef.current.add(ws);
+ // Abort a socket stuck in CONNECTING so it can't hold Chrome's per-host
+ // handshake lock indefinitely; its close flows into the reconnect path
+ // below.
+ const cancelHandshakeWatchdog = startHandshakeWatchdog(ws);
+
ws.onopen = (event) => {
+ cancelHandshakeWatchdog();
sendWebSocketAuth(ws, optionsRef.current?.sessionApiKey);
setIsConnected(true);
setError(null); // Clear any previous errors
@@ -70,6 +81,7 @@ export const useWebSocket = (url: string, options?: WebSocketHookOptions) => {
};
ws.onclose = (event) => {
+ cancelHandshakeWatchdog();
// Check if this specific WebSocket instance is allowed to reconnect
const canReconnect = allowedToReconnectRef.current.has(ws);
setIsConnected(false);
@@ -86,7 +98,14 @@ export const useWebSocket = (url: string, options?: WebSocketHookOptions) => {
optionsRef.current?.onError?.(event);
}
}
- optionsRef.current?.onClose?.(event);
+ // Notify the consumer unless this socket was deliberately replaced by a
+ // newer one β€” a replaced socket's close event arrives late and must not
+ // clobber the replacement's OPEN state in the consumer. Final closes
+ // (disconnect/unmount, nothing replacing the socket) still notify.
+ const wasReplaced = wsRef.current !== null && wsRef.current !== ws;
+ if (!wasReplaced) {
+ optionsRef.current?.onClose?.(event);
+ }
// Attempt reconnection if enabled and allowed
// IMPORTANT: Only reconnect if this specific instance is allowed to reconnect
@@ -103,15 +122,30 @@ export const useWebSocket = (url: string, options?: WebSocketHookOptions) => {
setIsReconnecting(true);
attemptCountRef.current += 1;
+ // Exponential backoff with up to 30% random jitter so parallel
+ // sockets (main + planning) don't retry in lockstep and hammer an
+ // already-struggling server every few seconds forever.
+ const baseDelay = Math.min(
+ RECONNECT_BASE_DELAY_MS * 2 ** (attemptCountRef.current - 1),
+ RECONNECT_MAX_DELAY_MS,
+ );
+ const delay = baseDelay + Math.random() * baseDelay * 0.3;
+
reconnectTimeoutRef.current = setTimeout(() => {
connectWebSocket();
- }, 3000); // 3 second delay
+ }, delay);
} else {
setIsReconnecting(false);
}
};
ws.onerror = (event) => {
+ // Ignore errors from sockets we've deliberately replaced or closed β€”
+ // aborting a mid-handshake socket fires `error`, and it must not
+ // surface as a connection failure for the replacement socket.
+ if (!allowedToReconnectRef.current.has(ws)) {
+ return;
+ }
setIsConnected(false);
optionsRef.current?.onError?.(event);
};
diff --git a/src/utils/websocket-handshake.ts b/src/utils/websocket-handshake.ts
new file mode 100644
index 0000000000..52a6a9207d
--- /dev/null
+++ b/src/utils/websocket-handshake.ts
@@ -0,0 +1,26 @@
+// Browsers never time out a socket stuck in CONNECTING on their own, and
+// Chrome serializes WebSocket handshakes per host β€” a hung handshake also
+// blocks every other socket to the same origin until it settles. Close it
+// after this long so a retry (and any other queued handshake) can proceed.
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+
+/**
+ * Watches a freshly constructed socket's handshake and closes the socket if it
+ * is still in CONNECTING when the timeout elapses. close() fires the socket's
+ * own error/close events (code 1006), so the abort flows through the caller's
+ * normal close handling rather than a separate failure path.
+ *
+ * Returns a cancel function. The caller must invoke it once the handshake
+ * settles β€” in its open and close handlers, and in any cleanup that detaches
+ * those handlers β€” so the watchdog never outlives the socket it watches.
+ */
+export function startHandshakeWatchdog(
+ ws: Pick<WebSocket, "readyState" | "close">,
+): () => void {
+ const timeout = setTimeout(() => {
+ if (ws.readyState === WebSocket.CONNECTING) {
+ ws.close();
+ }
+ }, HANDSHAKE_TIMEOUT_MS);
+ return () => clearTimeout(timeout);
+}