@arka-labs/nemesis 1.2.0

package/lib/kairos/dispatcher-router.js

@@ -0,0 +1,173 @@
+/**
+ * Dispatcher Router — execute routing decisions post-classification.
+ * V1: terminal display only. V2 will add webhook HCM + event-bus.
+ */
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadTemplate, mergeTemplate } from '../core/templates.js';
+import { titledBox } from '../ui/box.js';
+import { style } from '../ui/colors.js';
+
+/**
+ * Display routing decisions in terminal.
+ * LEADER = green box, HUMAN = yellow box, NOISE = dim line.
+ * @param {Array} routing — array of { target, reason, priority, summary }
+ * @param {object} context — { agentName, odmId }
+ * @returns {{ displayed: string[], archived: string[], escalated: string[] }}
+ */
+export function routeToTerminal(routing, _context = {}) {
+  const displayed = [];
+  const archived = [];
+  const escalated = [];
+
+  for (const entry of routing) {
+    const line = formatSingleRouting(entry);
+
+    switch (entry.target) {
+      case 'LEADER':
+        console.log('');
+        console.log(titledBox('Routing LEADER', [line], { border: style.green }));
+        displayed.push(entry.summary || entry.reason);
+        break;
+      case 'HUMAN':
+        console.log('');
+        console.log(titledBox('Routing HUMAN', [line], { border: style.yellow }));
+        escalated.push(entry.summary || entry.reason);
+        break;
+      case 'NOISE':
+        console.log(`  ${style.dim(`NOISE  ○ [${entry.priority}] ${entry.summary || entry.reason}`)}`);
+        archived.push(entry.summary || entry.reason);
+        break;
+    }
+  }
+
+  // V2: webhook HCM (Signal 2)
+  // V2: event-bus push vers Leader
+  // V2: notifications Slack/email pour HUMAN
+
+  return { displayed, archived, escalated };
+}
+
+/**
+ * Create a dispatch Transaction in .nemesis/HCM/transactions/.
+ * @param {object} opts — { from, to, odmId, projectId, root }
+ * @returns {{ filepath: string, txnId: string }}
+ */
+export function createDispatchTransaction(opts = {}) {
+  const { from = 'PM', to, odmId = '', missionId = '', projectId = '', root = process.cwd() } = opts;
+
+  const txnId = `TXN-DISP-${Date.now()}`;
+  const txnDir = join(root, '.nemesis', 'HCM', 'transactions');
+
+  if (!existsSync(txnDir)) {
+    mkdirSync(txnDir, { recursive: true });
+  }
+
+  const refs = [];
+  if (odmId) refs.push(odmId);
+  if (missionId) refs.push(missionId);
+
+  const template = loadTemplate('transaction', root);
+  const txn = mergeTemplate(template, {
+    transaction_meta: {
+      txn_id: txnId,
+      project_id: projectId,
+      type: 'OdM_DISPATCH',
+      status: 'SENT',
+      created_at: new Date().toISOString(),
+      mission_id: missionId || undefined,
+    },
+    transaction_payload: {
+      from: { actor_type: 'human', actor_id: from },
+      to: { actor_type: 'agent', actor_id: to },
+      subject: `Dispatch OdM ${odmId}`,
+      refs,
+    },
+  });
+
+  const filepath = join(txnDir, `${txnId}.json`);
+  writeFileSync(filepath, JSON.stringify(txn, null, 2) + '\n', 'utf-8');
+
+  return { filepath, txnId };
+}
+
+/**
+ * Format routing decisions as display lines.
+ * @param {Array} routing
+ * @param {object} context
+ * @returns {string[]}
+ */
+export function formatRoutingDisplay(routing, _context = {}) {
+  return routing.map(entry => formatSingleRouting(entry));
+}
+
+function formatSingleRouting(entry) {
+  const icons = { LEADER: '★', HUMAN: '⚠', NOISE: '○' };
+  const colors = { LEADER: style.green, HUMAN: style.yellow, NOISE: style.dim };
+  const icon = icons[entry.target] || '?';
+  const colorFn = colors[entry.target] || (v => v);
+  return colorFn(`${entry.target}  ${icon} [${entry.priority}] ${entry.reason} — ${entry.summary}`);
+}
+
+/**
+ * Route classified dispatch results to files for inter-process consumption.
+ * LEADER → .nemesis/kairos/events/
+ * HUMAN → .nemesis/kairos/escalations/
+ * NOISE → .nemesis/kairos/noise/
+ *
+ * @param {Array} routing - array of { target, reason, priority, summary }
+ * @param {object} context - { agentName, odmId, projectId }
+ * @param {string} projectRoot
+ * @returns {{ events: string[], escalations: string[], noise: string[] }}
+ */
+export function routeToFile(routing, context = {}, projectRoot = process.cwd()) {
+  const kairosDir = join(projectRoot, '.nemesis', 'kairos');
+  const events = [];
+  const escalations = [];
+  const noise = [];
+
+  for (const entry of routing) {
+    const ts = Date.now();
+    const agentId = context.agentName || 'unknown';
+    const payload = {
+      timestamp: new Date().toISOString(),
+      agentName: agentId,
+      odmId: context.odmId || '',
+      projectId: context.projectId || '',
+      target: entry.target,
+      priority: entry.priority,
+      reason: entry.reason,
+      summary: entry.summary,
+    };
+
+    switch (entry.target) {
+      case 'LEADER': {
+        const dir = join(kairosDir, 'events');
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const filepath = join(dir, `${ts}-${agentId}.json`);
+        writeFileSync(filepath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+        events.push(filepath);
+        break;
+      }
+      case 'HUMAN': {
+        const dir = join(kairosDir, 'escalations');
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const filepath = join(dir, `${ts}.json`);
+        writeFileSync(filepath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+        escalations.push(filepath);
+        break;
+      }
+      case 'NOISE': {
+        const dir = join(kairosDir, 'noise');
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const filepath = join(dir, `${ts}.json`);
+        writeFileSync(filepath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+        noise.push(filepath);
+        break;
+      }
+    }
+  }
+
+  return { events, escalations, noise };
+}

package/lib/kairos/dispatcher.js

@@ -0,0 +1,139 @@
+/**
+ * Dispatcher — LLM classification of agent responses.
+ * Routes to LEADER, HUMAN, or NOISE.
+ */
+
+import { debug } from '../core/logger.js';
+
+export const ROUTING_TARGETS = { LEADER: 'LEADER', HUMAN: 'HUMAN', NOISE: 'NOISE' };
+
+const VALID_TARGETS = new Set(Object.values(ROUTING_TARGETS));
+const VALID_PRIORITIES = new Set(['HIGH', 'MEDIUM', 'LOW']);
+
+/**
+ * Build the system prompt for the Dispatcher LLM.
+ * @returns {string}
+ */
+export function buildDispatcherSystemPrompt() {
+  return `Tu es le Kairos Dispatcher. Classe la reponse d'un agent en 3 categories.
+
+## LEADER
+Contient un livrable, CR, demande de validation, rapport d'avancement,
+ou information que le Leader doit examiner.
+Indices : fichiers deposes, references OdM, "voici le livrable", "CR depose".
+
+## HUMAN
+Demande d'intervention humaine : decision hors perimetre, blocage non
+resolvable, clarification PM, alerte securite.
+Indices : "besoin d'arbitrage PM", "blocage", "question pour le PM".
+
+## NOISE
+Accuse de reception, log intermediaire, confirmation standard, contenu vide.
+Indices : reponse < 50 mots sans contenu technique, "OK", "compris".
+
+## Regles
+1. Doute LEADER/NOISE → LEADER
+2. Doute LEADER/HUMAN → HUMAN
+3. Un CR n'est JAMAIS NOISE
+4. Message > 200 mots technique = rarement NOISE
+
+## Format JSON strict
+{ "routing": [{ "target": "LEADER"|"HUMAN"|"NOISE", "reason": "...", "priority": "HIGH"|"MEDIUM"|"LOW", "summary": "..." }] }`;
+}
+
+/**
+ * Build the user prompt containing the agent response to classify.
+ * @param {string} agentResponse
+ * @param {object} context — { agentName, odmId, projectId }
+ * @returns {string}
+ */
+export function buildDispatcherUserPrompt(agentResponse, context = {}) {
+  const parts = ['# Reponse agent a classifier'];
+  if (context.agentName) parts.push(`Agent : ${context.agentName}`);
+  if (context.odmId) parts.push(`OdM : ${context.odmId}`);
+  if (context.projectId) parts.push(`Projet : ${context.projectId}`);
+  parts.push('', '## Reponse', '', agentResponse);
+  return parts.join('\n');
+}
+
+/**
+ * Classify an agent response via LLM.
+ * @param {string} agentResponse
+ * @param {object} context — { agentName, odmId, projectId }
+ * @param {function} callLlm — async (systemPrompt, userPrompt) => string
+ * @returns {Promise<{ routing: Array, raw: string }>}
+ */
+export async function classifyResponse(agentResponse, context, callLlm) {
+  const systemPrompt = buildDispatcherSystemPrompt();
+  const userPrompt = buildDispatcherUserPrompt(agentResponse, context);
+
+  let raw;
+  try {
+    raw = await callLlm(systemPrompt, userPrompt);
+  } catch (e) {
+    debug(`classifyResponse LLM: ${e.message}`);
+    return classifyFallback(agentResponse, context);
+  }
+
+  const parsed = parseJsonResponse(raw);
+  if (!parsed) return classifyFallback(agentResponse, context);
+
+  return { routing: parsed.routing, raw };
+}
+
+/**
+ * Graceful degradation: route everything to LEADER.
+ * @param {string} agentResponse
+ * @param {object} context
+ * @returns {{ routing: Array, raw: string }}
+ */
+export function classifyFallback(agentResponse, _context = {}) {
+  const maxLen = 200;
+  const summary = agentResponse.length > maxLen
+    ? agentResponse.slice(0, maxLen) + '...'
+    : agentResponse;
+
+  return {
+    routing: [{
+      target: 'LEADER',
+      reason: 'Classification automatique (fallback)',
+      priority: 'MEDIUM',
+      summary,
+    }],
+    raw: '',
+  };
+}
+
+/**
+ * Parse JSON from LLM response — direct or from markdown code block.
+ * @param {string} raw
+ * @returns {{ routing: Array }|null}
+ */
+function parseJsonResponse(raw) {
+  // Try direct parse
+  let obj = tryParse(raw);
+  if (obj && validateRouting(obj)) return obj;
+
+  // Try extracting from markdown code block
+  const match = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (match) {
+    obj = tryParse(match[1].trim());
+    if (obj && validateRouting(obj)) return obj;
+  }
+
+  return null;
+}
+
+function tryParse(str) {
+  try { return JSON.parse(str); } catch (e) { debug(`tryParse: ${e.message}`); return null; }
+}
+
+function validateRouting(obj) {
+  if (!obj || !Array.isArray(obj.routing) || obj.routing.length === 0) return false;
+  return obj.routing.every(entry =>
+    VALID_TARGETS.has(entry.target) &&
+    typeof entry.reason === 'string' &&
+    VALID_PRIORITIES.has(entry.priority) &&
+    typeof entry.summary === 'string'
+  );
+}

package/lib/kairos/event-bus.js

@@ -0,0 +1,287 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { debug } from '../core/logger.js';
+
+const EVENT_BUS_DIR = '.nemesis/kairos/event-bus';
+
+export const EVENT_TYPES = Object.freeze({
+  CR_DEPOSITED: 'cr_deposited',
+  TASK_ASSIGNED: 'task_assigned',
+  VALIDATION_REQUIRED: 'validation_required',
+  DISPATCH_RESULT: 'dispatch_result',
+  MESSAGE: 'message',
+});
+
+export const PRIORITIES = Object.freeze({
+  HIGH: 'HIGH',
+  MEDIUM: 'MEDIUM',
+  LOW: 'LOW',
+});
+
+const DEFAULT_TTL = 300; // seconds
+
+/**
+ * Resolve queue directory for an agent.
+ */
+function queueDir(projectRoot, agentId) {
+  return join(projectRoot, EVENT_BUS_DIR, agentId);
+}
+
+/**
+ * Generate a unique event ID.
+ */
+function generateEventId() {
+  const ts = Date.now();
+  const rand = randomBytes(3).toString('hex');
+  return `EVT-${ts}-${rand}`;
+}
+
+/**
+ * Push an event to an agent's inbox queue.
+ * @param {string} projectRoot
+ * @param {object} opts
+ * @param {string} opts.target_agent_id
+ * @param {string} opts.event_type
+ * @param {object} [opts.payload]
+ * @param {string} [opts.priority]
+ * @param {number} [opts.ttl] - TTL in seconds
+ * @param {string} [opts.source_agent_id]
+ * @returns {{ eventId: string, filepath: string }}
+ */
+export function pushEvent(projectRoot, opts) {
+  const {
+    target_agent_id,
+    event_type,
+    payload = {},
+    priority = PRIORITIES.MEDIUM,
+    ttl = DEFAULT_TTL,
+    source_agent_id = 'system',
+  } = opts;
+
+  if (!target_agent_id) throw new Error('target_agent_id requis');
+  if (!event_type) throw new Error('event_type requis');
+
+  const dir = queueDir(projectRoot, target_agent_id);
+  mkdirSync(dir, { recursive: true });
+
+  const eventId = generateEventId();
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + ttl * 1000);
+
+  const event = {
+    event_id: eventId,
+    event_type,
+    source_agent_id,
+    target_agent_id,
+    priority,
+    ttl,
+    created_at: now.toISOString(),
+    expires_at: expiresAt.toISOString(),
+    payload,
+  };
+
+  const filepath = join(dir, `${eventId}.json`);
+  writeFileSync(filepath, JSON.stringify(event, null, 2) + '\n', 'utf-8');
+
+  return { eventId, filepath };
+}
+
+/**
+ * Poll pending events for an agent (non-consuming read).
+ * @param {string} projectRoot
+ * @param {string} agentId
+ * @returns {Array<{ eventId: string, event: object, filepath: string }>}
+ */
+export function pollEvents(projectRoot, agentId) {
+  const dir = queueDir(projectRoot, agentId);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter(f => f.startsWith('EVT-') && f.endsWith('.json'));
+  const results = [];
+
+  for (const file of files) {
+    const filepath = join(dir, file);
+    try {
+      const event = JSON.parse(readFileSync(filepath, 'utf-8'));
+      results.push({
+        eventId: event.event_id || file.replace('.json', ''),
+        event,
+        filepath,
+      });
+    } catch (e) { debug(`pollEvents ${file}: ${e.message}`); }
+  }
+
+  // Sort by priority (HIGH first) then by creation time
+  const priorityOrder = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  results.sort((a, b) => {
+    const pa = priorityOrder[a.event.priority] ?? 1;
+    const pb = priorityOrder[b.event.priority] ?? 1;
+    if (pa !== pb) return pa - pb;
+    return (a.event.created_at || '').localeCompare(b.event.created_at || '');
+  });
+
+  return results;
+}
+
+/**
+ * Consume (delete) a single event by ID.
+ * @param {string} projectRoot
+ * @param {string} agentId
+ * @param {string} eventId
+ */
+export function consumeEvent(projectRoot, agentId, eventId) {
+  const dir = queueDir(projectRoot, agentId);
+  if (!existsSync(dir)) return;
+
+  const filepath = join(dir, `${eventId}.json`);
+  try { unlinkSync(filepath); } catch (e) { debug(`consumeEvent: ${e.message}`); }
+}
+
+/**
+ * Atomically consume all events for an agent — read + delete.
+ * @param {string} projectRoot
+ * @param {string} agentId
+ * @returns {Array<{ eventId: string, event: object }>}
+ */
+export function consumeAllEvents(projectRoot, agentId) {
+  const dir = queueDir(projectRoot, agentId);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter(f => f.startsWith('EVT-') && f.endsWith('.json'));
+  const results = [];
+
+  for (const file of files) {
+    const filepath = join(dir, file);
+    try {
+      const event = JSON.parse(readFileSync(filepath, 'utf-8'));
+      results.push({
+        eventId: event.event_id || file.replace('.json', ''),
+        event,
+      });
+      unlinkSync(filepath);
+    } catch (e) { debug(`consumeAllEvents ${file}: ${e.message}`); }
+  }
+
+  // Sort by priority then time
+  const priorityOrder = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  results.sort((a, b) => {
+    const pa = priorityOrder[a.event.priority] ?? 1;
+    const pb = priorityOrder[b.event.priority] ?? 1;
+    if (pa !== pb) return pa - pb;
+    return (a.event.created_at || '').localeCompare(b.event.created_at || '');
+  });
+
+  return results;
+}
+
+/**
+ * List all queues with event counts.
+ * @param {string} projectRoot
+ * @returns {Array<{ agentId: string, count: number, oldest: string|null }>}
+ */
+export function listQueues(projectRoot) {
+  const busDir = join(projectRoot, EVENT_BUS_DIR);
+  if (!existsSync(busDir)) return [];
+
+  const dirs = readdirSync(busDir, { withFileTypes: true })
+    .filter(d => d.isDirectory());
+
+  return dirs.map(d => {
+    const agentDir = join(busDir, d.name);
+    const files = readdirSync(agentDir).filter(f => f.startsWith('EVT-') && f.endsWith('.json'));
+    let oldest = null;
+    for (const file of files) {
+      try {
+        const evt = JSON.parse(readFileSync(join(agentDir, file), 'utf-8'));
+        if (!oldest || evt.created_at < oldest) oldest = evt.created_at;
+      } catch (e) { debug(`listQueues ${file}: ${e.message}`); }
+    }
+    return { agentId: d.name, count: files.length, oldest };
+  });
+}
+
+/**
+ * Clear all events in an agent's queue.
+ * @param {string} projectRoot
+ * @param {string} agentId
+ * @returns {number} Number of events cleared
+ */
+export function clearQueue(projectRoot, agentId) {
+  const dir = queueDir(projectRoot, agentId);
+  if (!existsSync(dir)) return 0;
+
+  const files = readdirSync(dir).filter(f => f.startsWith('EVT-') && f.endsWith('.json'));
+  let count = 0;
+  for (const file of files) {
+    try { unlinkSync(join(dir, file)); count++; } catch (e) { debug(`clearQueue: ${e.message}`); }
+  }
+  return count;
+}
+
+/**
+ * Format events as markdown for stdout injection in hooks.
+ * @param {Array<{ eventId: string, event: object }>} events
+ * @returns {string}
+ */
+export function formatEventsForInjection(events) {
+  if (!events || events.length === 0) return '';
+
+  const lines = [
+    '',
+    `# KAIROS EVENT BUS — ${events.length} evenement(s) en attente`,
+    '',
+  ];
+
+  for (const { event } of events) {
+    lines.push(`## [${event.priority || 'MEDIUM'}] ${event.event_type}`);
+    lines.push(`De: ${event.source_agent_id || 'inconnu'} — ${event.created_at || ''}`);
+
+    if (event.payload) {
+      if (event.payload.summary) lines.push(`Resume: ${event.payload.summary}`);
+      if (event.payload.odmId) lines.push(`OdM: ${event.payload.odmId}`);
+      if (event.payload.cr_id) lines.push(`CR: ${event.payload.cr_id}`);
+      if (event.payload.message) lines.push(`Message: ${event.payload.message}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('Traite ces evenements selon leur priorite.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Purge expired events across all queues.
+ * @param {string} projectRoot
+ * @returns {number} Number of events purged
+ */
+export function purgeExpired(projectRoot) {
+  const busDir = join(projectRoot, EVENT_BUS_DIR);
+  if (!existsSync(busDir)) return 0;
+
+  const now = new Date();
+  let purged = 0;
+
+  const dirs = readdirSync(busDir, { withFileTypes: true })
+    .filter(d => d.isDirectory());
+
+  for (const d of dirs) {
+    const agentDir = join(busDir, d.name);
+    const files = readdirSync(agentDir).filter(f => f.startsWith('EVT-') && f.endsWith('.json'));
+    for (const file of files) {
+      const filepath = join(agentDir, file);
+      try {
+        const evt = JSON.parse(readFileSync(filepath, 'utf-8'));
+        if (evt.expires_at && new Date(evt.expires_at) < now) {
+          unlinkSync(filepath);
+          purged++;
+        }
+      } catch (e) { debug(`purgeExpired ${file}: ${e.message}`); }
+    }
+  }
+
+  return purged;
+}