@cleocode/core 2026.3.74 → 2026.4.0

package/src/conduit/conduit-client.ts

@@ -0,0 +1,123 @@
+/**
+ * ConduitClient — High-level agent messaging that wraps a Transport adapter.
+ *
+ * This is the WHAT layer: send messages, subscribe to events, manage presence.
+ * The Transport adapter (HttpTransport, LocalTransport, etc.) handles the HOW.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.3
+ * @task T177
+ */
+
+import type {
+  AgentCredential,
+  Conduit,
+  ConduitMessage,
+  ConduitSendOptions,
+  ConduitSendResult,
+  ConduitState,
+  ConduitUnsubscribe,
+  Transport,
+} from '@cleocode/contracts';
+
+/** ConduitClient wraps a Transport, adding high-level messaging semantics. */
+export class ConduitClient implements Conduit {
+  private transport: Transport;
+  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 {
+      await this.transport.connect({
+        agentId: this.credential.agentId,
+        apiKey: this.credential.apiKey,
+        apiBaseUrl: this.credential.apiBaseUrl,
+        ...this.credential.transportConfig,
+      });
+      this.state = 'connected';
+    } catch (err) {
+      // H6 fix: transition to 'error' state instead of stuck at 'connecting'
+      this.state = 'error';
+      throw err;
+    }
+  }
+
+  /** Send a message to another agent, optionally within a thread. */
+  async send(
+    to: string,
+    content: string,
+    options?: ConduitSendOptions,
+  ): Promise<ConduitSendResult> {
+    const result = await this.transport.push(to, content, {
+      conversationId: options?.threadId,
+    });
+    return {
+      messageId: result.messageId,
+      deliveredAt: new Date().toISOString(),
+    };
+  }
+
+  /** 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) {
+      return this.transport.subscribe(handler);
+    }
+    // Fallback: polling loop
+    const interval = setInterval(async () => {
+      const messages = await this.transport.poll();
+      for (const msg of messages) handler(msg);
+      if (messages.length > 0) {
+        await this.transport.ack(messages.map((m) => m.id));
+      }
+    }, this.credential.transportConfig.pollIntervalMs ?? 5000);
+    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 {
+      const response = await fetch(`${this.credential.apiBaseUrl}/agents/${agentId}`, {
+        headers: {
+          Authorization: `Bearer ${this.credential.apiKey}`,
+          'X-Agent-Id': this.credential.agentId,
+        },
+      });
+      if (!response.ok) return false;
+      const data = (await response.json()) as { data?: { agent?: { status?: string } } };
+      return data.data?.agent?.status === 'online';
+    } catch {
+      return false;
+    }
+  }
+
+  /** Disconnect the transport and reset state to disconnected. */
+  async disconnect(): Promise<void> {
+    await this.transport.disconnect();
+    this.state = 'disconnected';
+  }
+}

package/src/conduit/factory.ts

@@ -0,0 +1,49 @@
+/**
+ * Conduit factory — creates a Conduit instance from the agent registry.
+ *
+ * Auto-selects the appropriate Transport based on the agent's credential
+ * configuration. Priority: Local (napi-rs) > WebSocket > SSE > HTTP polling.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.5
+ * @task T177
+ */
+
+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. */
+export function resolveTransport(credential: AgentCredential): Transport {
+  // Priority: Local (SQLite) > WebSocket > SSE > HTTP polling
+  if (LocalTransport.isAvailable()) {
+    return new LocalTransport();
+  }
+  if (credential.transportConfig.wsUrl) {
+    // WsTransport — fall through to SSE/HTTP for now
+  }
+  if (credential.transportConfig.sseEndpoint) {
+    return new SseTransport();
+  }
+  return new HttpTransport();
+}
+
+/** Create a Conduit instance from the agent registry. */
+export async function createConduit(
+  registry: AgentRegistryAPI,
+  agentId?: string,
+): Promise<Conduit> {
+  const credential = agentId ? await registry.get(agentId) : await registry.getActive();
+
+  if (!credential) {
+    throw new Error(
+      'No agent credential found. Run: cleo agent register --id <id> --api-key <key>',
+    );
+  }
+
+  const transport = resolveTransport(credential);
+  const conduit = new ConduitClient(transport, credential);
+  await conduit.connect();
+  return conduit;
+}

package/src/conduit/http-transport.ts

@@ -0,0 +1,201 @@
+/**
+ * HttpTransport — HTTP polling transport with automatic failover.
+ *
+ * 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
+ */
+
+import type { ConduitMessage, Transport, TransportConnectConfig } from '@cleocode/contracts';
+
+/** Internal connection state. */
+interface HttpTransportState {
+  agentId: string;
+  apiKey: string;
+  primaryUrl: string;
+  fallbackUrl: string | null;
+  activeUrl: string;
+  connected: boolean;
+}
+
+/** 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,
+      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,
+    options?: { conversationId?: string; replyTo?: string },
+  ): Promise<{ messageId: string }> {
+    this.ensureConnected();
+
+    const body: Record<string, string> = { content };
+
+    let path: string;
+    if (options?.conversationId) {
+      path = `/conversations/${options.conversationId}/messages`;
+      if (options.replyTo) {
+        body['replyTo'] = options.replyTo;
+      }
+    } else {
+      path = '/messages';
+      body['toAgentId'] = to;
+    }
+
+    const response = await this.fetchWithFallback(path, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new Error(`HttpTransport push failed: ${response.status} ${text}`);
+    }
+
+    const data = (await response.json()) as {
+      success?: boolean;
+      data?: { message?: { id?: string }; id?: string };
+    };
+    const messageId = data.data?.message?.id ?? data.data?.id ?? 'unknown';
+    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));
+    if (options?.since) params.set('since', options.since);
+
+    const response = await this.fetchWithFallback(`/messages/peek?${params}`, {
+      method: 'GET',
+      headers: this.headers(),
+    });
+
+    if (!response.ok) return [];
+
+    const data = (await response.json()) as {
+      data?: {
+        messages?: Array<{
+          id: string;
+          fromAgentId?: string;
+          content?: string;
+          conversationId?: string;
+          createdAt?: string;
+        }>;
+      };
+    };
+
+    return (data.data?.messages ?? []).map((m) => ({
+      id: m.id,
+      from: m.fromAgentId ?? 'unknown',
+      content: m.content ?? '',
+      threadId: m.conversationId,
+      timestamp: m.createdAt ?? new Date().toISOString(),
+    }));
+  }
+
+  /** Acknowledge messages by ID so they are not returned by future polls. */
+  async ack(messageIds: string[]): Promise<void> {
+    this.ensureConnected();
+
+    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',
+      Authorization: `Bearer ${this.state!.apiKey}`,
+      'X-Agent-Id': this.state!.agentId,
+    };
+  }
+
+  private ensureConnected(): void {
+    if (!this.state?.connected) {
+      throw new Error('HttpTransport not connected. Call connect() first.');
+    }
+  }
+}

package/src/conduit/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Conduit — High-level agent messaging for the CLEO ecosystem.
+ *
+ * Exports the ConduitClient (high-level messaging), HttpTransport
+ * (HTTP polling to cloud), LocalTransport (offline SQLite), and
+ * createConduit factory.
+ *
+ * @module conduit
+ */
+
+export { ConduitClient } from './conduit-client.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';

package/src/conduit/local-transport.ts

@@ -0,0 +1,309 @@
+/**
+ * LocalTransport — In-process SQLite transport for fully offline agent messaging.
+ *
+ * Reads and writes messages directly to signaldock.db via node:sqlite.
+ * No network calls. Works fully offline. Messages are stored in the
+ * same schema that the Rust signaldock-storage crate manages, so both
+ * the local CLI and the cloud backend see the same data.
+ *
+ * Priority: LocalTransport is preferred over HttpTransport when
+ * signaldock.db is available (see factory.ts).
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.4
+ * @task T213
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import type { DatabaseSync } from 'node:sqlite';
+import type { ConduitMessage, Transport, TransportConnectConfig } from '@cleocode/contracts';
+import { getSignaldockDbPath } from '../store/signaldock-sqlite.js';
+
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof DatabaseSync>) => DatabaseSync;
+};
+
+/** Internal state for an active local transport connection. */
+interface LocalTransportState {
+  agentId: string;
+  db: DatabaseSync;
+  dbPath: string;
+  subscribers: Set<(message: ConduitMessage) => void>;
+  pollTimer: ReturnType<typeof setInterval> | null;
+}
+
+/** In-process SQLite transport for fully offline agent messaging. */
+export class LocalTransport implements Transport {
+  readonly name = 'local';
+  private state: LocalTransportState | null = null;
+
+  /**
+   * Connect to signaldock.db for in-process messaging.
+   *
+   * Opens the database, sets WAL mode pragmas, and verifies
+   * the messages table exists. Throws if signaldock.db is missing
+   * or uninitialized (run `cleo init` first).
+   */
+  async connect(config: TransportConnectConfig): Promise<void> {
+    const dbPath = getSignaldockDbPath();
+
+    if (!existsSync(dbPath)) {
+      throw new Error(`LocalTransport: signaldock.db not found at ${dbPath}. Run: cleo init`);
+    }
+
+    const db = new DatabaseSyncClass(dbPath);
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('PRAGMA foreign_keys = ON');
+
+    // Verify the messages table exists
+    const hasMessages = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages'")
+      .get() as { name: string } | undefined;
+
+    if (!hasMessages) {
+      db.close();
+      throw new Error(
+        'LocalTransport: signaldock.db exists but messages table missing. Run: cleo upgrade',
+      );
+    }
+
+    this.state = {
+      agentId: config.agentId,
+      db,
+      dbPath,
+      subscribers: new Set(),
+      pollTimer: null,
+    };
+  }
+
+  /** Close the database connection and stop any subscriber polling. */
+  async disconnect(): Promise<void> {
+    if (!this.state) return;
+
+    if (this.state.pollTimer) {
+      clearInterval(this.state.pollTimer);
+    }
+    this.state.subscribers.clear();
+    this.state.db.close();
+    this.state = null;
+  }
+
+  /**
+   * Store a message in signaldock.db.
+   *
+   * Inserts into the messages table with status 'pending'.
+   * For conversation messages, also links via conversation_participants
+   * if not already present.
+   */
+  async push(
+    to: string,
+    content: string,
+    options?: { conversationId?: string; replyTo?: string },
+  ): Promise<{ messageId: string }> {
+    this.ensureConnected();
+    const { db, agentId } = this.state!;
+    const messageId = randomUUID();
+    const nowUnix = Math.floor(Date.now() / 1000);
+
+    if (options?.conversationId) {
+      db.prepare(
+        `INSERT INTO messages (id, conversation_id, from_agent_id, to_agent_id, content, content_type, status, created_at)
+         VALUES (?, ?, ?, ?, ?, 'text', 'pending', ?)`,
+      ).run(messageId, options.conversationId, agentId, to, content, nowUnix);
+    } else {
+      // Direct message — create or reuse a DM conversation
+      const convId = this.ensureDmConversation(agentId, to);
+      db.prepare(
+        `INSERT INTO messages (id, conversation_id, from_agent_id, to_agent_id, content, content_type, status, created_at)
+         VALUES (?, ?, ?, ?, ?, 'text', 'pending', ?)`,
+      ).run(messageId, convId, agentId, to, content, nowUnix);
+    }
+
+    // Notify local subscribers
+    this.notifySubscribers({
+      id: messageId,
+      from: agentId,
+      content,
+      threadId: options?.conversationId,
+      timestamp: new Date(nowUnix * 1000).toISOString(),
+    });
+
+    return { messageId };
+  }
+
+  /**
+   * Poll for messages addressed to this agent.
+   *
+   * Returns messages with status 'pending' where to_agent_id matches
+   * the connected agent. Messages are returned oldest-first.
+   */
+  async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
+    this.ensureConnected();
+    const { db, agentId } = this.state!;
+    const limit = options?.limit ?? 50;
+
+    let query: string;
+    let params: (string | number)[];
+
+    if (options?.since) {
+      query = `SELECT id, from_agent_id, content, conversation_id, created_at
+               FROM messages
+               WHERE to_agent_id = ? AND status = 'pending' AND created_at > ?
+               ORDER BY created_at ASC
+               LIMIT ?`;
+      params = [agentId, options.since, limit];
+    } else {
+      query = `SELECT id, from_agent_id, content, conversation_id, created_at
+               FROM messages
+               WHERE to_agent_id = ? AND status = 'pending'
+               ORDER BY created_at ASC
+               LIMIT ?`;
+      params = [agentId, limit];
+    }
+
+    const rows = db.prepare(query).all(...params) as Array<{
+      id: string;
+      from_agent_id: string;
+      content: string;
+      conversation_id: string | null;
+      created_at: number;
+    }>;
+
+    return rows.map((r) => ({
+      id: r.id,
+      from: r.from_agent_id,
+      content: r.content,
+      threadId: r.conversation_id ?? undefined,
+      timestamp: new Date(r.created_at * 1000).toISOString(),
+    }));
+  }
+
+  /**
+   * Acknowledge messages by marking them as 'delivered'.
+   *
+   * Updates the status and delivered_at timestamp for each message ID.
+   */
+  async ack(messageIds: string[]): Promise<void> {
+    this.ensureConnected();
+    if (messageIds.length === 0) return;
+
+    const { db } = this.state!;
+    const nowUnix = Math.floor(Date.now() / 1000);
+
+    const placeholders = messageIds.map(() => '?').join(', ');
+    db.prepare(
+      `UPDATE messages SET status = 'delivered', delivered_at = ? WHERE id IN (${placeholders})`,
+    ).run(nowUnix, ...messageIds);
+  }
+
+  /**
+   * Subscribe to real-time local messages.
+   *
+   * Since this is in-process, subscribers are notified synchronously
+   * when push() is called. Additionally, a polling interval checks
+   * for messages inserted by other processes (e.g., Rust CLI).
+   *
+   * @returns Unsubscribe function.
+   */
+  subscribe(handler: (message: ConduitMessage) => void): () => void {
+    this.ensureConnected();
+    this.state!.subscribers.add(handler);
+
+    // Start cross-process polling if not already running
+    if (!this.state!.pollTimer && this.state!.subscribers.size === 1) {
+      this.state!.pollTimer = setInterval(() => {
+        void this.pollAndNotify();
+      }, 1000);
+    }
+
+    return () => {
+      this.state?.subscribers.delete(handler);
+      if (this.state?.subscribers.size === 0 && this.state.pollTimer) {
+        clearInterval(this.state.pollTimer);
+        this.state.pollTimer = null;
+      }
+    };
+  }
+
+  /**
+   * Check whether signaldock.db is available for local transport.
+   *
+   * Used by factory.ts to decide whether to use LocalTransport.
+   */
+  static isAvailable(cwd?: string): boolean {
+    const dbPath = getSignaldockDbPath(cwd);
+    return existsSync(dbPath);
+  }
+
+  /** Poll for new messages and notify subscribers (cross-process sync). */
+  private async pollAndNotify(): Promise<void> {
+    if (!this.state || this.state.subscribers.size === 0) return;
+
+    const messages = await this.poll({ limit: 20 });
+    for (const msg of messages) {
+      this.notifySubscribers(msg);
+    }
+    if (messages.length > 0) {
+      await this.ack(messages.map((m) => m.id));
+    }
+  }
+
+  /** Notify all active subscribers of a new message. */
+  private notifySubscribers(message: ConduitMessage): void {
+    if (!this.state) return;
+    for (const handler of this.state.subscribers) {
+      try {
+        handler(message);
+      } catch {
+        // Subscriber errors must not break the transport
+      }
+    }
+  }
+
+  /**
+   * Ensure a DM conversation exists between two agents.
+   *
+   * Conversations store participants as a comma-separated TEXT field.
+   * We search for existing private conversations containing both agents.
+   *
+   * @returns The conversation ID.
+   */
+  private ensureDmConversation(fromAgentId: string, toAgentId: string): string {
+    const { db } = this.state!;
+
+    // Participants are stored as comma-separated text, sorted alphabetically
+    const sortedParticipants = [fromAgentId, toAgentId].sort().join(',');
+
+    // Check for existing DM conversation with these exact participants
+    const existing = db
+      .prepare(
+        `SELECT id FROM conversations
+         WHERE visibility = 'private' AND participants = ?
+         LIMIT 1`,
+      )
+      .get(sortedParticipants) as { id: string } | undefined;
+
+    if (existing) return existing.id;
+
+    // Create new DM conversation
+    const convId = randomUUID();
+    const nowUnix = Math.floor(Date.now() / 1000);
+
+    db.prepare(
+      `INSERT INTO conversations (id, participants, visibility, message_count, created_at, updated_at)
+       VALUES (?, ?, 'private', 0, ?, ?)`,
+    ).run(convId, sortedParticipants, nowUnix, nowUnix);
+
+    return convId;
+  }
+
+  /** Throw if not connected. */
+  private ensureConnected(): void {
+    if (!this.state) {
+      throw new Error('LocalTransport not connected. Call connect() first.');
+    }
+  }
+}