@cleocode/core 2026.3.76 → 2026.4.0

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
+  });
+});

package/src/conduit/conduit-client.ts

@@ -25,19 +25,23 @@ export class ConduitClient implements Conduit {
   private credential: AgentCredential;
   private state: ConduitState = 'disconnected';
 
+  /** Create a ConduitClient backed by the given transport and credential. */
   constructor(transport: Transport, credential: AgentCredential) {
     this.transport = transport;
     this.credential = credential;
   }
 
+  /** The agent ID from the bound credential. */
   get agentId(): string {
     return this.credential.agentId;
   }
 
+  /** Current connection state (disconnected → connecting → connected | error). */
   getState(): ConduitState {
     return this.state;
   }
 
+  /** Connect the underlying transport using the bound credential. */
   async connect(): Promise<void> {
     this.state = 'connecting';
     try {
@@ -55,6 +59,7 @@ export class ConduitClient implements Conduit {
     }
   }
 
+  /** Send a message to another agent, optionally within a thread. */
   async send(
     to: string,
     content: string,
@@ -69,6 +74,7 @@ export class ConduitClient implements Conduit {
     };
   }
 
+  /** Subscribe to incoming messages. Uses real-time transport when available, else polls. */
   onMessage(handler: (message: ConduitMessage) => void): ConduitUnsubscribe {
     // Prefer real-time subscription if transport supports it
     if (this.transport.subscribe) {
@@ -85,11 +91,13 @@ export class ConduitClient implements Conduit {
     return () => clearInterval(interval);
   }
 
+  /** Send an empty heartbeat to maintain presence on the relay. */
   async heartbeat(): Promise<void> {
     // Send empty heartbeat via transport
     await this.transport.push(this.credential.agentId, '', {});
   }
 
+  /** Check whether a remote agent is currently online via the cloud API. */
   async isOnline(agentId: string): Promise<boolean> {
     // Delegate to cloud API check — stub for now
     try {
@@ -107,6 +115,7 @@ export class ConduitClient implements Conduit {
     }
   }
 
+  /** Disconnect the transport and reset state to disconnected. */
   async disconnect(): Promise<void> {
     await this.transport.disconnect();
     this.state = 'disconnected';

package/src/conduit/factory.ts

@@ -11,16 +11,20 @@
 import type { AgentCredential, AgentRegistryAPI, Conduit, Transport } from '@cleocode/contracts';
 import { ConduitClient } from './conduit-client.js';
 import { HttpTransport } from './http-transport.js';
+import { LocalTransport } from './local-transport.js';
+import { SseTransport } from './sse-transport.js';
 
 /** Resolve the best available transport for a credential. */
-function resolveTransport(credential: AgentCredential): Transport {
-  // Priority: Local (napi-rs) > WebSocket > SSE > HTTP polling
-  // LocalTransport and SseTransport are future — stubs not yet implemented
+export function resolveTransport(credential: AgentCredential): Transport {
+  // Priority: Local (SQLite) > WebSocket > SSE > HTTP polling
+  if (LocalTransport.isAvailable()) {
+    return new LocalTransport();
+  }
   if (credential.transportConfig.wsUrl) {
-    // WsTransport stub — fall through to HTTP for now
+    // WsTransport — fall through to SSE/HTTP for now
   }
   if (credential.transportConfig.sseEndpoint) {
-    // SseTransport stub — fall through to HTTP for now
+    return new SseTransport();
   }
   return new HttpTransport();
 }

package/src/conduit/http-transport.ts

@@ -1,9 +1,10 @@
 /**
- * HttpTransport — HTTP polling transport to cloud SignalDock API.
+ * HttpTransport — HTTP polling transport with automatic failover.
  *
- * Implements the Transport interface using HTTP requests to the SignalDock
- * (api.signaldock.io) REST API. This is the default transport for
- * cloud-connected agents.
+ * Tries the primary API URL (api.signaldock.io) first. If unreachable,
+ * falls back to the legacy URL (api.clawmsgr.com). Failover is transparent
+ * to callers — they see a single transport that always works if either
+ * endpoint is up.
  *
  * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.4
  * @task T177
@@ -15,28 +16,52 @@ import type { ConduitMessage, Transport, TransportConnectConfig } from '@cleocod
 interface HttpTransportState {
   agentId: string;
   apiKey: string;
-  apiBaseUrl: string;
+  primaryUrl: string;
+  fallbackUrl: string | null;
+  activeUrl: string;
   connected: boolean;
 }
 
-/** HTTP polling transport to cloud SignalDock API. */
+/** HTTP transport with automatic primary/fallback failover. */
 export class HttpTransport implements Transport {
   readonly name = 'http';
   private state: HttpTransportState | null = null;
 
+  /** Connect to the SignalDock API, probing primary/fallback health when both are configured. */
   async connect(config: TransportConnectConfig): Promise<void> {
+    const primaryUrl = config.apiBaseUrl;
+    const fallbackUrl = config.apiBaseUrlFallback ?? null;
+
+    // Only probe health when there's a fallback to choose between
+    let activeUrl = primaryUrl;
+    if (fallbackUrl) {
+      const [primaryResult, fallbackResult] = await Promise.allSettled([
+        fetch(`${primaryUrl}/health`, { method: 'GET', signal: AbortSignal.timeout(5000) }),
+        fetch(`${fallbackUrl}/health`, { method: 'GET', signal: AbortSignal.timeout(5000) }),
+      ]);
+      const primaryOk = primaryResult.status === 'fulfilled' && primaryResult.value.ok;
+      const fallbackOk = fallbackResult.status === 'fulfilled' && fallbackResult.value.ok;
+      if (!primaryOk && fallbackOk) {
+        activeUrl = fallbackUrl;
+      }
+    }
+
     this.state = {
       agentId: config.agentId,
       apiKey: config.apiKey,
-      apiBaseUrl: config.apiBaseUrl,
+      primaryUrl,
+      fallbackUrl,
+      activeUrl,
       connected: true,
     };
   }
 
+  /** Disconnect and clear connection state. */
   async disconnect(): Promise<void> {
     this.state = null;
   }
 
+  /** Send a message to an agent (direct or within a conversation thread). */
   async push(
     to: string,
     content: string,
@@ -46,18 +71,18 @@ export class HttpTransport implements Transport {
 
     const body: Record<string, string> = { content };
 
-    let url: string;
+    let path: string;
     if (options?.conversationId) {
-      url = `${this.state!.apiBaseUrl}/conversations/${options.conversationId}/messages`;
+      path = `/conversations/${options.conversationId}/messages`;
       if (options.replyTo) {
         body['replyTo'] = options.replyTo;
       }
     } else {
-      url = `${this.state!.apiBaseUrl}/messages`;
+      path = '/messages';
       body['toAgentId'] = to;
     }
 
-    const response = await fetch(url, {
+    const response = await this.fetchWithFallback(path, {
       method: 'POST',
       headers: this.headers(),
       body: JSON.stringify(body),
@@ -76,17 +101,16 @@ export class HttpTransport implements Transport {
     return { messageId };
   }
 
+  /** Poll for new messages mentioning this agent. Returns empty array on HTTP error. */
   async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
     this.ensureConnected();
 
     const params = new URLSearchParams();
     params.set('mentioned', this.state!.agentId);
     if (options?.limit) params.set('limit', String(options.limit));
-    // H5 fix: pass since param to avoid reprocessing old messages
     if (options?.since) params.set('since', options.since);
 
-    const url = `${this.state!.apiBaseUrl}/messages/peek?${params}`;
-    const response = await fetch(url, {
+    const response = await this.fetchWithFallback(`/messages/peek?${params}`, {
       method: 'GET',
       headers: this.headers(),
     });
@@ -114,16 +138,53 @@ export class HttpTransport implements Transport {
     }));
   }
 
+  /** Acknowledge messages by ID so they are not returned by future polls. */
   async ack(messageIds: string[]): Promise<void> {
     this.ensureConnected();
 
-    await fetch(`${this.state!.apiBaseUrl}/messages/ack`, {
+    await this.fetchWithFallback('/messages/ack', {
       method: 'POST',
       headers: this.headers(),
       body: JSON.stringify({ messageIds }),
     });
   }
 
+  /**
+   * Fetch with automatic failover. Tries activeUrl first.
+   * If it fails and a fallback exists, retries on the other URL
+   * and swaps activeUrl for subsequent calls.
+   */
+  private async fetchWithFallback(path: string, init: RequestInit): Promise<Response> {
+    const timeout = AbortSignal.timeout(10000);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+    const url = `${this.state!.activeUrl}${path}`;
+
+    try {
+      return await fetch(url, { ...init, signal });
+    } catch (primaryErr) {
+      const otherUrl =
+        this.state!.activeUrl === this.state!.primaryUrl
+          ? this.state!.fallbackUrl
+          : this.state!.primaryUrl;
+
+      if (!otherUrl) throw primaryErr;
+
+      try {
+        const fallbackSignal = init.signal
+          ? AbortSignal.any([init.signal, AbortSignal.timeout(10000)])
+          : AbortSignal.timeout(10000);
+        const fallbackResponse = await fetch(`${otherUrl}${path}`, {
+          ...init,
+          signal: fallbackSignal,
+        });
+        this.state!.activeUrl = otherUrl;
+        return fallbackResponse;
+      } catch {
+        throw primaryErr;
+      }
+    }
+  }
+
   private headers(): Record<string, string> {
     return {
       'Content-Type': 'application/json',

package/src/conduit/index.ts

@@ -2,11 +2,14 @@
  * Conduit — High-level agent messaging for the CLEO ecosystem.
  *
  * Exports the ConduitClient (high-level messaging), HttpTransport
- * (HTTP polling to cloud), and createConduit factory.
+ * (HTTP polling to cloud), LocalTransport (offline SQLite), and
+ * createConduit factory.
  *
  * @module conduit
  */
 
 export { ConduitClient } from './conduit-client.js';
-export { createConduit } from './factory.js';
+export { createConduit, resolveTransport } from './factory.js';
 export { HttpTransport } from './http-transport.js';
+export { LocalTransport } from './local-transport.js';
+export { SseTransport } from './sse-transport.js';