agent-relay 2.3.2 → 2.3.5

package/packages/sdk/src/browser-framing.test.ts

@@ -1,115 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { encodeFrameLegacyBrowser, BrowserFrameParser } from './browser-framing.js';
-
-describe('browser-framing', () => {
-  describe('encodeFrameLegacyBrowser', () => {
-    it('encodes envelope with 4-byte length header', () => {
-      const envelope = { type: 'PING', v: 1, id: 'test', ts: 12345, payload: {} };
-      const frame = encodeFrameLegacyBrowser(envelope);
-
-      // Should be Uint8Array
-      expect(frame).toBeInstanceOf(Uint8Array);
-
-      // First 4 bytes should be the length in big-endian
-      const view = new DataView(frame.buffer);
-      const length = view.getUint32(0, false);
-
-      // Payload should match the encoded JSON length
-      const json = JSON.stringify(envelope);
-      expect(length).toBe(new TextEncoder().encode(json).length);
-    });
-
-    it('throws on oversized frames', () => {
-      const largePayload = 'x'.repeat(1024 * 1024 + 1);
-      const envelope = { type: 'SEND', v: 1, id: 'test', ts: 12345, payload: { body: largePayload } };
-
-      expect(() => encodeFrameLegacyBrowser(envelope)).toThrow(/Frame too large/);
-    });
-  });
-
-  describe('BrowserFrameParser', () => {
-    it('parses complete frame', () => {
-      const envelope = { type: 'PONG', v: 1, id: 'abc', ts: 999, payload: {} };
-      const frame = encodeFrameLegacyBrowser(envelope);
-
-      const parser = new BrowserFrameParser();
-      const parsed = parser.push(frame);
-
-      expect(parsed).toHaveLength(1);
-      expect(parsed[0]).toEqual(envelope);
-    });
-
-    it('handles partial frames', () => {
-      const envelope = { type: 'SEND', v: 1, id: 'xyz', ts: 1000, payload: { to: 'Agent', body: 'Hello' } };
-      const frame = encodeFrameLegacyBrowser(envelope);
-
-      const parser = new BrowserFrameParser();
-
-      // Send first half
-      const half = Math.floor(frame.length / 2);
-      let parsed = parser.push(frame.subarray(0, half));
-      expect(parsed).toHaveLength(0);
-
-      // Send second half
-      parsed = parser.push(frame.subarray(half));
-      expect(parsed).toHaveLength(1);
-      expect(parsed[0]).toEqual(envelope);
-    });
-
-    it('parses multiple frames in sequence', () => {
-      const envelopes = [
-        { type: 'PING', v: 1, id: '1', ts: 1, payload: {} },
-        { type: 'PONG', v: 1, id: '2', ts: 2, payload: {} },
-        { type: 'ACK', v: 1, id: '3', ts: 3, payload: { messageId: 'x' } },
-      ];
-
-      const frames = envelopes.map(e => encodeFrameLegacyBrowser(e));
-      const combined = new Uint8Array(frames.reduce((sum, f) => sum + f.length, 0));
-      let offset = 0;
-      for (const frame of frames) {
-        combined.set(frame, offset);
-        offset += frame.length;
-      }
-
-      const parser = new BrowserFrameParser();
-      const parsed = parser.push(combined);
-
-      expect(parsed).toHaveLength(3);
-      expect(parsed).toEqual(envelopes);
-    });
-
-    it('tracks pending bytes correctly', () => {
-      const parser = new BrowserFrameParser();
-      expect(parser.pendingBytes).toBe(0);
-
-      // Push partial header
-      parser.push(new Uint8Array([0, 0, 0, 10])); // Header claiming 10 byte payload
-      expect(parser.pendingBytes).toBe(4);
-
-      // Push partial payload
-      parser.push(new Uint8Array([123])); // Just '{'
-      expect(parser.pendingBytes).toBe(5);
-    });
-
-    it('throws on oversized frame', () => {
-      const parser = new BrowserFrameParser();
-
-      // Create header claiming 2MB payload
-      const header = new Uint8Array(4);
-      const view = new DataView(header.buffer);
-      view.setUint32(0, 2 * 1024 * 1024, false);
-
-      expect(() => parser.push(header)).toThrow(/Frame too large/);
-    });
-
-    it('resets parser state', () => {
-      const parser = new BrowserFrameParser();
-      parser.push(new Uint8Array([0, 0, 0, 5, 123])); // Partial frame
-
-      expect(parser.pendingBytes).toBeGreaterThan(0);
-
-      parser.reset();
-      expect(parser.pendingBytes).toBe(0);
-    });
-  });
-});

package/packages/sdk/src/browser-framing.ts

@@ -1,150 +0,0 @@
-/**
- * Browser-compatible frame encoding/decoding for the Agent Relay protocol.
- *
- * Uses Uint8Array and DataView instead of Node.js Buffer for browser compatibility.
- *
- * Wire format (legacy):
- * - 4 bytes: big-endian payload length
- * - N bytes: JSON payload
- */
-
-import type { Envelope } from '@agent-relay/protocol';
-
-export const MAX_FRAME_BYTES = 1024 * 1024; // 1 MiB
-export const LEGACY_HEADER_SIZE = 4;
-
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-
-/**
- * Encode a frame in legacy format (4-byte header, JSON only).
- * Browser-compatible version using Uint8Array.
- */
-export function encodeFrameLegacyBrowser(envelope: Envelope): Uint8Array {
-  const json = JSON.stringify(envelope);
-  const data = textEncoder.encode(json);
-
-  if (data.length > MAX_FRAME_BYTES) {
-    throw new Error(`Frame too large: ${data.length} > ${MAX_FRAME_BYTES}`);
-  }
-
-  const frame = new Uint8Array(LEGACY_HEADER_SIZE + data.length);
-  const view = new DataView(frame.buffer);
-
-  // Write 4-byte big-endian length header
-  view.setUint32(0, data.length, false);
-
-  // Copy payload
-  frame.set(data, LEGACY_HEADER_SIZE);
-
-  return frame;
-}
-
-/**
- * Browser-compatible frame parser using Uint8Array and DataView.
- */
-export class BrowserFrameParser {
-  private buffer: Uint8Array;
-  private head = 0;
-  private tail = 0;
-  private readonly capacity: number;
-  private readonly maxFrameBytes: number;
-
-  constructor(maxFrameBytes: number = MAX_FRAME_BYTES) {
-    this.maxFrameBytes = maxFrameBytes;
-    this.capacity = maxFrameBytes * 2 + LEGACY_HEADER_SIZE;
-    this.buffer = new Uint8Array(this.capacity);
-  }
-
-  /**
-   * Get current unread bytes in buffer.
-   */
-  get pendingBytes(): number {
-    return this.tail - this.head;
-  }
-
-  /**
-   * Push data into the parser and extract complete frames.
-   *
-   * @param data - Incoming data as Uint8Array
-   * @returns Array of parsed envelope frames
-   */
-  push(data: Uint8Array): Envelope[] {
-    const spaceAtEnd = this.capacity - this.tail;
-
-    if (data.length > spaceAtEnd) {
-      this.compact();
-
-      if (data.length > this.capacity - this.tail) {
-        throw new Error(`Buffer overflow: data ${data.length} exceeds capacity`);
-      }
-    }
-
-    // Copy incoming data to buffer
-    this.buffer.set(data, this.tail);
-    this.tail += data.length;
-
-    return this.extractFrames();
-  }
-
-  private extractFrames(): Envelope[] {
-    const frames: Envelope[] = [];
-    const view = new DataView(this.buffer.buffer);
-
-    while (this.pendingBytes >= LEGACY_HEADER_SIZE) {
-      // Read 4-byte big-endian length
-      const frameLength = view.getUint32(this.head, false);
-
-      if (frameLength > this.maxFrameBytes) {
-        throw new Error(`Frame too large: ${frameLength} > ${this.maxFrameBytes}`);
-      }
-
-      const totalLength = LEGACY_HEADER_SIZE + frameLength;
-
-      if (this.pendingBytes < totalLength) {
-        break;
-      }
-
-      const payloadStart = this.head + LEGACY_HEADER_SIZE;
-      const payloadEnd = this.head + totalLength;
-
-      let envelope: Envelope;
-      try {
-        const payload = this.buffer.subarray(payloadStart, payloadEnd);
-        const json = textDecoder.decode(payload);
-        envelope = JSON.parse(json) as Envelope;
-      } catch (err) {
-        throw new Error(`Invalid frame payload: ${err}`);
-      }
-
-      this.head += totalLength;
-      frames.push(envelope);
-    }
-
-    if (this.head > this.capacity / 2 && this.pendingBytes < this.capacity / 4) {
-      this.compact();
-    }
-
-    return frames;
-  }
-
-  private compact(): void {
-    if (this.head === 0) return;
-
-    const pending = this.pendingBytes;
-    if (pending > 0) {
-      // Copy remaining data to start of buffer
-      this.buffer.copyWithin(0, this.head, this.tail);
-    }
-    this.tail = pending;
-    this.head = 0;
-  }
-
-  /**
-   * Reset the parser state.
-   */
-  reset(): void {
-    this.head = 0;
-    this.tail = 0;
-  }
-}

package/packages/sdk/src/standalone.ts

@@ -1,183 +0,0 @@
-/**
- * Standalone Relay - Dead Simple Agent Communication
- *
- * Use Agent Relay as a pure communication layer without any external setup.
- * Just import and go.
- *
- * @example
- * ```typescript
- * import { createRelay } from '@agent-relay/sdk/standalone';
- *
- * const relay = await createRelay();
- *
- * const alice = await relay.client('Alice');
- * const bob = await relay.client('Bob');
- *
- * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
- * alice.sendMessage('Bob', 'Hello!');
- *
- * await relay.stop();
- * ```
- */
-
-import { RelayClient, type ClientConfig } from './client.js';
-
-// Types for the daemon (avoid importing to keep this file lightweight)
-interface DaemonLike {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  isRunning: boolean;
-}
-
-export interface RelayConfig {
-  /** Socket path for IPC. Default: /tmp/agent-relay-standalone.sock */
-  socketPath?: string;
-  /** Suppress console logging. Default: true */
-  quiet?: boolean;
-  /** Enable agent spawning. Default: false */
-  spawnManager?: boolean;
-}
-
-export interface Relay {
-  /** Create a connected client for an agent */
-  client(name: string, config?: Partial<ClientConfig>): Promise<RelayClient>;
-  /** Stop the relay and disconnect all clients */
-  stop(): Promise<void>;
-  /** Check if relay is running */
-  readonly isRunning: boolean;
-  /** The socket path being used */
-  readonly socketPath: string;
-}
-
-const DEFAULT_SOCKET_PATH = '/tmp/agent-relay-standalone.sock';
-
-/**
- * Create a standalone relay for pure agent-to-agent communication.
- *
- * This starts an in-process daemon - no external setup required.
- * Perfect for using Agent Relay as just a communication layer.
- *
- * @example Basic Usage
- * ```typescript
- * const relay = await createRelay();
- *
- * const agent1 = await relay.client('Agent1');
- * const agent2 = await relay.client('Agent2');
- *
- * agent2.onMessage = (from, payload) => {
- *   console.log(`Message from ${from}: ${payload.body}`);
- * };
- *
- * agent1.sendMessage('Agent2', 'Hello!');
- * ```
- *
- * @example With Custom Socket
- * ```typescript
- * const relay = await createRelay({ socketPath: '/tmp/my-relay.sock' });
- * ```
- */
-export async function createRelay(config: RelayConfig = {}): Promise<Relay> {
-  const socketPath = config.socketPath ?? DEFAULT_SOCKET_PATH;
-  const quiet = config.quiet ?? true;
-
-  // Lazy-load daemon to keep SDK lightweight for client-only users
-  let Daemon: new (config: Record<string, unknown>) => DaemonLike;
-  try {
-    // Dynamic import using variable to prevent TypeScript from resolving the module
-    // This avoids circular dependency: sdk -> daemon -> bridge -> mcp -> sdk
-    const daemonModulePath = '@agent-relay/daemon';
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const daemonModule: any = await import(/* webpackIgnore: true */ daemonModulePath);
-    Daemon = daemonModule.Daemon;
-  } catch {
-    throw new Error(
-      'To use standalone relay, install @agent-relay/daemon:\n' +
-      '  npm install @agent-relay/daemon\n\n' +
-      'Or if you have an external daemon running, use RelayClient directly.'
-    );
-  }
-
-  const daemon = new Daemon({
-    socketPath,
-    consensus: false, // Minimal mode - just messaging
-    cloudSync: false, // No cloud features
-    spawnManager: config.spawnManager ?? false,
-  });
-
-  await daemon.start();
-
-  const clients: RelayClient[] = [];
-
-  return {
-    async client(name: string, clientConfig: Partial<ClientConfig> = {}): Promise<RelayClient> {
-      const client = new RelayClient({
-        agentName: name,
-        socketPath,
-        quiet,
-        reconnect: true,
-        ...clientConfig,
-      });
-      await client.connect();
-      clients.push(client);
-      return client;
-    },
-
-    async stop(): Promise<void> {
-      // Disconnect all clients first
-      for (const client of clients) {
-        client.destroy();
-      }
-      clients.length = 0;
-      // Stop the daemon
-      await daemon.stop();
-    },
-
-    get isRunning(): boolean {
-      return daemon.isRunning;
-    },
-
-    get socketPath(): string {
-      return socketPath;
-    },
-  };
-}
-
-/**
- * Quick helper to create two connected agents for simple communication.
- *
- * @example
- * ```typescript
- * const { alice, bob, stop } = await createPair('Alice', 'Bob');
- *
- * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
- * alice.sendMessage('Bob', 'Hi there!');
- *
- * await stop();
- * ```
- */
-export async function createPair(
-  name1: string,
-  name2: string,
-  config: RelayConfig = {}
-): Promise<{
-  [K in typeof name1]: RelayClient;
-} & {
-  [K in typeof name2]: RelayClient;
-} & {
-  relay: Relay;
-  stop: () => Promise<void>;
-}> {
-  const relay = await createRelay(config);
-  const client1 = await relay.client(name1);
-  const client2 = await relay.client(name2);
-
-  return {
-    [name1]: client1,
-    [name2]: client2,
-    relay,
-    stop: () => relay.stop(),
-  } as any;
-}
-
-// Re-export client for convenience
-export { RelayClient, type ClientConfig } from './client.js';

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

@@ -1,197 +0,0 @@
-/**
- * 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;
-}