@cleocode/core 2026.4.35 → 2026.4.37

package/src/hooks/handlers/__tests__/conduit-hooks.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Tests for conduit-hooks.ts
+ *
+ * Verifies that SubagentStart, SubagentStop, and SessionEnd handlers
+ * write the correct structured messages to conduit via LocalTransport.
+ *
+ * Mocks the LocalTransport module so no real conduit.db is required.
+ *
+ * @task T268
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Hoisted mock state — established before any module is imported
+// ---------------------------------------------------------------------------
+
+const transportMocks = vi.hoisted(() => {
+  const pushFn = vi.fn().mockResolvedValue({ messageId: 'msg-1' });
+  const disconnectFn = vi.fn().mockResolvedValue(undefined);
+  const connectFn = vi.fn().mockResolvedValue(undefined);
+  const isAvailableFn = vi.fn().mockReturnValue(true);
+  const transportInstance = { connect: connectFn, push: pushFn, disconnect: disconnectFn };
+
+  return { pushFn, disconnectFn, connectFn, isAvailableFn, transportInstance };
+});
+
+vi.mock('../../../conduit/local-transport.js', () => {
+  class MockLocalTransport {
+    connect = transportMocks.connectFn;
+    push = transportMocks.pushFn;
+    disconnect = transportMocks.disconnectFn;
+    static isAvailable = transportMocks.isAvailableFn;
+  }
+  return { LocalTransport: MockLocalTransport };
+});
+
+// ---------------------------------------------------------------------------
+// Subject under test — imported AFTER mocks are registered
+// ---------------------------------------------------------------------------
+
+import {
+  handleConduitSessionEnd,
+  handleConduitSubagentStart,
+  handleConduitSubagentStop,
+  tryGetLocalTransport,
+} from '../conduit-hooks.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Parse JSON content from the first push call argument at position `callIndex`. */
+function parsePush(callIndex = 0): Record<string, unknown> {
+  const rawContent = transportMocks.pushFn.mock.calls[callIndex][1] as string;
+  return JSON.parse(rawContent) as Record<string, unknown>;
+}
+
+/** Reset all transport mocks to fresh state. */
+function resetMocks() {
+  transportMocks.pushFn.mockReset().mockResolvedValue({ messageId: 'msg-1' });
+  transportMocks.disconnectFn.mockReset().mockResolvedValue(undefined);
+  transportMocks.connectFn.mockReset().mockResolvedValue(undefined);
+  transportMocks.isAvailableFn.mockReturnValue(true);
+}
+
+// ---------------------------------------------------------------------------
+// tryGetLocalTransport
+// ---------------------------------------------------------------------------
+
+describe('tryGetLocalTransport', () => {
+  beforeEach(resetMocks);
+
+  it('returns null when conduit.db is unavailable', async () => {
+    transportMocks.isAvailableFn.mockReturnValue(false);
+
+    const result = await tryGetLocalTransport('/tmp/project');
+
+    expect(result).toBeNull();
+    expect(transportMocks.connectFn).not.toHaveBeenCalled();
+  });
+
+  it('returns a connected transport instance when available', async () => {
+    const result = await tryGetLocalTransport('/tmp/project');
+
+    expect(result).not.toBeNull();
+    expect(transportMocks.connectFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns null when connect throws', async () => {
+    transportMocks.connectFn.mockRejectedValue(new Error('connection refused'));
+
+    const result = await tryGetLocalTransport('/tmp/project');
+
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleConduitSubagentStart
+// ---------------------------------------------------------------------------
+
+describe('handleConduitSubagentStart', () => {
+  beforeEach(resetMocks);
+
+  it('pushes a subagent.spawn message when conduit.db is available', async () => {
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-42',
+      role: 'researcher',
+      taskId: 'T999',
+    });
+
+    expect(transportMocks.pushFn).toHaveBeenCalledTimes(1);
+    const msg = parsePush();
+    expect(msg.type).toBe('subagent.spawn');
+    expect(msg.from).toBe('cleo-orchestrator');
+    expect(msg.to).toBe('worker-42');
+    expect(msg.taskId).toBe('T999');
+    expect(typeof msg.timestamp).toBe('string');
+    expect((msg.content as string).includes('worker-42')).toBe(true);
+  });
+
+  it('includes role in content when provided', async () => {
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-99',
+      role: 'implementer',
+    });
+
+    const msg = parsePush();
+    expect((msg.content as string).includes('implementer')).toBe(true);
+  });
+
+  it('sets taskId to null when not provided', async () => {
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-no-task',
+    });
+
+    const msg = parsePush();
+    expect(msg.taskId).toBeNull();
+  });
+
+  it('does nothing when conduit.db is unavailable', async () => {
+    transportMocks.isAvailableFn.mockReturnValue(false);
+
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-offline',
+    });
+
+    expect(transportMocks.pushFn).not.toHaveBeenCalled();
+  });
+
+  it('swallows push errors so orchestration is never blocked', async () => {
+    transportMocks.pushFn.mockRejectedValue(new Error('SQLITE_ERROR: disk full'));
+
+    await expect(
+      handleConduitSubagentStart('/tmp/project', {
+        timestamp: '2026-04-13T10:00:00.000Z',
+        agentId: 'worker-crash',
+        taskId: 'T888',
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('always disconnects the transport after a successful push', async () => {
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-cleanup',
+    });
+
+    expect(transportMocks.disconnectFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('still disconnects when push throws', async () => {
+    transportMocks.pushFn.mockRejectedValue(new Error('push failed'));
+
+    await handleConduitSubagentStart('/tmp/project', {
+      timestamp: '2026-04-13T10:00:00.000Z',
+      agentId: 'worker-cleanup-on-error',
+    });
+
+    expect(transportMocks.disconnectFn).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleConduitSubagentStop
+// ---------------------------------------------------------------------------
+
+describe('handleConduitSubagentStop', () => {
+  beforeEach(resetMocks);
+
+  it('pushes a subagent.complete message when conduit.db is available', async () => {
+    await handleConduitSubagentStop('/tmp/project', {
+      timestamp: '2026-04-13T11:00:00.000Z',
+      agentId: 'worker-42',
+      status: 'complete',
+      taskId: 'T999',
+    });
+
+    expect(transportMocks.pushFn).toHaveBeenCalledTimes(1);
+    const msg = parsePush();
+    expect(msg.type).toBe('subagent.complete');
+    expect(msg.from).toBe('worker-42');
+    expect(msg.to).toBe('cleo-system');
+    expect(msg.taskId).toBe('T999');
+  });
+
+  it('includes status in content', async () => {
+    await handleConduitSubagentStop('/tmp/project', {
+      timestamp: '2026-04-13T11:00:00.000Z',
+      agentId: 'worker-partial',
+      status: 'partial',
+    });
+
+    const msg = parsePush();
+    expect((msg.content as string).includes('partial')).toBe(true);
+  });
+
+  it('uses "unknown" when status is absent', async () => {
+    await handleConduitSubagentStop('/tmp/project', {
+      timestamp: '2026-04-13T11:00:00.000Z',
+      agentId: 'worker-no-status',
+    });
+
+    const msg = parsePush();
+    expect((msg.content as string).includes('unknown')).toBe(true);
+  });
+
+  it('does nothing when conduit.db is unavailable', async () => {
+    transportMocks.isAvailableFn.mockReturnValue(false);
+
+    await handleConduitSubagentStop('/tmp/project', {
+      timestamp: '2026-04-13T11:00:00.000Z',
+      agentId: 'worker-offline',
+      status: 'complete',
+    });
+
+    expect(transportMocks.pushFn).not.toHaveBeenCalled();
+  });
+
+  it('swallows push errors so orchestration is never blocked', async () => {
+    transportMocks.pushFn.mockRejectedValue(new Error('conduit.db locked'));
+
+    await expect(
+      handleConduitSubagentStop('/tmp/project', {
+        timestamp: '2026-04-13T11:00:00.000Z',
+        agentId: 'worker-crash',
+        status: 'failed',
+      }),
+    ).resolves.toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleConduitSessionEnd
+// ---------------------------------------------------------------------------
+
+describe('handleConduitSessionEnd', () => {
+  beforeEach(resetMocks);
+
+  it('pushes a session.handoff message when conduit.db is available', async () => {
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-test-1',
+      duration: 3600,
+      tasksCompleted: ['T100', 'T101'],
+    });
+
+    expect(transportMocks.pushFn).toHaveBeenCalledTimes(1);
+    const msg = parsePush();
+    expect(msg.type).toBe('session.handoff');
+    expect(msg.from).toBe('cleo-orchestrator');
+    expect(msg.to).toBe('cleo-system');
+    expect((msg.content as string).includes('ses-test-1')).toBe(true);
+  });
+
+  it('includes nextTask in content and taskId when metadata.nextTask is set', async () => {
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-handoff',
+      duration: 1800,
+      tasksCompleted: ['T200'],
+      metadata: { nextTask: 'T201' },
+    });
+
+    const msg = parsePush();
+    expect(msg.taskId).toBe('T201');
+    expect((msg.content as string).includes('T201')).toBe(true);
+  });
+
+  it('sets taskId to null when no nextTask metadata', async () => {
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-no-next',
+      duration: 900,
+      tasksCompleted: [],
+    });
+
+    const msg = parsePush();
+    expect(msg.taskId).toBeNull();
+  });
+
+  it('ignores non-string nextTask metadata', async () => {
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-bad-meta',
+      duration: 100,
+      tasksCompleted: [],
+      metadata: { nextTask: 42 },
+    });
+
+    const msg = parsePush();
+    expect(msg.taskId).toBeNull();
+  });
+
+  it('does nothing when conduit.db is unavailable', async () => {
+    transportMocks.isAvailableFn.mockReturnValue(false);
+
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-offline',
+      duration: 0,
+      tasksCompleted: [],
+    });
+
+    expect(transportMocks.pushFn).not.toHaveBeenCalled();
+  });
+
+  it('swallows push errors so session end is never blocked', async () => {
+    transportMocks.pushFn.mockRejectedValue(new Error('conduit write timeout'));
+
+    await expect(
+      handleConduitSessionEnd('/tmp/project', {
+        timestamp: '2026-04-13T12:00:00.000Z',
+        sessionId: 'ses-crash',
+        duration: 500,
+        tasksCompleted: ['T300'],
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('always disconnects the transport after a successful push', async () => {
+    await handleConduitSessionEnd('/tmp/project', {
+      timestamp: '2026-04-13T12:00:00.000Z',
+      sessionId: 'ses-cleanup',
+      duration: 600,
+      tasksCompleted: [],
+    });
+
+    expect(transportMocks.disconnectFn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/handlers/conduit-hooks.ts

@@ -0,0 +1,258 @@
+/**
+ * Conduit Messaging Hook Handlers
+ *
+ * Captures orchestration lifecycle events (SubagentStart, SubagentStop,
+ * SessionEnd) and writes structured messages to conduit.db via LocalTransport.
+ * This is the DECOUPLED approach: hooks observe orchestration events without
+ * any changes to the orchestrate engine itself.
+ *
+ * Message format (JSON string stored as conduit message content):
+ *   { type, from, to, content, taskId, timestamp }
+ *
+ * All handlers are best-effort — failures are silently swallowed so that
+ * conduit writes NEVER crash or block agent orchestration.
+ *
+ * Auto-registers on module load.
+ *
+ * @task T268
+ */
+
+import { LocalTransport } from '../../conduit/local-transport.js';
+import { getLogger } from '../../logger.js';
+import { hooks } from '../registry.js';
+import type { SessionEndPayload, SubagentStartPayload, SubagentStopPayload } from '../types.js';
+
+/** Well-known system agent ID used as the "from" sender for lifecycle messages. */
+const SYSTEM_AGENT_ID = 'cleo-orchestrator';
+
+/** Well-known broadcast recipient for lifecycle events. */
+const BROADCAST_RECIPIENT = 'cleo-system';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the content string for a SubagentStart conduit message.
+ *
+ * @param payload - SubagentStart event payload.
+ * @returns JSON-serialised message content string.
+ */
+function buildSpawnMessageContent(payload: SubagentStartPayload): string {
+  return JSON.stringify({
+    type: 'subagent.spawn',
+    from: SYSTEM_AGENT_ID,
+    to: payload.agentId,
+    content: `Subagent spawned: ${payload.agentId}${payload.role ? ` (${payload.role})` : ''}`,
+    taskId: payload.taskId ?? null,
+    timestamp: payload.timestamp,
+  });
+}
+
+/**
+ * Build the content string for a SubagentStop conduit message.
+ *
+ * @param payload - SubagentStop event payload.
+ * @returns JSON-serialised message content string.
+ */
+function buildCompletionMessageContent(payload: SubagentStopPayload): string {
+  return JSON.stringify({
+    type: 'subagent.complete',
+    from: payload.agentId,
+    to: BROADCAST_RECIPIENT,
+    content: `Subagent completed: ${payload.agentId} status=${payload.status ?? 'unknown'}${payload.taskId ? ` task=${payload.taskId}` : ''}`,
+    taskId: payload.taskId ?? null,
+    timestamp: payload.timestamp,
+  });
+}
+
+/**
+ * Build the content string for a SessionEnd handoff conduit message.
+ *
+ * @param payload  - SessionEnd event payload.
+ * @param nextTask - Optional next suggested task ID from the session.
+ * @returns JSON-serialised message content string.
+ */
+function buildHandoffMessageContent(payload: SessionEndPayload, nextTask?: string): string {
+  return JSON.stringify({
+    type: 'session.handoff',
+    from: SYSTEM_AGENT_ID,
+    to: BROADCAST_RECIPIENT,
+    content: `Session ended: ${payload.sessionId}${nextTask ? ` \u2014 next task: ${nextTask}` : ''}`,
+    taskId: nextTask ?? null,
+    timestamp: payload.timestamp,
+  });
+}
+
+/**
+ * Attempt to create and connect a LocalTransport for conduit.db.
+ *
+ * Returns null when conduit.db is unavailable (not yet initialised), or when
+ * the connect call fails, so callers can bail out gracefully without throwing.
+ *
+ * The `transportFactory` parameter exists for testing: callers can inject a
+ * mock constructor so no real conduit.db is required in unit tests.
+ *
+ * @param projectRoot      - Absolute path to the project root directory.
+ * @param transportFactory - Optional factory used to construct the transport.
+ *                           Defaults to the `LocalTransport` class.
+ */
+export async function tryGetLocalTransport(
+  projectRoot: string,
+  transportFactory: typeof LocalTransport = LocalTransport,
+): Promise<InstanceType<typeof LocalTransport> | null> {
+  try {
+    if (!transportFactory.isAvailable(projectRoot)) return null;
+
+    const transport = new transportFactory();
+    await transport.connect({
+      agentId: SYSTEM_AGENT_ID,
+      apiKey: '',
+      apiBaseUrl: 'local',
+    });
+    return transport;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle SubagentStart — send a spawn message to conduit.db.
+ *
+ * Writes a `subagent.spawn` message from `cleo-orchestrator` to the
+ * spawned agent ID so orchestrators and watchers can observe the event.
+ *
+ * Best-effort: failures are swallowed and logged at debug level.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStart event payload.
+ */
+export async function handleConduitSubagentStart(
+  projectRoot: string,
+  payload: SubagentStartPayload,
+): Promise<void> {
+  const transport = await tryGetLocalTransport(projectRoot);
+  if (!transport) return;
+
+  try {
+    const content = buildSpawnMessageContent(payload);
+    await transport.push(payload.agentId, content);
+  } catch (err) {
+    getLogger('conduit-hooks').debug(
+      { err, agentId: payload.agentId },
+      'conduit spawn write failed',
+    );
+  } finally {
+    try {
+      await transport.disconnect();
+    } catch {
+      // Disconnect errors are ignored
+    }
+  }
+}
+
+/**
+ * Handle SubagentStop — send a completion message to conduit.db.
+ *
+ * Writes a `subagent.complete` message from the stopped agent to
+ * `cleo-system` so orchestrators can audit completion outcomes.
+ *
+ * Best-effort: failures are swallowed and logged at debug level.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SubagentStop event payload.
+ */
+export async function handleConduitSubagentStop(
+  projectRoot: string,
+  payload: SubagentStopPayload,
+): Promise<void> {
+  const transport = await tryGetLocalTransport(projectRoot);
+  if (!transport) return;
+
+  try {
+    const content = buildCompletionMessageContent(payload);
+    await transport.push(BROADCAST_RECIPIENT, content);
+  } catch (err) {
+    getLogger('conduit-hooks').debug(
+      { err, agentId: payload.agentId },
+      'conduit complete write failed',
+    );
+  } finally {
+    try {
+      await transport.disconnect();
+    } catch {
+      // Disconnect errors are ignored
+    }
+  }
+}
+
+/**
+ * Handle SessionEnd — send a handoff message if a next task is suggested.
+ *
+ * Writes a `session.handoff` message to `cleo-system` when the session
+ * metadata includes a `nextTask` suggestion (stored in `metadata.nextTask`).
+ * The message lets waiting agents pick up where the session left off.
+ *
+ * Best-effort: failures are swallowed and logged at debug level.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param payload     - SessionEnd event payload.
+ */
+export async function handleConduitSessionEnd(
+  projectRoot: string,
+  payload: SessionEndPayload,
+): Promise<void> {
+  const transport = await tryGetLocalTransport(projectRoot);
+  if (!transport) return;
+
+  try {
+    // Extract optional next-task hint from metadata
+    const nextTask =
+      typeof payload.metadata?.nextTask === 'string' ? payload.metadata.nextTask : undefined;
+
+    const content = buildHandoffMessageContent(payload, nextTask);
+    await transport.push(BROADCAST_RECIPIENT, content);
+  } catch (err) {
+    getLogger('conduit-hooks').debug(
+      { err, sessionId: payload.sessionId },
+      'conduit handoff write failed',
+    );
+  } finally {
+    try {
+      await transport.disconnect();
+    } catch {
+      // Disconnect errors are ignored
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+hooks.register({
+  id: 'conduit-subagent-start',
+  event: 'SubagentStart',
+  handler: handleConduitSubagentStart,
+  // Priority 50: runs after brain capture (100) but before low-priority bookkeeping
+  priority: 50,
+});
+
+hooks.register({
+  id: 'conduit-subagent-stop',
+  event: 'SubagentStop',
+  handler: handleConduitSubagentStop,
+  priority: 50,
+});
+
+hooks.register({
+  id: 'conduit-session-end',
+  event: 'SessionEnd',
+  handler: handleConduitSessionEnd,
+  // Priority 8: runs after brain (100), backup (10), but before consolidation (5)
+  priority: 8,
+});

package/src/hooks/handlers/index.ts

@@ -20,8 +20,15 @@ import './context-hooks.js';
 import './watchdog-hooks.js';
 // T549 Wave 5-D/E: Intelligence hooks (best-effort risk detection on task start)
 import './intelligence-hooks.js';
+// Conduit messaging hooks — write orchestration events to conduit.db
+import './conduit-hooks.js';
 
 export { handleSubagentStart, handleSubagentStop } from './agent-hooks.js';
+export {
+  handleConduitSessionEnd,
+  handleConduitSubagentStart,
+  handleConduitSubagentStop,
+} from './conduit-hooks.js';
 export { handlePostCompact, handlePreCompact } from './context-hooks.js';
 export { handleError } from './error-hooks.js';
 export { handleFileChange } from './file-hooks.js';

package/src/hooks/handlers/session-hooks.ts

@@ -15,6 +15,8 @@
  *       was pure noise.
  * T549 Wave 3-E: Fire-and-forget sleep-time consolidation on session end.
  *       Runs after backup (priority 5) so brain.db snapshot is captured first.
+ * T554: Fire-and-forget LLM reflector on session end. Runs at priority 4
+ *       (after consolidation at priority 5) to synthesize final session knowledge.
  */
 
 import { hooks } from '../registry.js';
@@ -141,6 +143,31 @@ export async function handleSessionEndConsolidation(
   });
 }
 
+/**
+ * Handle SessionEnd — fire-and-forget LLM reflector synthesis.
+ *
+ * T554: Runs the Reflector after the consolidation pass (priority 5) to
+ * synthesize session observations into durable patterns and learnings.
+ *
+ * Uses setImmediate to yield control before the LLM call. Errors are caught
+ * and logged — they MUST NOT block session end or throw to callers.
+ *
+ * Priority 4 ensures this runs after consolidation (priority 5).
+ */
+export async function handleSessionEndReflector(
+  projectRoot: string,
+  payload: SessionEndPayload,
+): Promise<void> {
+  setImmediate(async () => {
+    try {
+      const { runReflector } = await import('../../memory/observer-reflector.js');
+      await runReflector(projectRoot, payload.sessionId);
+    } catch (err) {
+      console.warn('[reflector] Session-end reflector failed:', err);
+    }
+  });
+}
+
 // Register handlers on module load
 hooks.register({
   id: 'brain-session-start',
@@ -174,3 +201,13 @@ hooks.register({
   handler: handleSessionEndConsolidation,
   priority: 5,
 });
+
+// Priority 4 runs AFTER consolidation (priority 5) — reflector synthesizes
+// the final session knowledge using observations that consolidation may have
+// updated (tier promotions, dedup).
+hooks.register({
+  id: 'reflector-session-end',
+  event: 'SessionEnd',
+  handler: handleSessionEndReflector,
+  priority: 4,
+});