OpenHands / OpenHands/software-agent-sdk
[Bug]: WebSocket clients ignore Node's global WebSocket in ESM builds
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
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
- Install dependencies with uv sync --dev.
- Build the TypeScript package on Node 22.
- Import WebSocketCallbackClient from dist/events/websocket-client.js in an ESM process.
- 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 https://github.com/OpenHands/software-agent-sdk/pull/4799
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the TypeScript source that builds to dist/events/websocket-client.js and inspect the conversation and bash WebSocket callback clients. Reproduce the failure with the Node 22 ESM command after uv sync --dev and the TypeScript build, then run the existing client tests. Done means globalThis.WebSocket is covered while injected implementations and browser window.WebSocket still work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100