@cleocode/core 2026.3.74 → 2026.4.0

package/src/conduit/__tests__/local-transport.test.ts

@@ -0,0 +1,320 @@
+/**
+ * LocalTransport test suite.
+ *
+ * Tests the in-process SQLite transport for fully offline agent messaging.
+ * Uses a temporary signaldock.db created via ensureSignaldockDb().
+ *
+ * @see packages/core/src/conduit/local-transport.ts
+ * @task T213
+ */
+
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ensureSignaldockDb } from '../../store/signaldock-sqlite.js';
+import { LocalTransport } from '../local-transport.js';
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+let testDir: string;
+let originalCwd: string;
+
+/** Create a temporary directory with a valid signaldock.db for testing. */
+async function setupTestDb(): Promise<string> {
+  const dir = join(
+    tmpdir(),
+    `local-transport-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(join(dir, '.cleo'), { recursive: true });
+  await ensureSignaldockDb(dir);
+  return dir;
+}
+
+/** Standard connect config for tests. */
+function testConfig(agentId = 'test-agent') {
+  return {
+    agentId,
+    apiKey: 'sk_test_fake',
+    apiBaseUrl: 'http://localhost:4000',
+  };
+}
+
+// ============================================================================
+// Test suite
+// ============================================================================
+
+describe('LocalTransport', () => {
+  beforeEach(async () => {
+    originalCwd = process.cwd();
+    testDir = await setupTestDb();
+    process.chdir(testDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    if (testDir && existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  // --------------------------------------------------------------------------
+  // Connection
+  // --------------------------------------------------------------------------
+
+  describe('connect', () => {
+    it('connects when signaldock.db exists', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig());
+      await transport.disconnect();
+    });
+
+    it('throws when signaldock.db is missing', async () => {
+      const emptyDir = join(tmpdir(), `empty-${Date.now()}`);
+      mkdirSync(join(emptyDir, '.cleo'), { recursive: true });
+      process.chdir(emptyDir);
+
+      const transport = new LocalTransport();
+      await expect(transport.connect(testConfig())).rejects.toThrow('signaldock.db not found');
+
+      rmSync(emptyDir, { recursive: true, force: true });
+    });
+
+    it('has name "local"', () => {
+      const transport = new LocalTransport();
+      expect(transport.name).toBe('local');
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Push
+  // --------------------------------------------------------------------------
+
+  describe('push', () => {
+    it('stores a direct message and returns a message ID', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig('sender'));
+
+      const result = await transport.push('receiver', 'hello from sender');
+      expect(result.messageId).toBeDefined();
+      expect(typeof result.messageId).toBe('string');
+      expect(result.messageId.length).toBeGreaterThan(0);
+
+      await transport.disconnect();
+    });
+
+    it('stores a message in a conversation', async () => {
+      const sender = new LocalTransport();
+      const receiver = new LocalTransport();
+      await sender.connect(testConfig('sender'));
+      await receiver.connect(testConfig('receiver'));
+
+      // First push creates a DM conversation, then use that ID
+      const dm = await sender.push('receiver', 'setup');
+      const messages = await receiver.poll();
+      expect(messages).toHaveLength(1);
+      const convId = messages[0].threadId;
+      expect(convId).toBeDefined();
+
+      // Now send within that conversation
+      const result = await sender.push('receiver', 'group msg', {
+        conversationId: convId,
+      });
+      expect(result.messageId).toBeDefined();
+
+      await sender.disconnect();
+      await receiver.disconnect();
+    });
+
+    it('throws when not connected', async () => {
+      const transport = new LocalTransport();
+      await expect(transport.push('to', 'content')).rejects.toThrow('not connected');
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Poll
+  // --------------------------------------------------------------------------
+
+  describe('poll', () => {
+    it('returns messages addressed to the connected agent', async () => {
+      const sender = new LocalTransport();
+      const receiver = new LocalTransport();
+
+      await sender.connect(testConfig('sender'));
+      await receiver.connect(testConfig('receiver'));
+
+      await sender.push('receiver', 'message 1');
+      await sender.push('receiver', 'message 2');
+
+      const messages = await receiver.poll();
+      expect(messages).toHaveLength(2);
+      expect(messages[0].from).toBe('sender');
+      expect(messages[0].content).toBe('message 1');
+      expect(messages[1].content).toBe('message 2');
+
+      await sender.disconnect();
+      await receiver.disconnect();
+    });
+
+    it('returns empty array when no messages', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig('lonely'));
+
+      const messages = await transport.poll();
+      expect(messages).toHaveLength(0);
+
+      await transport.disconnect();
+    });
+
+    it('respects limit parameter', async () => {
+      const sender = new LocalTransport();
+      const receiver = new LocalTransport();
+
+      await sender.connect(testConfig('sender'));
+      await receiver.connect(testConfig('receiver'));
+
+      for (let i = 0; i < 5; i++) {
+        await sender.push('receiver', `msg ${i}`);
+      }
+
+      const messages = await receiver.poll({ limit: 2 });
+      expect(messages).toHaveLength(2);
+
+      await sender.disconnect();
+      await receiver.disconnect();
+    });
+
+    it('returns messages oldest first', async () => {
+      const sender = new LocalTransport();
+      const receiver = new LocalTransport();
+
+      await sender.connect(testConfig('sender'));
+      await receiver.connect(testConfig('receiver'));
+
+      await sender.push('receiver', 'first');
+      await sender.push('receiver', 'second');
+      await sender.push('receiver', 'third');
+
+      const messages = await receiver.poll();
+      expect(messages[0].content).toBe('first');
+      expect(messages[2].content).toBe('third');
+
+      await sender.disconnect();
+      await receiver.disconnect();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Ack
+  // --------------------------------------------------------------------------
+
+  describe('ack', () => {
+    it('marks messages as delivered so they are not re-polled', async () => {
+      const sender = new LocalTransport();
+      const receiver = new LocalTransport();
+
+      await sender.connect(testConfig('sender'));
+      await receiver.connect(testConfig('receiver'));
+
+      await sender.push('receiver', 'ack me');
+      const before = await receiver.poll();
+      expect(before).toHaveLength(1);
+
+      await receiver.ack([before[0].id]);
+
+      const after = await receiver.poll();
+      expect(after).toHaveLength(0);
+
+      await sender.disconnect();
+      await receiver.disconnect();
+    });
+
+    it('handles empty messageIds array', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig());
+      await transport.ack([]);
+      await transport.disconnect();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Subscribe
+  // --------------------------------------------------------------------------
+
+  describe('subscribe', () => {
+    it('notifies subscribers on push', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig('agent'));
+
+      const received: string[] = [];
+      const unsub = transport.subscribe((msg) => {
+        received.push(msg.content);
+      });
+
+      await transport.push('someone', 'hello');
+      expect(received).toContain('hello');
+
+      unsub();
+      await transport.disconnect();
+    });
+
+    it('returns unsubscribe function that stops notifications', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig('agent'));
+
+      const received: string[] = [];
+      const unsub = transport.subscribe((msg) => {
+        received.push(msg.content);
+      });
+
+      await transport.push('someone', 'before');
+      unsub();
+      await transport.push('someone', 'after');
+
+      expect(received).toContain('before');
+      expect(received).not.toContain('after');
+
+      await transport.disconnect();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Disconnect
+  // --------------------------------------------------------------------------
+
+  describe('disconnect', () => {
+    it('clears state and is safe to call twice', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig());
+      await transport.disconnect();
+      await transport.disconnect(); // Should not throw
+    });
+
+    it('makes subsequent operations throw', async () => {
+      const transport = new LocalTransport();
+      await transport.connect(testConfig());
+      await transport.disconnect();
+      await expect(transport.poll()).rejects.toThrow('not connected');
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Static
+  // --------------------------------------------------------------------------
+
+  describe('isAvailable', () => {
+    it('returns true when signaldock.db exists', () => {
+      expect(LocalTransport.isAvailable(testDir)).toBe(true);
+    });
+
+    it('returns false when signaldock.db is missing', () => {
+      const emptyDir = join(tmpdir(), `no-db-${Date.now()}`);
+      mkdirSync(emptyDir, { recursive: true });
+      expect(LocalTransport.isAvailable(emptyDir)).toBe(false);
+      rmSync(emptyDir, { recursive: true, force: true });
+    });
+  });
+});

package/src/conduit/__tests__/sse-transport.test.ts

@@ -0,0 +1,344 @@
+/**
+ * SseTransport test scenarios.
+ *
+ * Tests for the Server-Sent Events transport implementation.
+ * SseTransport extends HTTP polling with real-time push via SSE,
+ * falling back to HTTP polling when SSE is unavailable.
+ *
+ * @see packages/contracts/src/transport.ts — Transport interface
+ * @see packages/contracts/src/conduit.ts — ConduitState types
+ * @task T216
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { SseTransport } from '../sse-transport.js';
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+/** Mock SSE event source that simulates server-sent events. */
+function createMockEventSource() {
+  const handlers: Record<string, ((event: MessageEvent) => void)[]> = {};
+  return {
+    addEventListener: vi.fn((type: string, handler: (event: MessageEvent) => void) => {
+      handlers[type] = handlers[type] || [];
+      handlers[type].push(handler);
+    }),
+    removeEventListener: vi.fn(),
+    close: vi.fn(),
+    readyState: 0, // CONNECTING
+    /** Simulate receiving an SSE event. */
+    _emit(type: string, data: string) {
+      for (const h of handlers[type] || []) {
+        h(new MessageEvent(type, { data }));
+      }
+    },
+    /** Simulate connection open. */
+    _open() {
+      this.readyState = 1; // OPEN
+      for (const h of handlers['open'] || []) {
+        h(new MessageEvent('open', { data: '' }));
+      }
+    },
+    /** Simulate connection error. */
+    _error() {
+      this.readyState = 2; // CLOSED
+      for (const h of handlers['error'] || []) {
+        h(new MessageEvent('error', { data: '' }));
+      }
+    },
+  };
+}
+
+/** Standard test config for SseTransport. */
+const TEST_CONFIG = {
+  agentId: 'test-agent',
+  apiKey: 'sk_live_test123',
+  apiBaseUrl: 'https://api.signaldock.io',
+  sseEndpoint: 'https://api.signaldock.io/sse',
+};
+
+// ============================================================================
+// Connection lifecycle
+// ============================================================================
+
+describe('SseTransport', () => {
+  describe('connect', () => {
+    it.todo('should establish SSE connection to sseEndpoint');
+    // Expected behavior:
+    // - Creates EventSource to config.sseEndpoint with auth headers
+    // - Sets transport name to 'sse'
+    // - Transitions state: disconnected → connecting → connected
+    // - Resolves when EventSource 'open' event fires
+
+    it.todo('should fall back to HTTP polling when SSE endpoint is unreachable');
+    // Expected behavior:
+    // - Attempts SSE connection
+    // - On connection error, transitions to HTTP polling mode
+    // - State: disconnected → connecting → connected (via HTTP fallback)
+    // - Logs warning: "SSE unavailable, falling back to HTTP polling"
+    // - poll() still works via HTTP
+
+    it.todo('should include auth headers in SSE connection');
+    // Expected behavior:
+    // - EventSource URL includes ?token=<apiKey> (SSE doesn't support custom headers)
+    // - Or uses a pre-flight auth endpoint to get a session token
+    // - X-Agent-Id is conveyed via query param or pre-flight
+
+    it.todo('should reject connect when no sseEndpoint or apiBaseUrl is configured');
+    // Expected behavior:
+    // - Throws Error with message indicating missing config
+    // - State remains 'disconnected'
+
+    it('rejects connect when no sseEndpoint or apiBaseUrl provided', async () => {
+      const transport = new SseTransport();
+      await expect(
+        transport.connect({ agentId: 'test', apiKey: 'key', apiBaseUrl: '' }),
+      ).rejects.toThrow('requires');
+    });
+
+    it.todo('should reject connect when already connected');
+    // Expected behavior:
+    // - Second connect() call throws or is no-op
+    // - Does not create duplicate EventSource instances
+
+    it('has name "sse"', () => {
+      const transport = new SseTransport();
+      expect(transport.name).toBe('sse');
+    });
+  });
+
+  // ============================================================================
+  // Disconnect
+  // ============================================================================
+
+  describe('disconnect', () => {
+    it.todo('should close SSE connection and clear state');
+    // Expected behavior:
+    // - Calls EventSource.close()
+    // - Clears internal state
+    // - State: connected → disconnected
+    // - Subsequent push/poll calls throw "not connected"
+
+    it.todo('should be idempotent when already disconnected');
+    // Expected behavior:
+    // - No error when calling disconnect() on already disconnected transport
+    // - State remains 'disconnected'
+
+    it('is safe to call disconnect when not connected', async () => {
+      const transport = new SseTransport();
+      await transport.disconnect(); // Should not throw
+      await transport.disconnect(); // Still should not throw
+    });
+
+    it.todo('should cancel any pending poll timers');
+    // Expected behavior:
+    // - If HTTP fallback polling is active, clears interval
+    // - No orphaned timers after disconnect
+  });
+
+  // ============================================================================
+  // Reconnect
+  // ============================================================================
+
+  describe('reconnect', () => {
+    it.todo('should automatically reconnect on SSE connection drop');
+    // Expected behavior:
+    // - When EventSource fires 'error' and readyState becomes CLOSED
+    // - State: connected → reconnecting
+    // - Exponential backoff: 1s, 2s, 4s, 8s, max 30s
+    // - On successful reconnect: state → connected
+    // - Messages received during reconnect are not lost (server-side cursor)
+
+    it.todo('should fall back to HTTP polling after N failed SSE reconnects');
+    // Expected behavior:
+    // - After 3 failed SSE reconnect attempts
+    // - Permanently switches to HTTP polling mode for this session
+    // - State: reconnecting → connected (via HTTP)
+    // - Logs: "SSE reconnect failed 3 times, switching to HTTP polling"
+
+    it.todo('should preserve message cursor across reconnect');
+    // Expected behavior:
+    // - Tracks last received message ID or timestamp
+    // - Reconnect URL includes ?lastEventId=<cursor>
+    // - Server replays missed messages from cursor
+    // - No duplicate messages delivered to consumer
+
+    it.todo('should emit state change events during reconnect cycle');
+    // Expected behavior:
+    // - onStateChange fires: connected → reconnecting → connected
+    // - Or: connected → reconnecting → error (if max retries exceeded)
+  });
+
+  // ============================================================================
+  // Message receive (SSE mode)
+  // ============================================================================
+
+  describe('message receive via SSE', () => {
+    it.todo('should deliver incoming SSE messages via poll() return');
+    // Expected behavior:
+    // - SSE 'message' events are buffered internally
+    // - poll() returns buffered messages and clears buffer
+    // - Messages conform to ConduitMessage interface
+
+    it.todo('should parse SSE data field as JSON ConduitMessage');
+    // Expected behavior:
+    // - SSE data: {"id":"msg-1","from":"agent-a","content":"hello","timestamp":"..."}
+    // - Parsed into ConduitMessage with all fields populated
+
+    it.todo('should handle malformed SSE data gracefully');
+    // Expected behavior:
+    // - Invalid JSON in SSE data field does not crash transport
+    // - Malformed messages are logged and skipped
+    // - poll() returns only valid messages
+
+    it.todo('should filter self-sent messages');
+    // Expected behavior:
+    // - Messages where from === config.agentId are excluded from poll()
+    // - Prevents echo of own messages
+
+    it.todo('should support SSE event types for different message categories');
+    // Expected behavior:
+    // - 'message' event: standard agent messages
+    // - 'heartbeat' event: keep-alive (ignored in poll output)
+    // - 'system' event: system notifications (e.g., agent online/offline)
+  });
+
+  // ============================================================================
+  // Send with SSE down (fallback to HTTP)
+  // ============================================================================
+
+  describe('send (push)', () => {
+    it.todo('should send messages via HTTP POST regardless of SSE state');
+    // Expected behavior:
+    // - push() always uses HTTP POST (SSE is receive-only)
+    // - POST /conversations/{conversationId}/messages or /agents/{to}/messages
+    // - Returns { messageId } from response
+    // - Works whether SSE is connected, reconnecting, or fallen back to HTTP
+
+    it.todo('should send messages when SSE is connected');
+    // Expected behavior:
+    // - SSE connection is active for receiving
+    // - push() uses HTTP POST for sending (SSE is unidirectional)
+    // - Both channels work simultaneously
+
+    it.todo('should send messages when SSE is down and in HTTP fallback mode');
+    // Expected behavior:
+    // - SSE connection has failed, transport is in HTTP polling mode
+    // - push() still works via HTTP POST
+    // - No difference in send behavior between SSE and HTTP modes
+
+    it.todo('should retry failed sends with exponential backoff');
+    // Expected behavior:
+    // - On HTTP 5xx or network error, retry up to 3 times
+    // - Backoff: 500ms, 1s, 2s
+    // - On 4xx (client error), fail immediately (no retry)
+    // - Returns error after max retries
+
+    it.todo('should throw when not connected');
+    // Expected behavior:
+    // - push() before connect() throws "Transport not connected"
+    // - push() after disconnect() throws "Transport not connected"
+
+    it('throws when push is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.push('to', 'msg')).rejects.toThrow('not connected');
+    });
+
+    it('throws when poll is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.poll()).rejects.toThrow('not connected');
+    });
+
+    it('throws when ack is called before connect', async () => {
+      const transport = new SseTransport();
+      await expect(transport.ack(['id'])).rejects.toThrow('not connected');
+    });
+  });
+
+  // ============================================================================
+  // Poll (hybrid mode)
+  // ============================================================================
+
+  describe('poll', () => {
+    it.todo('should return SSE-buffered messages when SSE is active');
+    // Expected behavior:
+    // - In SSE mode, poll() drains the internal message buffer
+    // - Does NOT make an HTTP request (messages arrive via SSE push)
+    // - Returns empty array if no new messages since last poll
+
+    it.todo('should fall back to HTTP polling when SSE is down');
+    // Expected behavior:
+    // - In HTTP fallback mode, poll() makes GET /messages/peek
+    // - Behaves identically to HttpTransport.poll()
+    // - Respects limit and since options
+
+    it.todo('should respect since parameter for cursor-based retrieval');
+    // Expected behavior:
+    // - poll({ since: '2026-03-30T20:00:00Z' }) returns only newer messages
+    // - In SSE mode: filters buffer by timestamp
+    // - In HTTP mode: passes as query param
+  });
+
+  // ============================================================================
+  // Acknowledge
+  // ============================================================================
+
+  describe('ack', () => {
+    it.todo('should acknowledge messages via HTTP POST');
+    // Expected behavior:
+    // - ack(['msg-1', 'msg-2']) sends POST /messages/ack
+    // - Works in both SSE and HTTP modes (always HTTP for ack)
+    // - Acknowledged messages are not returned by subsequent poll()
+  });
+
+  // ============================================================================
+  // Heartbeat
+  // ============================================================================
+
+  describe('heartbeat', () => {
+    it.todo('should send heartbeat via HTTP POST');
+    // Expected behavior:
+    // - POST /agents/{agentId}/heartbeat
+    // - Works in both SSE and HTTP modes
+    // - Does not depend on SSE connection state
+
+    it.todo('should detect SSE connection health from heartbeat response');
+    // Expected behavior:
+    // - Heartbeat response may include SSE connection status
+    // - If server reports SSE session expired, trigger reconnect
+  });
+
+  // ============================================================================
+  // Edge cases
+  // ============================================================================
+
+  describe('edge cases', () => {
+    it.todo('should handle rapid connect/disconnect cycles');
+    // Expected behavior:
+    // - connect() → disconnect() → connect() in quick succession
+    // - No resource leaks (EventSource properly closed)
+    // - Final state is consistent
+
+    it.todo('should handle server-initiated SSE close');
+    // Expected behavior:
+    // - Server sends SSE close/shutdown event
+    // - Transport transitions to reconnecting or HTTP fallback
+    // - No unhandled errors
+
+    it.todo('should handle network going offline then online');
+    // Expected behavior:
+    // - SSE connection drops (network offline)
+    // - Reconnect attempts fail (network offline)
+    // - When network returns, reconnect succeeds
+    // - Messages buffered server-side are delivered
+
+    it.todo('should not leak EventSource instances on repeated reconnects');
+    // Expected behavior:
+    // - Each reconnect properly closes the previous EventSource
+    // - No accumulation of open connections
+    // - Memory usage stays constant
+  });
+});