π 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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'sdiff --git a/src/hooks/query/use-conversation-history.ts b/src/hooks/query/use-conversation-history.tsindex 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 returnrefetchOnMount: "always",refetchOnWindowFocus: false,+ refetchOnReconnect: false,+ retry: 1,});};diff --git a/src/hooks/query/use-paginated-conversations.ts b/src/hooks/query/use-paginated-conversations.tsindex 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.tsindex 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 unmountws.onclose = null;ws.onerror = null;diff --git a/src/hooks/use-websocket.ts b/src/hooks/use-websocket.tsindex 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 reconnectallowedToReconnectRef.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 reconnectconst 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.tsnew file mode 100644index 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);+}