fix(events): use global WebSocket in Node ESM

[georgeglarson]

• A human has tested these changes.

HUMAN:

Ran the built ESM reproduction on Node 22.22.2 and confirmed the client selected the global WebSocket constructor without reporting a missing implementation.

---

Why

The package is emitted as ESM. In Node 22, both WebSocket clients ignore the standards-compatible globalThis.WebSocket, check the absent window.WebSocket, then attempt the unavailable require('ws'). Starting either client reports that no WebSocket implementation is available.

This follows #157, which stopped ESM package imports from throwing by deferring the missing-WebSocket error until start(). The built ESM socket path still ignored Node's native globalThis.WebSocket.

Summary

• Prefer globalThis.WebSocket in the conversation and bash event clients.
• Retain the existing ws fallback for environments where CommonJS require is available.
• Cover global constructor selection and the missing-implementation path for both clients.

Issue Number

Closes OpenHands/software-agent-sdk#4764.

How to Test

npm ci
npm run test:coverage
npm run lint
npm run build
npm run format:check

The built ESM package can also be checked directly:

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(); console.log(client.ws?.constructor?.name); client.stop()"

On Node 22, this prints WebSocket instead of reporting a missing implementation.

Video/Screenshots

Not applicable.

Type

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

Notes

Older Node ESM runtimes without a global WebSocket still follow the existing fallback behavior.

[all-hands-bot]

👋 This PR needs a couple of things fixed before OpenHands can review it:

• the PR description's HUMAN: section needs at least 20 characters describing what you tested, not just the template placeholder

Push an update once this is addressed and this check re-runs automatically.

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

[enyst]

Thank you for looking into this, TBH I think maybe we could upgrade to Node 24+ and not worry about 22… We had a small discussion on Slack here on upgrading support, though I forgot about it TBH

(my agent will have some explaining to do! why wasn’t it in my morning coffee newsletter?)

[all-hands-bot]

🚦 CI is currently failing on this PR's latest commit.

Please fix the failing checks before OpenHands reviews it - this is re-checked automatically once you push a new commit. (A maintainer can also request @all-hands-bot as a reviewer to have it reviewed regardless of CI status.)

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

[georgeglarson]

Closing in favour of #370, which contains this change and deletes the dead ws fallback along with it.

On not worrying about 22: the bump alone doesn't fix this one. window is undefined on Node 24 as well, so the fallback still reaches require('ws') and still throws in ESM. 370 removes the branch outright, so it's fixed wherever the floor ends up, and ws stops shipping to consumers.