agent-relay 2.1.4 → 2.1.6

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

@@ -0,0 +1,115 @@
+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

@@ -0,0 +1,150 @@
+/**
+ * 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/client.test.ts

@@ -10,6 +10,8 @@ import type {
   HealthResponsePayload,
   MetricsResponsePayload,
   InboxResponsePayload,
+  AgentReadyPayload,
+  SpawnResultPayload,
 } from '@agent-relay/protocol';
 import { RelayClient } from './client.js';
 
@@ -256,6 +258,208 @@ describe('RelayClient', () => {
     });
   });
 
+  describe('request', () => {
+    it('resolves when matching response arrives via payload_meta.replyTo', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const promise = client.request('Worker', 'Do task', { timeout: 1000 });
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      const correlationId = sentEnvelope.payload.data._correlationId;
+
+      // Simulate response from Worker
+      const responseEnvelope: DeliverEnvelope = {
+        v: 1,
+        type: 'DELIVER',
+        id: 'response-1',
+        ts: Date.now(),
+        from: 'Worker',
+        payload: {
+          kind: 'message',
+          body: 'Task completed',
+          data: { result: 'success' },
+        },
+        payload_meta: {
+          replyTo: correlationId,
+        },
+        delivery: {
+          seq: 1,
+          session_id: 'session-1',
+        },
+      };
+
+      (client as any).processFrame(responseEnvelope);
+
+      const result = await promise;
+      expect(result.from).toBe('Worker');
+      expect(result.body).toBe('Task completed');
+      expect(result.data?.result).toBe('success');
+      expect(result.correlationId).toBe(correlationId);
+    });
+
+    it('resolves when matching response arrives via data._correlationId', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const promise = client.request('Worker', 'Do task', { timeout: 1000 });
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      const correlationId = sentEnvelope.payload.data._correlationId;
+
+      // Simulate response from Worker using data._correlationId
+      const responseEnvelope: DeliverEnvelope = {
+        v: 1,
+        type: 'DELIVER',
+        id: 'response-2',
+        ts: Date.now(),
+        from: 'Worker',
+        payload: {
+          kind: 'message',
+          body: 'Done!',
+          data: { _correlationId: correlationId, _isResponse: true },
+        },
+        delivery: {
+          seq: 2,
+          session_id: 'session-1',
+        },
+      };
+
+      (client as any).processFrame(responseEnvelope);
+
+      const result = await promise;
+      expect(result.from).toBe('Worker');
+      expect(result.body).toBe('Done!');
+      expect(result.correlationId).toBe(correlationId);
+    });
+
+    it('rejects on timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        const client = new RelayClient({ reconnect: false, quiet: true });
+        (client as any)._state = 'READY';
+        const sendMock = vi.fn().mockReturnValue(true);
+        (client as any).send = sendMock;
+
+        const promise = client.request('Worker', 'Do task', { timeout: 50 });
+        const rejection = expect(promise).rejects.toThrow('Request timeout after 50ms waiting for response from Worker');
+        await vi.advanceTimersByTimeAsync(60);
+
+        await rejection;
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('rejects when not ready', async () => {
+      const client = new RelayClient({ reconnect: false });
+      await expect(client.request('Worker', 'Do task')).rejects.toThrow('Client not ready');
+    });
+
+    it('rejects when send fails', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(false);
+      (client as any).send = sendMock;
+
+      await expect(client.request('Worker', 'Do task')).rejects.toThrow('Failed to send request');
+    });
+
+    it('includes custom data and thread in the sent message', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      // Don't await - we just want to check what was sent
+      client.request('Worker', 'Do task', {
+        timeout: 1000,
+        data: { taskId: '123', priority: 'high' },
+        thread: 'task-thread-1',
+      }).catch(() => {}); // Ignore timeout
+
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      expect(sentEnvelope.to).toBe('Worker');
+      expect(sentEnvelope.payload.body).toBe('Do task');
+      expect(sentEnvelope.payload.data.taskId).toBe('123');
+      expect(sentEnvelope.payload.data.priority).toBe('high');
+      expect(sentEnvelope.payload.data._correlationId).toBeDefined();
+      expect(sentEnvelope.payload.thread).toBe('task-thread-1');
+      expect(sentEnvelope.payload_meta.replyTo).toBe(sentEnvelope.payload.data._correlationId);
+    });
+
+    it('still calls onMessage after resolving request', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const messages: any[] = [];
+      client.onMessage = (from, payload) => messages.push({ from, payload });
+
+      const promise = client.request('Worker', 'Do task', { timeout: 1000 });
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      const correlationId = sentEnvelope.payload.data._correlationId;
+
+      const responseEnvelope: DeliverEnvelope = {
+        v: 1,
+        type: 'DELIVER',
+        id: 'response-3',
+        ts: Date.now(),
+        from: 'Worker',
+        payload: {
+          kind: 'message',
+          body: 'Task completed',
+        },
+        payload_meta: {
+          replyTo: correlationId,
+        },
+        delivery: {
+          seq: 3,
+          session_id: 'session-1',
+        },
+      };
+
+      (client as any).processFrame(responseEnvelope);
+
+      await promise;
+
+      // onMessage should still be called
+      expect(messages).toHaveLength(1);
+      expect(messages[0].from).toBe('Worker');
+      expect(messages[0].payload.body).toBe('Task completed');
+    });
+  });
+
+  describe('respond', () => {
+    it('returns false when not connected', () => {
+      const client = new RelayClient({ reconnect: false });
+      const result = client.respond('corr-123', 'Alice', 'Done');
+      expect(result).toBe(false);
+    });
+
+    it('sends response with correlation ID', () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const result = client.respond('corr-123', 'Alice', 'Task completed', { result: 'success' });
+
+      expect(result).toBe(true);
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      expect(sentEnvelope.type).toBe('SEND');
+      expect(sentEnvelope.to).toBe('Alice');
+      expect(sentEnvelope.payload.body).toBe('Task completed');
+      expect(sentEnvelope.payload.data._correlationId).toBe('corr-123');
+      expect(sentEnvelope.payload.data._isResponse).toBe(true);
+      expect(sentEnvelope.payload.data.result).toBe('success');
+      expect(sentEnvelope.payload_meta.replyTo).toBe('corr-123');
+    });
+  });
+
   describe('channel operations', () => {
     it('should return false for joinChannel when not connected', () => {
       const client = new RelayClient({ reconnect: false });
@@ -482,6 +686,227 @@ describe('RelayClient', () => {
     });
   });
 
+  describe('agent ready', () => {
+    it('should call onAgentReady when AGENT_READY received', () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      const readyEvents: AgentReadyPayload[] = [];
+      client.onAgentReady = (info) => readyEvents.push(info);
+
+      const agentReadyEnvelope: Envelope<AgentReadyPayload> = {
+        v: 1,
+        type: 'AGENT_READY',
+        id: 'ready-1',
+        ts: Date.now(),
+        payload: {
+          name: 'Worker',
+          cli: 'claude',
+          task: 'Do something',
+          connectedAt: Date.now(),
+        },
+      };
+
+      (client as any).processFrame(agentReadyEnvelope);
+
+      expect(readyEvents).toHaveLength(1);
+      expect(readyEvents[0].name).toBe('Worker');
+      expect(readyEvents[0].cli).toBe('claude');
+    });
+
+    it('resolves waitForAgentReady when AGENT_READY arrives', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+
+      const promise = client.waitForAgentReady('Worker', 1000);
+
+      const agentReadyEnvelope: Envelope<AgentReadyPayload> = {
+        v: 1,
+        type: 'AGENT_READY',
+        id: 'ready-2',
+        ts: Date.now(),
+        payload: {
+          name: 'Worker',
+          cli: 'codex',
+          connectedAt: Date.now(),
+        },
+      };
+
+      (client as any).processFrame(agentReadyEnvelope);
+
+      const result = await promise;
+      expect(result.name).toBe('Worker');
+      expect(result.cli).toBe('codex');
+    });
+
+    it('rejects waitForAgentReady on timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        const client = new RelayClient({ reconnect: false, quiet: true });
+        (client as any)._state = 'READY';
+
+        const promise = client.waitForAgentReady('Worker', 50);
+        const rejection = expect(promise).rejects.toThrow('Agent Worker did not become ready within 50ms');
+        await vi.advanceTimersByTimeAsync(60);
+
+        await rejection;
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('rejects waitForAgentReady when not ready', async () => {
+      const client = new RelayClient({ reconnect: false });
+      await expect(client.waitForAgentReady('Worker')).rejects.toThrow('Client not ready');
+    });
+
+    it('rejects waitForAgentReady when already waiting', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+
+      // Start waiting
+      client.waitForAgentReady('Worker', 10000).catch(() => {});
+
+      // Try to wait again - should reject
+      await expect(client.waitForAgentReady('Worker')).rejects.toThrow('Already waiting for agent Worker');
+    });
+
+    it('spawn with waitForReady resolves with ready info', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const spawnPromise = client.spawn(
+        {
+          name: 'Worker',
+          cli: 'claude',
+          task: 'Do work',
+          waitForReady: true,
+          readyTimeoutMs: 5000,
+        },
+        1000
+      );
+
+      // First, SPAWN_RESULT arrives
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      const spawnResultEnvelope: Envelope<SpawnResultPayload> = {
+        v: 1,
+        type: 'SPAWN_RESULT',
+        id: 'spawn-result-1',
+        ts: Date.now(),
+        payload: {
+          replyTo: sentEnvelope.id,
+          success: true,
+          name: 'Worker',
+          pid: 12345,
+        },
+      };
+      (client as any).processFrame(spawnResultEnvelope);
+
+      // Then, AGENT_READY arrives
+      const agentReadyEnvelope: Envelope<AgentReadyPayload> = {
+        v: 1,
+        type: 'AGENT_READY',
+        id: 'ready-3',
+        ts: Date.now(),
+        payload: {
+          name: 'Worker',
+          cli: 'claude',
+          task: 'Do work',
+          connectedAt: Date.now(),
+        },
+      };
+      (client as any).processFrame(agentReadyEnvelope);
+
+      const result = await spawnPromise;
+      expect(result.success).toBe(true);
+      expect(result.ready).toBe(true);
+      expect(result.readyInfo?.name).toBe('Worker');
+      expect(result.readyInfo?.cli).toBe('claude');
+    });
+
+    it('spawn with waitForReady returns ready:false on timeout', async () => {
+      vi.useFakeTimers();
+      try {
+        const client = new RelayClient({ reconnect: false, quiet: true });
+        (client as any)._state = 'READY';
+        const sendMock = vi.fn().mockReturnValue(true);
+        (client as any).send = sendMock;
+
+        const spawnPromise = client.spawn(
+          {
+            name: 'Worker',
+            cli: 'claude',
+            waitForReady: true,
+            readyTimeoutMs: 100,
+          },
+          500
+        );
+
+        // SPAWN_RESULT arrives
+        const sentEnvelope = sendMock.mock.calls[0][0];
+        const spawnResultEnvelope: Envelope<SpawnResultPayload> = {
+          v: 1,
+          type: 'SPAWN_RESULT',
+          id: 'spawn-result-2',
+          ts: Date.now(),
+          payload: {
+            replyTo: sentEnvelope.id,
+            success: true,
+            name: 'Worker',
+            pid: 12346,
+          },
+        };
+        (client as any).processFrame(spawnResultEnvelope);
+
+        // Agent ready timeout expires
+        await vi.advanceTimersByTimeAsync(150);
+
+        const result = await spawnPromise;
+        expect(result.success).toBe(true);
+        expect(result.ready).toBe(false);
+        expect(result.readyInfo).toBeUndefined();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('spawn without waitForReady does not wait for AGENT_READY', async () => {
+      const client = new RelayClient({ reconnect: false, quiet: true });
+      (client as any)._state = 'READY';
+      const sendMock = vi.fn().mockReturnValue(true);
+      (client as any).send = sendMock;
+
+      const spawnPromise = client.spawn(
+        {
+          name: 'Worker',
+          cli: 'claude',
+        },
+        1000
+      );
+
+      // SPAWN_RESULT arrives
+      const sentEnvelope = sendMock.mock.calls[0][0];
+      const spawnResultEnvelope: Envelope<SpawnResultPayload> = {
+        v: 1,
+        type: 'SPAWN_RESULT',
+        id: 'spawn-result-3',
+        ts: Date.now(),
+        payload: {
+          replyTo: sentEnvelope.id,
+          success: true,
+          name: 'Worker',
+          pid: 12347,
+        },
+      };
+      (client as any).processFrame(spawnResultEnvelope);
+
+      const result = await spawnPromise;
+      expect(result.success).toBe(true);
+      expect(result.ready).toBeUndefined();
+      expect(result.readyInfo).toBeUndefined();
+    });
+  });
+
   describe('consensus operations', () => {
     it('should return false for createProposal when not connected', () => {
       const client = new RelayClient({ reconnect: false });