@cleocode/core 2026.3.74 → 2026.4.0

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/crypto/credentials.ts

@@ -0,0 +1,166 @@
+/**
+ * Credential encryption — AES-256-GCM with machine-bound key derivation.
+ *
+ * API keys (`sk_live_*`) are encrypted at rest in SQLite using AES-256-GCM.
+ * The encryption key is derived per-project from a machine-specific secret:
+ *
+ *   machine-key (32 random bytes at ~/.local/share/cleo/machine-key)
+ *   + project path
+ *   = HMAC-SHA256(machine-key, project-path) → per-project AES key
+ *
+ * This means credentials are bound to BOTH the machine AND the project.
+ * Moving `.cleo/tasks.db` to another machine renders stored keys unreadable.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3.6
+ * @module crypto/credentials
+ */
+
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** AES-256-GCM constants. */
+const ALGORITHM = 'aes-256-gcm' as const;
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+/** Version byte prefix for ciphertext format (F-006: enables future algorithm migration). */
+const CIPHERTEXT_VERSION = 0x01;
+
+/**
+ * Get the path to the machine key file.
+ * Uses XDG data dir: `~/.local/share/cleo/machine-key`
+ *
+ * @throws If HOME/USERPROFILE are unset (F-002: never fall back to /tmp).
+ */
+function getMachineKeyPath(): string {
+  const home = process.env['HOME'] ?? process.env['USERPROFILE'];
+  if (!home) {
+    throw new Error(
+      'Cannot determine home directory. Set HOME or USERPROFILE environment variable. ' +
+        'Machine key cannot be stored securely without a persistent home directory.',
+    );
+  }
+  return join(home, '.local', 'share', 'cleo', 'machine-key');
+}
+
+/**
+ * Read or auto-generate the machine key (32 random bytes).
+ * Sets file permissions to 0600 (owner read/write only).
+ *
+ * @throws If the machine key exists but has wrong permissions (not 0600).
+ */
+async function getMachineKey(): Promise<Buffer> {
+  const keyPath = getMachineKeyPath();
+
+  try {
+    // Check existing key
+    const stats = await stat(keyPath);
+    const mode = stats.mode & 0o777;
+    if (mode !== 0o600) {
+      throw new Error(
+        `Machine key has unsafe permissions (${mode.toString(8)}). Expected 0600. ` +
+          `Fix with: chmod 600 ${keyPath}`,
+      );
+    }
+    const key = await readFile(keyPath);
+    // F-004: validate key length
+    if (key.length !== KEY_LENGTH) {
+      throw new Error(
+        `Machine key has invalid length (${key.length} bytes, expected ${KEY_LENGTH}). ` +
+          `Delete ${keyPath} and re-register agents to generate a new key.`,
+      );
+    }
+    return key;
+  } catch (err: unknown) {
+    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+      // Auto-generate on first use
+      const key = randomBytes(KEY_LENGTH);
+      await mkdir(dirname(keyPath), { recursive: true });
+      await writeFile(keyPath, key, { mode: 0o600 });
+      await chmod(keyPath, 0o600); // Ensure perms even on existing dirs
+      return key;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Derive a per-project encryption key from the machine key.
+ * Uses HMAC-SHA256(machine-key, project-path) to produce a 32-byte AES key.
+ */
+async function deriveProjectKey(projectPath: string): Promise<Buffer> {
+  const machineKey = await getMachineKey();
+  return createHmac('sha256', machineKey).update(projectPath).digest();
+}
+
+/**
+ * Encrypt a plaintext string using AES-256-GCM with a per-project key.
+ *
+ * Output format: base64(version + iv + ciphertext + authTag)
+ *   - version: 1 byte (0x01 = AES-256-GCM)
+ *   - iv: 12 bytes
+ *   - ciphertext: variable length
+ *   - authTag: 16 bytes
+ *
+ * @param plaintext - The string to encrypt (e.g. an API key).
+ * @param projectPath - Absolute path to the project directory (used for key derivation).
+ * @returns Base64-encoded ciphertext.
+ */
+export async function encrypt(plaintext: string, projectPath: string): Promise<string> {
+  const key = await deriveProjectKey(projectPath);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  // Pack: version + iv + ciphertext + authTag (F-006: version byte for future migration)
+  const version = Buffer.from([CIPHERTEXT_VERSION]);
+  const packed = Buffer.concat([version, iv, encrypted, authTag]);
+  return packed.toString('base64');
+}
+
+/**
+ * Decrypt a base64-encoded ciphertext using AES-256-GCM with a per-project key.
+ *
+ * @param ciphertext - Base64-encoded string from `encrypt()`.
+ * @param projectPath - Absolute path to the project directory (must match the one used for encryption).
+ * @returns The original plaintext string.
+ * @throws If decryption fails (wrong key, corrupted data, or machine key mismatch).
+ */
+export async function decrypt(ciphertext: string, projectPath: string): Promise<string> {
+  const key = await deriveProjectKey(projectPath);
+  const packed = Buffer.from(ciphertext, 'base64');
+
+  if (packed.length < 1 + IV_LENGTH + AUTH_TAG_LENGTH) {
+    throw new Error('Cannot decrypt credentials: ciphertext too short');
+  }
+
+  // F-006: check version byte
+  const version = packed[0];
+  if (version !== CIPHERTEXT_VERSION) {
+    throw new Error(
+      `Unknown ciphertext version (${version}). Expected ${CIPHERTEXT_VERSION}. ` +
+        'Re-register agents to re-encrypt with the current format.',
+    );
+  }
+
+  const iv = packed.subarray(1, 1 + IV_LENGTH);
+  const authTag = packed.subarray(packed.length - AUTH_TAG_LENGTH);
+  const encrypted = packed.subarray(1 + IV_LENGTH, packed.length - AUTH_TAG_LENGTH);
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(authTag);
+
+  try {
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    return decrypted.toString('utf8');
+  } catch {
+    throw new Error(
+      'Cannot decrypt credentials. Machine key mismatch or corrupted data. ' +
+        'If this database was moved from another machine, re-register agents: ' +
+        'cleo agent register --id <id> --api-key <key>',
+    );
+  }
+}

package/src/engine-result.ts

@@ -9,7 +9,7 @@
  * @epic T5701
  */
 
-import type { LAFSPage } from '@cleocode/lafs-protocol';
+import type { LAFSPage } from '@cleocode/lafs';
 
 /**
  * Canonical EngineResult type used by all engines and core engine-compat modules.

package/src/error-catalog.ts

@@ -10,7 +10,7 @@
  */
 
 import { ExitCode } from '@cleocode/contracts';
-import type { LAFSErrorCategory } from '@cleocode/lafs-protocol';
+import type { LAFSErrorCategory } from '@cleocode/lafs';
 
 /**
  * A single entry in the unified error catalog.

package/src/error-registry.ts

@@ -13,7 +13,7 @@
  */
 
 import { ExitCode } from '@cleocode/contracts';
-import type { LAFSErrorCategory } from '@cleocode/lafs-protocol';
+import type { LAFSErrorCategory } from '@cleocode/lafs';
 
 /**
  * Entry in the CLEO-to-LAFS error registry.

package/src/errors.ts

@@ -8,7 +8,7 @@
  */
 
 import { ExitCode, getExitCodeName, isRecoverableCode } from '@cleocode/contracts';
-import type { LAFSError, LAFSErrorCategory } from '@cleocode/lafs-protocol';
+import type { LAFSError, LAFSErrorCategory } from '@cleocode/lafs';
 import { getErrorDefinition } from './error-catalog.js';
 
 /**

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * E2E integration tests: hook automation fires across lifecycle events
+ *
+ * Verifies that brain automation hooks actually dispatch and call observeBrain
+ * with the correct payloads for all lifecycle event types. Tests use mock
+ * adapters and direct handler invocation to exercise the full handler logic
+ * without requiring a real SQLite database.
+ *
+ * @task T168
+ * @epic T134
+ */
+export {};
+//# sourceMappingURL=hook-automation-e2e.test.d.ts.map

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-automation-e2e.test.d.ts","sourceRoot":"","sources":["hook-automation-e2e.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}