@cleocode/core 2026.3.76 → 2026.4.2

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,12 @@ export class ConduitClient implements Conduit {
     };
   }
 
+  /** One-shot poll for new messages. Delegates to the transport's poll method. */
+  async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
+    return this.transport.poll(options);
+  }
+
+  /** 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 +96,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 +120,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,17 +11,38 @@
 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
-  if (credential.transportConfig.wsUrl) {
-    // WsTransport stub — fall through to HTTP for now
+/**
+ * Resolve the best available transport for a credential.
+ *
+ * Cloud-backed agents (apiBaseUrl is a remote URL) use HttpTransport
+ * so they can receive messages from the SignalDock cloud relay.
+ * LocalTransport is only used when the agent is explicitly local-only
+ * (apiBaseUrl is 'local' or absent), since local signaldock.db doesn't
+ * sync with the cloud.
+ */
+export function resolveTransport(credential: AgentCredential): Transport {
+  const isCloudBacked =
+    credential.apiBaseUrl &&
+    credential.apiBaseUrl !== 'local' &&
+    credential.apiBaseUrl.startsWith('http');
+
+  // Cloud-backed agents must use network transports to receive cloud messages
+  if (isCloudBacked) {
+    if (credential.transportConfig.sseEndpoint) {
+      return new SseTransport();
+    }
+    return new HttpTransport();
   }
-  if (credential.transportConfig.sseEndpoint) {
-    // SseTransport stub — fall through to HTTP for now
+
+  // Local-only agents use LocalTransport when signaldock.db is available
+  if (LocalTransport.isAvailable()) {
+    return new LocalTransport();
   }
+
+  // Fallback to HTTP
   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,17 @@ export class HttpTransport implements Transport {
     return { messageId };
   }
 
+  /** Poll for new messages for 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);
+    // Don't filter by mentioned — the API already scopes by X-Agent-Id header.
+    // Using mentioned= misses messages sent TO this agent without @-mentions.
     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 +139,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';

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