Fix WebSocket browser compatibility

- Replace Node.js 'ws' import with universal WebSocket implementation
- Use native browser WebSocket when available, fallback to 'ws' in Node.js
- Handle different event APIs: browser (onmessage) vs Node.js (.on())
- Maintain backward compatibility for Node.js environments
- Fix 'ws does not work in the browser' error in example app

This allows the SDK to work in both browser and Node.js environments
without requiring separate builds or polyfills.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

src/events/websocket-client.ts

@@ -2,9 +2,24 @@
  * WebSocket client for real-time event streaming
  */
 
-import WebSocket from 'ws';
 import { Event, ConversationCallbackType } from '../types/base';
 
+// Use native WebSocket in browser, ws library in Node.js
+const WebSocketImpl = (() => {
+  if (typeof window !== 'undefined' && window.WebSocket) {
+    // Browser environment
+    return window.WebSocket;
+  } else {
+    // Node.js environment
+    try {
+      const ws = require('ws');
+      return ws;
+    } catch (e) {
+      throw new Error('WebSocket implementation not available. Install ws package for Node.js environments.');
+    }
+  }
+})();
+
 export interface WebSocketClientOptions {
   host: string;
   conversationId: string;
@@ -17,7 +32,7 @@ export class WebSocketCallbackClient {
   private conversationId: string;
   private callback: ConversationCallbackType;
   private apiKey?: string;
-  private ws?: WebSocket;
+  private ws?: any; // WebSocket instance (browser or Node.js)
   private reconnectDelay = 1000;
   private maxReconnectDelay = 30000;
   private currentDelay = 1000;
@@ -64,38 +79,74 @@ export class WebSocketCallbackClient {
       // Add API key as query parameter if provided
       const finalUrl = this.apiKey ? `${wsUrl}?session_api_key=${this.apiKey}` : wsUrl;
 
-      this.ws = new WebSocket(finalUrl);
-
-      this.ws.on('open', () => {
-        console.debug(`WebSocket connected to ${finalUrl}`);
-        this.currentDelay = this.reconnectDelay; // Reset delay on successful connection
-      });
-
-      this.ws.on('message', (data: WebSocket.Data) => {
-        try {
-          const message = data.toString();
-          const event: Event = JSON.parse(message);
-          this.callback(event);
-        } catch (error) {
-          console.error('Error processing WebSocket message:', error);
-        }
-      });
-
-      this.ws.on('close', (code: number, reason: Buffer) => {
-        console.debug(`WebSocket closed: ${code} ${reason.toString()}`);
-        this.ws = undefined;
-
-        if (this.shouldReconnect) {
-          this.scheduleReconnect();
-        }
-      });
-
-      this.ws.on('error', (error: Error) => {
-        console.debug('WebSocket error:', error);
-        if (this.shouldReconnect) {
-          this.scheduleReconnect();
-        }
-      });
+      this.ws = new WebSocketImpl(finalUrl);
+
+      // Handle events differently for browser vs Node.js
+      if (typeof window !== 'undefined') {
+        // Browser WebSocket API
+        this.ws.onopen = () => {
+          console.debug(`WebSocket connected to ${finalUrl}`);
+          this.currentDelay = this.reconnectDelay; // Reset delay on successful connection
+        };
+
+        this.ws.onmessage = (event: MessageEvent) => {
+          try {
+            const message = event.data;
+            const eventData: Event = JSON.parse(message);
+            this.callback(eventData);
+          } catch (error) {
+            console.error('Error processing WebSocket message:', error);
+          }
+        };
+
+        this.ws.onclose = (event: CloseEvent) => {
+          console.debug(`WebSocket closed: ${event.code} ${event.reason}`);
+          this.ws = undefined;
+
+          if (this.shouldReconnect) {
+            this.scheduleReconnect();
+          }
+        };
+
+        this.ws.onerror = (error: Event) => {
+          console.debug('WebSocket error:', error);
+          if (this.shouldReconnect) {
+            this.scheduleReconnect();
+          }
+        };
+      } else {
+        // Node.js ws library API
+        this.ws.on('open', () => {
+          console.debug(`WebSocket connected to ${finalUrl}`);
+          this.currentDelay = this.reconnectDelay; // Reset delay on successful connection
+        });
+
+        this.ws.on('message', (data: any) => {
+          try {
+            const message = data.toString();
+            const event: Event = JSON.parse(message);
+            this.callback(event);
+          } catch (error) {
+            console.error('Error processing WebSocket message:', error);
+          }
+        });
+
+        this.ws.on('close', (code: number, reason: any) => {
+          console.debug(`WebSocket closed: ${code} ${reason ? reason.toString() : ''}`);
+          this.ws = undefined;
+
+          if (this.shouldReconnect) {
+            this.scheduleReconnect();
+          }
+        });
+
+        this.ws.on('error', (error: Error) => {
+          console.debug('WebSocket error:', error);
+          if (this.shouldReconnect) {
+            this.scheduleReconnect();
+          }
+        });
+      }
     } catch (error) {
       console.error('Failed to create WebSocket connection:', error);
       if (this.shouldReconnect) {