@cleocode/core 2026.3.76 → 2026.4.0

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

package/src/conduit/sse-transport.ts

@@ -0,0 +1,382 @@
+/**
+ * SseTransport — Server-Sent Events transport with HTTP polling fallback.
+ *
+ * Receives messages in real-time via SSE from the SignalDock v2 API.
+ * Sends messages and acks via HTTP POST (SSE is receive-only).
+ * Falls back to HTTP polling when SSE is unavailable or disconnects.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 4.4
+ * @task T216
+ */
+
+import type { ConduitMessage, Transport, TransportConnectConfig } from '@cleocode/contracts';
+
+/** Maximum reconnect attempts before permanent HTTP fallback. */
+const MAX_RECONNECT_ATTEMPTS = 3;
+
+/** Maximum reconnect delay in milliseconds. */
+const MAX_RECONNECT_DELAY_MS = 30_000;
+
+/** SSE transport mode. */
+type SseMode = 'sse' | 'http-fallback';
+
+/** Internal connection state. */
+interface SseTransportState {
+  agentId: string;
+  apiKey: string;
+  apiBaseUrl: string;
+  sseEndpoint: string;
+  eventSource: EventSource | null;
+  mode: SseMode;
+  messageBuffer: ConduitMessage[];
+  subscribers: Set<(message: ConduitMessage) => void>;
+  reconnectAttempts: number;
+  reconnectTimer: ReturnType<typeof setTimeout> | null;
+  connected: boolean;
+}
+
+/** SseTransport — real-time SSE with HTTP polling fallback. */
+export class SseTransport implements Transport {
+  readonly name = 'sse';
+  private state: SseTransportState | null = null;
+
+  /**
+   * Connect to the SSE endpoint for real-time message delivery.
+   *
+   * If SSE connection fails, falls back to HTTP polling mode.
+   * Auth is conveyed via query parameter (SSE doesn't support custom headers).
+   */
+  async connect(config: TransportConnectConfig): Promise<void> {
+    if (this.state?.connected) {
+      throw new Error('SseTransport already connected. Disconnect first.');
+    }
+
+    const sseEndpoint = config.sseEndpoint;
+    if (!sseEndpoint && !config.apiBaseUrl) {
+      throw new Error('SseTransport requires sseEndpoint or apiBaseUrl in config.');
+    }
+
+    const endpoint = sseEndpoint ?? `${config.apiBaseUrl}/messages/stream`;
+
+    this.state = {
+      agentId: config.agentId,
+      apiKey: config.apiKey,
+      apiBaseUrl: config.apiBaseUrl,
+      sseEndpoint: endpoint,
+      eventSource: null,
+      mode: 'sse',
+      messageBuffer: [],
+      subscribers: new Set(),
+      reconnectAttempts: 0,
+      reconnectTimer: null,
+      connected: false,
+    };
+
+    try {
+      await this.connectSse();
+    } catch {
+      // SSE failed — fall back to HTTP polling
+      this.state.mode = 'http-fallback';
+      this.state.connected = true;
+    }
+  }
+
+  /** Disconnect the transport, closing SSE and clearing all state. */
+  async disconnect(): Promise<void> {
+    if (!this.state) return;
+
+    if (this.state.eventSource) {
+      this.state.eventSource.close();
+    }
+    if (this.state.reconnectTimer) {
+      clearTimeout(this.state.reconnectTimer);
+    }
+    this.state.messageBuffer = [];
+    this.state.connected = false;
+    this.state = null;
+  }
+
+  /**
+   * Send a message via HTTP POST.
+   *
+   * SSE is receive-only — all sends go through HTTP regardless of SSE state.
+   */
+  async push(
+    to: string,
+    content: string,
+    options?: { conversationId?: string; replyTo?: string },
+  ): Promise<{ messageId: string }> {
+    this.ensureConnected();
+
+    const body: Record<string, string> = { content, toAgentId: to };
+    let path = '/messages';
+
+    if (options?.conversationId) {
+      path = `/conversations/${options.conversationId}/messages`;
+      if (options.replyTo) {
+        body['replyTo'] = options.replyTo;
+      }
+    }
+
+    const response = await this.httpFetch(path, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new Error(`SseTransport push failed: ${response.status} ${text}`);
+    }
+
+    const data = (await response.json()) as {
+      data?: { message?: { id?: string }; id?: string };
+    };
+    return { messageId: data.data?.message?.id ?? data.data?.id ?? 'unknown' };
+  }
+
+  /**
+   * Poll for messages.
+   *
+   * In SSE mode: drains the internal message buffer (no HTTP request).
+   * In HTTP fallback mode: fetches via GET /messages/peek.
+   */
+  async poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
+    this.ensureConnected();
+
+    if (this.state!.mode === 'sse' && this.state!.eventSource) {
+      // Drain buffer — messages arrived via SSE push
+      let messages = this.state!.messageBuffer.splice(0);
+
+      if (options?.since) {
+        messages = messages.filter((m) => m.timestamp > options.since!);
+      }
+      if (options?.limit && messages.length > options.limit) {
+        // Put excess back in buffer
+        const excess = messages.splice(options.limit);
+        this.state!.messageBuffer.unshift(...excess);
+      }
+      return messages;
+    }
+
+    // HTTP fallback mode
+    return this.httpPoll(options);
+  }
+
+  /** Acknowledge messages via HTTP POST. */
+  async ack(messageIds: string[]): Promise<void> {
+    this.ensureConnected();
+    if (messageIds.length === 0) return;
+
+    await this.httpFetch('/messages/ack', {
+      method: 'POST',
+      body: JSON.stringify({ messageIds }),
+    });
+  }
+
+  /**
+   * Subscribe to real-time messages.
+   *
+   * In SSE mode, messages are pushed to the handler as they arrive.
+   * In HTTP fallback mode, polls on an interval.
+   */
+  subscribe(handler: (message: ConduitMessage) => void): () => void {
+    this.ensureConnected();
+
+    this.state!.subscribers.add(handler);
+
+    // Start HTTP polling interval only if in fallback mode
+    const interval =
+      this.state!.mode === 'http-fallback'
+        ? setInterval(async () => {
+            if (this.state?.mode === 'http-fallback') {
+              const messages = await this.httpPoll({ limit: 20 });
+              for (const msg of messages) handler(msg);
+              if (messages.length > 0) {
+                await this.ack(messages.map((m) => m.id));
+              }
+            }
+          }, 5000)
+        : null;
+
+    return () => {
+      if (interval) clearInterval(interval);
+      if (this.state) {
+        this.state.subscribers.delete(handler);
+      }
+    };
+  }
+
+  // --------------------------------------------------------------------------
+  // SSE connection management
+  // --------------------------------------------------------------------------
+
+  /** Establish SSE connection. Resolves when open, rejects on error. */
+  private connectSse(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      if (!this.state) {
+        reject(new Error('No state'));
+        return;
+      }
+
+      // SSE doesn't support custom headers — auth via query param
+      const url = `${this.state.sseEndpoint}?token=${encodeURIComponent(this.state.apiKey)}&agent_id=${encodeURIComponent(this.state.agentId)}`;
+
+      const es = new EventSource(url);
+      this.state.eventSource = es;
+
+      const timeout = setTimeout(() => {
+        es.close();
+        reject(new Error('SSE connection timeout'));
+      }, 10_000);
+
+      es.addEventListener('open', () => {
+        clearTimeout(timeout);
+        this.state!.connected = true;
+        this.state!.reconnectAttempts = 0;
+        resolve();
+      });
+
+      es.addEventListener('message', (event: MessageEvent) => {
+        this.handleSseMessage(event);
+      });
+
+      es.addEventListener('error', () => {
+        clearTimeout(timeout);
+        if (!this.state!.connected) {
+          // Initial connection failed
+          es.close();
+          reject(new Error('SSE connection failed'));
+        } else {
+          // Connection dropped — attempt reconnect
+          this.handleSseDisconnect();
+        }
+      });
+    });
+  }
+
+  /** Handle an incoming SSE message event. */
+  private handleSseMessage(event: MessageEvent): void {
+    if (!this.state) return;
+
+    try {
+      const data = JSON.parse(event.data as string) as {
+        id?: string;
+        from_agent_id?: string;
+        from?: string;
+        content?: string;
+        conversation_id?: string;
+        threadId?: string;
+        created_at?: string;
+        timestamp?: string;
+        type?: string;
+      };
+
+      // Skip heartbeat events
+      if (data.type === 'heartbeat' || data.type === 'ping') return;
+
+      // Skip self-sent messages
+      const from = data.from_agent_id ?? data.from ?? 'unknown';
+      if (from === this.state.agentId) return;
+
+      const message: ConduitMessage = {
+        id: data.id ?? `sse-${Date.now()}`,
+        from,
+        content: data.content ?? '',
+        threadId: data.conversation_id ?? data.threadId,
+        timestamp: data.created_at ?? data.timestamp ?? new Date().toISOString(),
+      };
+
+      this.state.messageBuffer.push(message);
+      for (const h of this.state.subscribers) {
+        try {
+          h(message);
+        } catch {
+          /* subscriber error must not crash transport */
+        }
+      }
+    } catch {
+      // Malformed SSE data — skip silently
+    }
+  }
+
+  /** Handle SSE connection drop — attempt reconnect with backoff. */
+  private handleSseDisconnect(): void {
+    if (!this.state) return;
+
+    this.state.eventSource?.close();
+    this.state.eventSource = null;
+    this.state.reconnectAttempts++;
+
+    if (this.state.reconnectAttempts > MAX_RECONNECT_ATTEMPTS) {
+      // Switch to permanent HTTP fallback
+      this.state.mode = 'http-fallback';
+      return;
+    }
+
+    // Exponential backoff: 1s, 2s, 4s, ...
+    const delay = Math.min(1000 * 2 ** (this.state.reconnectAttempts - 1), MAX_RECONNECT_DELAY_MS);
+
+    this.state.reconnectTimer = setTimeout(() => {
+      void this.connectSse().catch(() => {
+        this.handleSseDisconnect();
+      });
+    }, delay);
+  }
+
+  // --------------------------------------------------------------------------
+  // HTTP helpers
+  // --------------------------------------------------------------------------
+
+  /** HTTP poll for messages (used in fallback mode). */
+  private async httpPoll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]> {
+    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.httpFetch(`/messages/peek?${params}`, { method: 'GET' });
+    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(),
+    }));
+  }
+
+  /** Make an authenticated HTTP request to the API. */
+  private async httpFetch(path: string, init: RequestInit): Promise<Response> {
+    const url = `${this.state!.apiBaseUrl}${path}`;
+    return fetch(url, {
+      ...init,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.state!.apiKey}`,
+        'X-Agent-Id': this.state!.agentId,
+        ...(init.headers as Record<string, string>),
+      },
+      signal: init.signal ?? AbortSignal.timeout(10_000),
+    });
+  }
+
+  /** Throw if not connected. */
+  private ensureConnected(): void {
+    if (!this.state?.connected) {
+      throw new Error('SseTransport not connected. Call connect() first.');
+    }
+  }
+}

package/src/index.ts

@@ -33,6 +33,7 @@ export * as admin from './admin/index.js';
 export * as adrs from './adrs/index.js';
 export * as agents from './agents/index.js';
 export * as caamp from './caamp/index.js';
+export * as code from './code/index.js';
 export * as codebaseMap from './codebase-map/index.js';
 export * as compliance from './compliance/index.js';
 export * as conduit from './conduit/index.js';