@cleocode/core 2026.3.74 → 2026.3.76

package/src/conduit/conduit-client.ts

@@ -0,0 +1,114 @@
+/**
+ * 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';
+
+  constructor(transport: Transport, credential: AgentCredential) {
+    this.transport = transport;
+    this.credential = credential;
+  }
+
+  get agentId(): string {
+    return this.credential.agentId;
+  }
+
+  getState(): ConduitState {
+    return this.state;
+  }
+
+  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;
+    }
+  }
+
+  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(),
+    };
+  }
+
+  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);
+  }
+
+  async heartbeat(): Promise<void> {
+    // Send empty heartbeat via transport
+    await this.transport.push(this.credential.agentId, '', {});
+  }
+
+  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;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    await this.transport.disconnect();
+    this.state = 'disconnected';
+  }
+}

package/src/conduit/factory.ts

@@ -0,0 +1,45 @@
+/**
+ * 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';
+
+/** 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
+  }
+  if (credential.transportConfig.sseEndpoint) {
+    // SseTransport stub — fall through to HTTP for now
+  }
+  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,140 @@
+/**
+ * HttpTransport — HTTP polling transport to cloud SignalDock API.
+ *
+ * Implements the Transport interface using HTTP requests to the SignalDock
+ * (api.signaldock.io) REST API. This is the default transport for
+ * cloud-connected agents.
+ *
+ * @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;
+  apiBaseUrl: string;
+  connected: boolean;
+}
+
+/** HTTP polling transport to cloud SignalDock API. */
+export class HttpTransport implements Transport {
+  readonly name = 'http';
+  private state: HttpTransportState | null = null;
+
+  async connect(config: TransportConnectConfig): Promise<void> {
+    this.state = {
+      agentId: config.agentId,
+      apiKey: config.apiKey,
+      apiBaseUrl: config.apiBaseUrl,
+      connected: true,
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    this.state = null;
+  }
+
+  async push(
+    to: string,
+    content: string,
+    options?: { conversationId?: string; replyTo?: string },
+  ): Promise<{ messageId: string }> {
+    this.ensureConnected();
+
+    const body: Record<string, string> = { content };
+
+    let url: string;
+    if (options?.conversationId) {
+      url = `${this.state!.apiBaseUrl}/conversations/${options.conversationId}/messages`;
+      if (options.replyTo) {
+        body['replyTo'] = options.replyTo;
+      }
+    } else {
+      url = `${this.state!.apiBaseUrl}/messages`;
+      body['toAgentId'] = to;
+    }
+
+    const response = await fetch(url, {
+      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 };
+  }
+
+  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, {
+      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(),
+    }));
+  }
+
+  async ack(messageIds: string[]): Promise<void> {
+    this.ensureConnected();
+
+    await fetch(`${this.state!.apiBaseUrl}/messages/ack`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ messageIds }),
+    });
+  }
+
+  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,12 @@
+/**
+ * Conduit — High-level agent messaging for the CLEO ecosystem.
+ *
+ * Exports the ConduitClient (high-level messaging), HttpTransport
+ * (HTTP polling to cloud), and createConduit factory.
+ *
+ * @module conduit
+ */
+
+export { ConduitClient } from './conduit-client.js';
+export { createConduit } from './factory.js';
+export { HttpTransport } from './http-transport.js';

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"}