OpenHands / OpenHands/software-agent-sdk

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

Open
#4,846 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug javascript priority:medium ready-for-dev release-note-required
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
  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 https://github.com/OpenHands/software-agent-sdk/pull/4799

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.