[Bug]: WebSocket clients ignore Node's global WebSocket in ESM builds

[georgeglarson]

Is there an existing issue for the same bug?

• I have searched existing issues and this is not a duplicate.

Bug Description

The package is emitted as ESM, and Node 22 provides a standards-compatible globalThis.WebSocket.

The conversation and bash event clients only check window.WebSocket, then attempt require("ws"). Since require is unavailable in ESM, starting either client reports that no WebSocket implementation is available.

Expected Behavior

The TypeScript WebSocket callback clients use Node's global WebSocket constructor when globalThis.WebSocket is available.

Actual Behavior

The error callback receives "WebSocket implementation not available", even though globalThis.WebSocket exists. This is reproducible after running uv sync --dev and building the TypeScript package.

Steps to Reproduce

1. Install dependencies with uv sync --dev.
2. Build the TypeScript package on Node 22.
3. Import WebSocketCallbackClient from dist/events/websocket-client.js in an ESM process.
4. Create a client and call start().

Example:

node --input-type=module -e "const {WebSocketCallbackClient}=await import('./dist/events/websocket-client.js'); const client=new WebSocketCallbackClient({host:'http://127.0.0.1:9',conversationId:'test',callback:()=>{},onError:console.error}); client.start(); client.stop()"

Acceptance Criteria

• The TypeScript WebSocket callback clients use globalThis.WebSocket in Node ESM when available.
• The fallback path still supports injected WebSocket implementations and browser window.WebSocket.
• A TypeScript client test covers Node's global WebSocket constructor path.

Installation Method

uv sync --dev; npm ci in clients/typescript

If you selected "Other", please specify

No response

SDK Version

Current main branch

Version Confirmation

• I have confirmed this bug exists on the LATEST version of OpenHands SDK

Python Version

No response

Model Name (if applicable)

No response

Operating System

Linux

Logs and Error Messages

WebSocket implementation not available

Minimal Code Sample

node --input-type=module -e "const {WebSocketCallbackClient}=await import('./dist/events/websocket-client.js'); const client=new WebSocketCallbackClient({host:'http://127.0.0.1:9',conversationId:'test',callback:()=>{},onError:console.error}); client.start(); client.stop()"

Screenshots and Additional Context

this is the issue backing #4799

[github-actions]

✅ ready-for-dev label applied

This issue meets the readiness criteria and is ready for contribution.
A contributor can now open a PR that links this issue (Fixes #<number>).

This is an automated check — no AI was used to generate this comment.

[all-hands-bot]

Exact duplicate of #4764: identical title, root cause (WebSocket detection skips globalThis.WebSocket in Node ESM), steps to reproduce, and acceptance criteria.

Found 2 possible duplicate issues:

1. #4764 — WebSocket clients ignore Node's global WebSocket in ESM builds
2. #4731 — Fix WebSocket client require('ws') breaking bundlers

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

This comment was created by an AI assistant (OpenHands) on behalf of the repository maintainer.