agent-relay 2.1.5 → 2.1.6

package/packages/sdk/src/transports/index.ts

@@ -0,0 +1,197 @@
+/**
+ * Transport module for relay client communication.
+ * @agent-relay/sdk
+ *
+ * Provides transport abstraction and implementations:
+ * - SocketTransport: Unix/TCP sockets (Node.js only)
+ * - WebSocketTransport: WebSocket connections (Node.js and Browser)
+ *
+ * Auto-detection selects the appropriate transport based on environment.
+ */
+
+// Types
+export type {
+  Transport,
+  TransportConfig,
+  TransportEvents,
+  TransportState,
+  TransportFactory,
+} from './types.js';
+
+// Socket transport (Node.js)
+export {
+  SocketTransport,
+  createSocketTransport,
+  type SocketTransportConfig,
+} from './socket-transport.js';
+
+// WebSocket transport (Node.js and Browser)
+export {
+  WebSocketTransport,
+  createWebSocketTransport,
+  socketPathToWsUrl,
+  type WebSocketTransportConfig,
+} from './websocket-transport.js';
+
+// Re-export types from types.ts for convenience
+import type { Transport, TransportConfig } from './types.js';
+import { SocketTransport, type SocketTransportConfig } from './socket-transport.js';
+import { WebSocketTransport, type WebSocketTransportConfig, socketPathToWsUrl } from './websocket-transport.js';
+
+/**
+ * Environment detection result.
+ */
+export interface EnvironmentInfo {
+  /** Running in browser environment */
+  isBrowser: boolean;
+  /** Running in Node.js environment */
+  isNode: boolean;
+  /** WebSocket API is available */
+  hasWebSocket: boolean;
+  /** Unix sockets are available (Node.js only) */
+  hasUnixSockets: boolean;
+}
+
+/**
+ * Detect the current runtime environment.
+ */
+export function detectEnvironment(): EnvironmentInfo {
+  const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+  const isNode = typeof process !== 'undefined' &&
+    process.versions != null &&
+    process.versions.node != null;
+  const hasWebSocket = typeof WebSocket !== 'undefined' || isNode; // 'ws' can provide WebSocket in Node
+  const hasUnixSockets = isNode; // Only Node.js supports Unix sockets
+
+  return {
+    isBrowser,
+    isNode,
+    hasWebSocket,
+    hasUnixSockets,
+  };
+}
+
+/**
+ * Options for creating an auto-detected transport.
+ */
+export interface AutoTransportOptions extends TransportConfig {
+  /** Unix socket path (for Node.js socket transport) */
+  socketPath?: string;
+  /** WebSocket URL (for WebSocket transport) */
+  wsUrl?: string;
+  /** WebSocket host (used with port to construct URL) */
+  wsHost?: string;
+  /** WebSocket port (default: 3888) */
+  wsPort?: number;
+  /** WebSocket path (default: /ws) */
+  wsPath?: string;
+  /** Use secure WebSocket (wss://) */
+  wsSecure?: boolean;
+  /** Force a specific transport type */
+  forceTransport?: 'socket' | 'websocket';
+}
+
+/**
+ * Create a transport automatically based on environment and options.
+ *
+ * In browser environments, WebSocket transport is always used.
+ * In Node.js, Unix socket is preferred if socketPath is provided,
+ * otherwise WebSocket is used if wsUrl or wsHost is provided.
+ *
+ * @param options - Transport configuration options
+ * @returns Configured transport instance
+ *
+ * @example Browser usage
+ * ```typescript
+ * const transport = createAutoTransport({
+ *   wsUrl: 'wss://relay.example.com/ws'
+ * });
+ * ```
+ *
+ * @example Node.js with Unix socket
+ * ```typescript
+ * const transport = createAutoTransport({
+ *   socketPath: '/tmp/agent-relay.sock'
+ * });
+ * ```
+ *
+ * @example Node.js with WebSocket
+ * ```typescript
+ * const transport = createAutoTransport({
+ *   wsHost: 'localhost',
+ *   wsPort: 3888
+ * });
+ * ```
+ */
+export function createAutoTransport(options: AutoTransportOptions): Transport {
+  const env = detectEnvironment();
+  const { forceTransport, ...config } = options;
+
+  // Forced transport type
+  if (forceTransport === 'websocket') {
+    return createWsTransportFromOptions(options);
+  }
+  if (forceTransport === 'socket') {
+    if (!options.socketPath) {
+      throw new Error('socketPath is required when forcing socket transport');
+    }
+    if (!env.hasUnixSockets) {
+      throw new Error('Unix sockets are not available in this environment');
+    }
+    return new SocketTransport({
+      socketPath: options.socketPath,
+      connectTimeout: config.connectTimeout,
+    });
+  }
+
+  // Auto-detect: Browser always uses WebSocket
+  if (env.isBrowser) {
+    return createWsTransportFromOptions(options);
+  }
+
+  // Node.js: prefer Unix socket if path is provided
+  if (env.isNode && options.socketPath) {
+    return new SocketTransport({
+      socketPath: options.socketPath,
+      connectTimeout: config.connectTimeout,
+    });
+  }
+
+  // Fall back to WebSocket
+  return createWsTransportFromOptions(options);
+}
+
+/**
+ * Create WebSocket transport from options.
+ */
+function createWsTransportFromOptions(options: AutoTransportOptions): WebSocketTransport {
+  let url = options.wsUrl;
+
+  if (!url) {
+    // Construct URL from components
+    const host = options.wsHost ?? 'localhost';
+    const port = options.wsPort ?? 3888;
+    const path = options.wsPath ?? '/ws';
+    const secure = options.wsSecure ?? false;
+    url = socketPathToWsUrl(host, port, path, secure);
+  }
+
+  return new WebSocketTransport({
+    url,
+    connectTimeout: options.connectTimeout,
+  });
+}
+
+/**
+ * Check if running in a browser environment.
+ */
+export function isBrowser(): boolean {
+  return detectEnvironment().isBrowser;
+}
+
+/**
+ * Check if running in Node.js environment.
+ */
+export function isNode(): boolean {
+  return detectEnvironment().isNode;
+}

package/packages/sdk/src/transports/socket-transport.ts

@@ -0,0 +1,115 @@
+/**
+ * Unix/TCP Socket Transport for Node.js environments.
+ * @agent-relay/sdk
+ */
+
+import net from 'node:net';
+import type { Transport, TransportConfig, TransportEvents, TransportState } from './types.js';
+
+export interface SocketTransportConfig extends TransportConfig {
+  /** Unix socket path or TCP host:port */
+  socketPath: string;
+}
+
+/**
+ * Socket-based transport for Unix sockets and TCP connections.
+ * This is the default transport for Node.js environments.
+ */
+export class SocketTransport implements Transport {
+  private socket?: net.Socket;
+  private config: SocketTransportConfig;
+  private events: TransportEvents = {};
+  private _state: TransportState = 'disconnected';
+
+  constructor(config: SocketTransportConfig) {
+    this.config = {
+      connectTimeout: 5000,
+      ...config,
+    };
+  }
+
+  get state(): TransportState {
+    return this._state;
+  }
+
+  setEvents(events: TransportEvents): void {
+    this.events = events;
+  }
+
+  connect(): Promise<void> {
+    if (this._state !== 'disconnected') {
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+      this._state = 'connecting';
+
+      const timeout = setTimeout(() => {
+        if (this._state === 'connecting') {
+          this.socket?.destroy();
+          this._state = 'disconnected';
+          reject(new Error('Connection timeout'));
+        }
+      }, this.config.connectTimeout);
+
+      this.socket = net.createConnection(this.config.socketPath, () => {
+        clearTimeout(timeout);
+        this._state = 'connected';
+        this.events.onConnect?.();
+        resolve();
+      });
+
+      this.socket.on('data', (data) => {
+        // Convert Buffer to Uint8Array for consistent interface
+        this.events.onData?.(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+      });
+
+      this.socket.on('close', () => {
+        this._state = 'disconnected';
+        this.events.onClose?.();
+      });
+
+      this.socket.on('error', (err) => {
+        clearTimeout(timeout);
+        if (this._state === 'connecting') {
+          this._state = 'disconnected';
+          reject(err);
+        }
+        this.events.onError?.(err);
+      });
+    });
+  }
+
+  disconnect(): void {
+    if (!this.socket || this._state === 'disconnected') {
+      return;
+    }
+
+    this._state = 'closing';
+    this.socket.end();
+    this.socket = undefined;
+    this._state = 'disconnected';
+  }
+
+  send(data: Uint8Array | Buffer): boolean {
+    if (!this.socket || this._state !== 'connected') {
+      return false;
+    }
+
+    try {
+      // Ensure we're sending a Buffer
+      const buffer = data instanceof Buffer ? data : Buffer.from(data);
+      this.socket.write(buffer);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Create a socket transport for Unix/TCP connections.
+ */
+export function createSocketTransport(socketPath: string, config?: TransportConfig): SocketTransport {
+  return new SocketTransport({ socketPath, ...config });
+}

package/packages/sdk/src/transports/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Transport abstraction for relay client communication.
+ * @agent-relay/sdk
+ *
+ * Defines the interface for different transport implementations:
+ * - SocketTransport: Unix/TCP sockets (Node.js)
+ * - WebSocketTransport: WebSocket connections (Node.js and Browser)
+ */
+
+/**
+ * Transport connection state.
+ */
+export type TransportState = 'disconnected' | 'connecting' | 'connected' | 'closing';
+
+/**
+ * Transport event handlers.
+ */
+export interface TransportEvents {
+  /** Called when transport connects successfully */
+  onConnect?: () => void;
+  /** Called when transport receives data */
+  onData?: (data: Uint8Array) => void;
+  /** Called when transport disconnects */
+  onClose?: () => void;
+  /** Called when transport encounters an error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Transport configuration options.
+ */
+export interface TransportConfig {
+  /** Connection timeout in milliseconds */
+  connectTimeout?: number;
+}
+
+/**
+ * Transport interface for relay client communication.
+ *
+ * Implementations must handle:
+ * - Connection lifecycle (connect, disconnect)
+ * - Binary data transmission
+ * - Event callbacks for state changes
+ */
+export interface Transport {
+  /** Current connection state */
+  readonly state: TransportState;
+
+  /**
+   * Connect to the relay endpoint.
+   * @throws Error if connection fails
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from the relay.
+   */
+  disconnect(): void;
+
+  /**
+   * Send binary data to the relay.
+   * @param data - Data to send (Buffer or Uint8Array)
+   * @returns true if data was queued for sending
+   */
+  send(data: Uint8Array | Buffer): boolean;
+
+  /**
+   * Set event handlers.
+   * @param events - Event handler callbacks
+   */
+  setEvents(events: TransportEvents): void;
+}
+
+/**
+ * Transport factory function type.
+ */
+export type TransportFactory = (config?: TransportConfig) => Transport;

package/packages/sdk/src/transports/websocket-transport.ts

@@ -0,0 +1,245 @@
+/**
+ * WebSocket Transport for browser and Node.js environments.
+ * @agent-relay/sdk
+ *
+ * Uses native WebSocket in browsers and 'ws' package in Node.js.
+ * The transport expects the daemon to have a WebSocket endpoint (e.g., /ws).
+ */
+
+import type { Transport, TransportConfig, TransportEvents, TransportState } from './types.js';
+
+export interface WebSocketTransportConfig extends TransportConfig {
+  /** WebSocket URL (e.g., ws://localhost:3888/ws) */
+  url: string;
+  /** Protocols to use in WebSocket handshake */
+  protocols?: string | string[];
+}
+
+// Simple close event type (works in both browser and Node.js)
+interface CloseEventLike {
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+}
+
+// Simple message event type (works in both browser and Node.js)
+interface MessageEventLike {
+  data: ArrayBuffer | string | Buffer;
+}
+
+// Type for WebSocket (works in both browser and Node.js with 'ws')
+interface WebSocketLike {
+  readyState: number;
+  CONNECTING: number;
+  OPEN: number;
+  CLOSING: number;
+  CLOSED: number;
+  send(data: ArrayBuffer | Uint8Array | string): void;
+  close(): void;
+  onopen: ((ev: Event) => void) | null;
+  onclose: ((ev: CloseEventLike) => void) | null;
+  onerror: ((ev: Event | Error) => void) | null;
+  onmessage: ((ev: MessageEventLike) => void) | null;
+  binaryType: string;
+}
+
+// Constructor type for WebSocket
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+
+/**
+ * WebSocket-based transport for browser and Node.js.
+ *
+ * In browsers, uses native WebSocket.
+ * In Node.js, requires 'ws' package (optional dependency).
+ */
+export class WebSocketTransport implements Transport {
+  private ws?: WebSocketLike;
+  private config: WebSocketTransportConfig;
+  private events: TransportEvents = {};
+  private _state: TransportState = 'disconnected';
+  private WebSocketImpl?: WebSocketConstructor;
+
+  constructor(config: WebSocketTransportConfig) {
+    this.config = {
+      connectTimeout: 5000,
+      ...config,
+    };
+  }
+
+  get state(): TransportState {
+    return this._state;
+  }
+
+  setEvents(events: TransportEvents): void {
+    this.events = events;
+  }
+
+  /**
+   * Get WebSocket implementation (native or 'ws' package).
+   */
+  private async getWebSocketImpl(): Promise<WebSocketConstructor> {
+    if (this.WebSocketImpl) {
+      return this.WebSocketImpl;
+    }
+
+    // Check for browser environment
+    if (typeof globalThis !== 'undefined' && 'WebSocket' in globalThis) {
+      this.WebSocketImpl = (globalThis as { WebSocket: WebSocketConstructor }).WebSocket;
+      return this.WebSocketImpl;
+    }
+
+    // Node.js environment - try to load 'ws' package
+    try {
+      // Dynamic import of 'ws' for Node.js
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const wsModule = await import('ws' as any) as any;
+      const impl = wsModule.default || wsModule.WebSocket || wsModule;
+      if (!impl) {
+        throw new Error('ws module loaded but WebSocket constructor not found');
+      }
+      this.WebSocketImpl = impl as WebSocketConstructor;
+      return this.WebSocketImpl;
+    } catch {
+      throw new Error(
+        'WebSocket not available. In Node.js, install the "ws" package:\n' +
+        '  npm install ws\n\n' +
+        'In browsers, native WebSocket should be available.'
+      );
+    }
+  }
+
+  async connect(): Promise<void> {
+    if (this._state !== 'disconnected') {
+      return;
+    }
+
+    const WebSocketImpl = await this.getWebSocketImpl();
+
+    return new Promise((resolve, reject) => {
+      this._state = 'connecting';
+
+      const timeout = setTimeout(() => {
+        if (this._state === 'connecting') {
+          this.ws?.close();
+          this._state = 'disconnected';
+          reject(new Error('Connection timeout'));
+        }
+      }, this.config.connectTimeout);
+
+      try {
+        this.ws = new WebSocketImpl(this.config.url, this.config.protocols);
+        this.ws.binaryType = 'arraybuffer';
+
+        this.ws.onopen = () => {
+          clearTimeout(timeout);
+          this._state = 'connected';
+          this.events.onConnect?.();
+          resolve();
+        };
+
+        this.ws.onmessage = (event: MessageEventLike) => {
+          // Handle binary data
+          if (event.data instanceof ArrayBuffer) {
+            this.events.onData?.(new Uint8Array(event.data));
+          } else if (typeof event.data === 'string') {
+            // Convert string to Uint8Array (shouldn't happen with binaryType = 'arraybuffer')
+            const encoder = new TextEncoder();
+            this.events.onData?.(encoder.encode(event.data));
+          } else if (event.data && typeof (event.data as Buffer).buffer !== 'undefined') {
+            // Handle Node.js Buffer
+            const buf = event.data as Buffer;
+            this.events.onData?.(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+          }
+        };
+
+        this.ws.onclose = () => {
+          clearTimeout(timeout);
+          this._state = 'disconnected';
+          this.events.onClose?.();
+        };
+
+        this.ws.onerror = (event: Event | Error) => {
+          clearTimeout(timeout);
+          const error = event instanceof Error
+            ? event
+            : new Error('WebSocket error');
+          if (this._state === 'connecting') {
+            this._state = 'disconnected';
+            reject(error);
+          }
+          this.events.onError?.(error);
+        };
+      } catch (err) {
+        clearTimeout(timeout);
+        this._state = 'disconnected';
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+
+  disconnect(): void {
+    if (!this.ws || this._state === 'disconnected') {
+      return;
+    }
+
+    this._state = 'closing';
+    this.ws.close();
+    this.ws = undefined;
+    this._state = 'disconnected';
+  }
+
+  send(data: Uint8Array | Buffer): boolean {
+    if (!this.ws || this._state !== 'connected') {
+      return false;
+    }
+
+    try {
+      // WebSocket send accepts ArrayBuffer or Uint8Array
+      // Convert Buffer to Uint8Array for browser compatibility
+      let bytes: Uint8Array;
+      if (data instanceof Uint8Array) {
+        bytes = data;
+      } else {
+        // Handle Buffer (Node.js)
+        const buf = data as Buffer;
+        bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      }
+      this.ws.send(bytes);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Create a WebSocket transport.
+ *
+ * @param url - WebSocket URL (e.g., ws://localhost:3888/ws)
+ * @param config - Additional configuration options
+ */
+export function createWebSocketTransport(
+  url: string,
+  config?: Omit<WebSocketTransportConfig, 'url'>
+): WebSocketTransport {
+  return new WebSocketTransport({ url, ...config });
+}
+
+/**
+ * Convert a socket path to WebSocket URL.
+ * Useful when daemon provides both Unix socket and WebSocket endpoints.
+ *
+ * @param host - Host address (default: localhost)
+ * @param port - Port number (default: 3888)
+ * @param path - WebSocket path (default: /ws)
+ * @param secure - Use wss:// instead of ws:// (default: false)
+ */
+export function socketPathToWsUrl(
+  host = 'localhost',
+  port = 3888,
+  path = '/ws',
+  secure = false
+): string {
+  const protocol = secure ? 'wss' : 'ws';
+  return `${protocol}://${host}:${port}${path}`;
+}

package/packages/sdk/tsconfig.json

@@ -3,7 +3,7 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
+    "lib": ["ES2022", "DOM"],
     "types": ["node"],
     "outDir": "./dist",
     "rootDir": "./src",

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.1.5"
+    "@agent-relay/protocol": "2.1.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/storage/src/jsonl-adapter.test.ts

@@ -218,11 +218,16 @@ describe('JsonlStorageAdapter', () => {
     await writerAdapter.saveMessage(makeMessage({ id: 'watch-test', body: 'from daemon' }));
     await writerAdapter.close();
 
-    // Wait for debounce + file watcher to trigger reload
-    await new Promise(resolve => setTimeout(resolve, 200));
+    // Wait for file watcher to trigger reload (fs.watch can be slow/flaky)
+    // Use polling with retries instead of a fixed timeout
+    let after: StoredMessage[] = [];
+    for (let i = 0; i < 20; i++) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      after = await watchingAdapter.getMessages({});
+      if (after.length > countBefore) break;
+    }
 
     // Should now see the new message
-    const after = await watchingAdapter.getMessages({});
     expect(after.length).toBe(countBefore + 1);
     expect(after.some(m => m.id === 'watch-test')).toBe(true);