fix(events): use global WebSocket in Node ESM

src/__tests__/package-import.test.ts

@@ -28,12 +28,20 @@ const WEBSOCKET_MODULES = [
 ] as const;
 
 const mockWsAsUnavailable = (): void => {
+  globalThis.WebSocket = undefined as unknown as typeof WebSocket;
   jest.doMock('ws', () => {
     throw new Error('ws is not available in this environment');
   });
 };
 
 describe('package imports do not crash when `ws` is unavailable', () => {
+  const originalWebSocket = globalThis.WebSocket;
+
+  afterEach(() => {
+    globalThis.WebSocket = originalWebSocket;
+    jest.resetModules();
+  });
+
   describe.each(WEBSOCKET_MODULES)('%s', (modulePath) => {
     it('does not throw at module load', () => {
       expect(() => {
@@ -130,3 +138,62 @@ describe('package imports do not crash when `ws` is unavailable', () => {
     expect(captured?.message).toMatch(/WebSocket implementation not available/i);
   });
 });
+
+describe('modern Node.js WebSocket support', () => {
+  const originalWebSocket = globalThis.WebSocket;
+
+  afterEach(() => {
+    globalThis.WebSocket = originalWebSocket;
+    jest.resetModules();
+  });
+
+  it.each([
+    {
+      modulePath: '../events/websocket-client',
+      exportName: 'WebSocketCallbackClient',
+      options: {
+        host: 'http://example.com',
+        conversationId: 'conv-1',
+        callback: () => {},
+      },
+      expectedUrl: 'ws://example.com/sockets/events/conv-1',
+    },
+    {
+      modulePath: '../events/bash-websocket-client',
+      exportName: 'BashWebSocketClient',
+      options: {
+        host: 'http://example.com',
+        callback: () => {},
+      },
+      expectedUrl: 'ws://example.com/sockets/bash-events',
+    },
+  ])(
+    '$exportName uses globalThis.WebSocket',
+    ({ modulePath, exportName, options, expectedUrl }) => {
+      const urls: string[] = [];
+      class FakeWebSocket {
+        onopen?: () => void;
+        onmessage?: (event: { data: unknown }) => void;
+        onclose?: () => void;
+        onerror?: () => void;
+
+        constructor(url: string) {
+          urls.push(url);
+        }
+
+        close(): void {}
+      }
+      globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+
+      jest.isolateModules(() => {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const module = require(modulePath);
+        const client = new module[exportName](options);
+        client.start();
+        client.stop();
+      });
+
+      expect(urls).toEqual([expectedUrl]);
+    }
+  );
+});

src/events/bash-websocket-client.ts

@@ -5,14 +5,16 @@
 import { BashEvent } from '../models/workspace';
 import { ErrorCallbackType } from './websocket-client';
 
+// Prefer the standards-compatible global in browsers and modern Node.js,
+// falling back to ws where CommonJS require is available.
 // IMPORTANT: this block must never throw. See the matching note in
 // `events/websocket-client.ts` — the "no WebSocket implementation"
 // condition is deferred to connect() time so importing this module does
 // not crash consumers that never use bash event streaming.
 let WebSocketImpl: any;
 
-if (typeof window !== 'undefined' && window.WebSocket) {
-  WebSocketImpl = window.WebSocket;
+if (typeof globalThis.WebSocket !== 'undefined') {
+  WebSocketImpl = globalThis.WebSocket;
 } else {
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -37,7 +39,7 @@
   private apiKey?: string;
   private resendMode?: 'all';
   private onError?: ErrorCallbackType;
   private ws?: any;
   private reconnectDelay = 1000;
   private maxReconnectDelay = 30000;
   private currentDelay = 1000;

src/events/websocket-client.ts

@@ -4,7 +4,8 @@
 
 import { Event, ConversationCallbackType } from '../types/base';
 
-// Use native WebSocket in browser, ws library in Node.js.
+// Prefer the standards-compatible global in browsers and modern Node.js,
+// falling back to ws where CommonJS require is available.
 //
 // IMPORTANT: this block must never throw. It runs whenever this file is
 // imported, and this file is transitively imported by the package barrel
@@ -13,13 +14,13 @@
 // even when they have no intent to open a WebSocket. The "no implementation
 // available" condition is deferred to connect() time, where it is surfaced
 // through the existing onError callback channel.
 let WebSocketImpl: any;
 
-if (typeof window !== 'undefined' && window.WebSocket) {
-  // Browser environment
-  WebSocketImpl = window.WebSocket;
+if (typeof globalThis.WebSocket !== 'undefined') {
+  // Browser or modern Node.js environment
+  WebSocketImpl = globalThis.WebSocket;
 } else {
-  // Node.js environment
+  // Older Node.js or another environment without a global WebSocket
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const ws = require('ws');
@@ -51,7 +52,7 @@
   private callback: ConversationCallbackType;
   private apiKey?: string;
   private onError?: ErrorCallbackType;
   private ws?: any; // WebSocket instance (browser or Node.js)
   private reconnectDelay = 1000;
   private maxReconnectDelay = 30000;
   private currentDelay = 1000;
@@ -111,7 +112,7 @@
         this.currentDelay = this.reconnectDelay;
       };
 
       this.ws.onmessage = (event: { data: any }) => {
         try {
           const message = typeof event.data === 'string' ? event.data : event.data.toString();
           const eventData: Event = JSON.parse(message);