@arka-labs/nemesis 1.2.0

package/lib/core/inbox.js

@@ -0,0 +1,275 @@
+/**
+ * Inbox — manage human documents pipeline.
+ * Structure: .nemesis/inbox/{pending,processing,done}/
+ * Each document has a metadata JSON + the original file content.
+ *
+ * Lifecycle: pending → processing (dispatch launched) → done (MC created)
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, renameSync, unlinkSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+
+const INBOX_DIR = '.nemesis/inbox';
+const SUBDIRS = ['pending', 'processing', 'done'];
+
+let _idCounter = 0;
+function nextDocId() {
+  const ts = Date.now();
+  return `DOC-${ts}-${String(++_idCounter).padStart(3, '0')}`;
+}
+
+/**
+ * Ensure inbox directories exist.
+ * @param {string} root - project root
+ */
+export function ensureInboxDirs(root) {
+  for (const sub of SUBDIRS) {
+    const dir = join(root, INBOX_DIR, sub);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Add a document to the inbox (copies to pending/).
+ *
+ * @param {string} root - project root
+ * @param {string} filePath - absolute path to the document file
+ * @param {object} [opts]
+ * @param {string} [opts.title] - human title
+ * @param {string} [opts.source] - source (e.g. "email", "slack", "manual")
+ * @returns {{ id: string, metadataPath: string, contentPath: string }}
+ */
+export function addDocument(root, filePath, opts = {}) {
+  ensureInboxDirs(root);
+
+  if (!existsSync(filePath)) {
+    throw new Error(`Fichier introuvable : ${filePath}`);
+  }
+
+  const ext = extname(filePath);
+  const name = basename(filePath, ext);
+  const id = nextDocId();
+  const contentFilename = `${id}${ext}`;
+  const metaFilename = `${id}.meta.json`;
+
+  const pendingDir = join(root, INBOX_DIR, 'pending');
+  const contentPath = join(pendingDir, contentFilename);
+  const metadataPath = join(pendingDir, metaFilename);
+
+  // Copy file content
+  copyFileSync(filePath, contentPath);
+
+  // Write metadata
+  const metadata = {
+    id,
+    title: opts.title || name,
+    source: opts.source || 'manual',
+    original_path: filePath,
+    original_filename: basename(filePath),
+    status: 'pending',
+    created_at: new Date().toISOString(),
+    content_file: contentFilename,
+  };
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+
+  return { id, metadataPath, contentPath };
+}
+
+/**
+ * Add a document from inline text (no file copy).
+ *
+ * @param {string} root - project root
+ * @param {string} text - document text content
+ * @param {object} [opts]
+ * @param {string} [opts.title] - human title
+ * @param {string} [opts.source] - source
+ * @returns {{ id: string, metadataPath: string, contentPath: string }}
+ */
+export function addDocumentFromText(root, text, opts = {}) {
+  ensureInboxDirs(root);
+
+  const id = nextDocId();
+  const contentFilename = `${id}.md`;
+  const metaFilename = `${id}.meta.json`;
+
+  const pendingDir = join(root, INBOX_DIR, 'pending');
+  const contentPath = join(pendingDir, contentFilename);
+  const metadataPath = join(pendingDir, metaFilename);
+
+  writeFileSync(contentPath, text, 'utf-8');
+
+  const metadata = {
+    id,
+    title: opts.title || `Document ${id}`,
+    source: opts.source || 'inline',
+    original_path: null,
+    original_filename: null,
+    status: 'pending',
+    created_at: new Date().toISOString(),
+    content_file: contentFilename,
+  };
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+
+  return { id, metadataPath, contentPath };
+}
+
+/**
+ * List documents in a given status directory.
+ *
+ * @param {string} root - project root
+ * @param {'pending'|'processing'|'done'} status
+ * @returns {Array<{ id: string, title: string, source: string, status: string, created_at: string, content_file: string }>}
+ */
+export function listDocuments(root, status = 'pending') {
+  const dir = join(root, INBOX_DIR, status);
+  if (!existsSync(dir)) return [];
+
+  const metaFiles = readdirSync(dir).filter(f => f.endsWith('.meta.json'));
+  const docs = [];
+
+  for (const file of metaFiles) {
+    try {
+      const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+      docs.push(data);
+    } catch (_e) { /* fallback: skip corrupted meta */ }
+  }
+
+  // Sort by created_at desc
+  docs.sort((a, b) => (b.created_at || '').localeCompare(a.created_at || ''));
+  return docs;
+}
+
+/**
+ * Read a document's content.
+ *
+ * @param {string} root - project root
+ * @param {string} docId - document ID (e.g. "DOC-1710496800000")
+ * @param {'pending'|'processing'|'done'} [status]
+ * @returns {{ metadata: object, content: string } | null}
+ */
+export function readDocument(root, docId, status) {
+  const statuses = status ? [status] : SUBDIRS;
+
+  for (const s of statuses) {
+    const dir = join(root, INBOX_DIR, s);
+    const metaPath = join(dir, `${docId}.meta.json`);
+    if (!existsSync(metaPath)) continue;
+
+    try {
+      const metadata = JSON.parse(readFileSync(metaPath, 'utf-8'));
+      const contentPath = join(dir, metadata.content_file);
+      const content = existsSync(contentPath) ? readFileSync(contentPath, 'utf-8') : '';
+      return { metadata, content };
+    } catch (_e) { /* fallback: unreadable document */ continue; }
+  }
+  return null;
+}
+
+/**
+ * Move a document between status directories.
+ *
+ * @param {string} root
+ * @param {string} docId
+ * @param {'pending'|'processing'|'done'} fromStatus
+ * @param {'pending'|'processing'|'done'} toStatus
+ * @param {object} [extraMeta] - extra metadata to merge
+ * @returns {boolean}
+ */
+export function moveDocument(root, docId, fromStatus, toStatus, extraMeta = {}) {
+  ensureInboxDirs(root);
+
+  const fromDir = join(root, INBOX_DIR, fromStatus);
+  const toDir = join(root, INBOX_DIR, toStatus);
+  const metaPath = join(fromDir, `${docId}.meta.json`);
+
+  if (!existsSync(metaPath)) return false;
+
+  try {
+    const metadata = JSON.parse(readFileSync(metaPath, 'utf-8'));
+    const contentFile = metadata.content_file;
+
+    // Move content file
+    const fromContent = join(fromDir, contentFile);
+    const toContent = join(toDir, contentFile);
+    if (existsSync(fromContent)) {
+      renameSync(fromContent, toContent);
+    }
+
+    // Update + move metadata
+    metadata.status = toStatus;
+    metadata[`${toStatus}_at`] = new Date().toISOString();
+    Object.assign(metadata, extraMeta);
+
+    const toMeta = join(toDir, `${docId}.meta.json`);
+    writeFileSync(toMeta, JSON.stringify(metadata, null, 2) + '\n', 'utf-8');
+
+    // Remove old meta
+    try { unlinkSync(metaPath); } catch (_e) { /* fallback: already moved */ }
+
+    return true;
+  } catch (_e) { /* fallback: move failed */ return false; }
+}
+
+/**
+ * Mark a document as processing (dispatch launched).
+ *
+ * @param {string} root
+ * @param {string} docId
+ * @param {object} [dispatchInfo] - { txnId, agentName }
+ * @returns {boolean}
+ */
+export function markProcessing(root, docId, dispatchInfo = {}) {
+  return moveDocument(root, docId, 'pending', 'processing', {
+    dispatch_txn_id: dispatchInfo.txnId || null,
+    dispatch_agent: dispatchInfo.agentName || null,
+  });
+}
+
+/**
+ * Mark a document as done (MC created).
+ *
+ * @param {string} root
+ * @param {string} docId
+ * @param {object} [mcInfo] - { missionId }
+ * @returns {boolean}
+ */
+export function markDone(root, docId, mcInfo = {}) {
+  return moveDocument(root, docId, 'processing', 'done', {
+    mission_id: mcInfo.missionId || null,
+  });
+}
+
+/**
+ * Cleanup done documents older than maxDays.
+ *
+ * @param {string} root
+ * @param {number} [maxDays=30]
+ * @returns {number} count of cleaned documents
+ */
+export function cleanupDone(root, maxDays = 30) {
+  const doneDir = join(root, INBOX_DIR, 'done');
+  if (!existsSync(doneDir)) return 0;
+
+  const cleanAll = maxDays <= 0;
+  const cutoff = cleanAll ? Infinity : Date.now() - (maxDays * 24 * 60 * 60 * 1000);
+  let count = 0;
+
+  const metaFiles = readdirSync(doneDir).filter(f => f.endsWith('.meta.json'));
+  for (const file of metaFiles) {
+    const filepath = join(doneDir, file);
+    try {
+      const stat = statSync(filepath);
+      if (cleanAll || stat.mtimeMs < cutoff) {
+        const metadata = JSON.parse(readFileSync(filepath, 'utf-8'));
+        // Remove content file
+        const contentPath = join(doneDir, metadata.content_file);
+        try { unlinkSync(contentPath); } catch (_e) { /* fallback: already removed */ }
+        // Remove meta
+        unlinkSync(filepath);
+        count++;
+      }
+    } catch (_e) { /* fallback: skip corrupted entry */ }
+  }
+
+  return count;
+}

package/lib/core/logger.js

@@ -0,0 +1,20 @@
+/**
+ * Minimal logger — writes to stderr to avoid polluting stdout (reserved for hooks).
+ * Activate debug output via NEMESIS_VERBOSE=1 or --verbose flag.
+ */
+
+export function isVerbose() {
+  return process.env.NEMESIS_VERBOSE === '1' || process.argv.includes('--verbose');
+}
+
+export function warn(msg) {
+  process.stderr.write(`[nemesis:warn] ${msg}\n`);
+}
+
+export function error(msg) {
+  process.stderr.write(`[nemesis:error] ${msg}\n`);
+}
+
+export function debug(msg) {
+  if (isVerbose()) process.stderr.write(`[nemesis:debug] ${msg}\n`);
+}

package/lib/core/mission.js

@@ -0,0 +1,109 @@
+import { writeFileSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadTemplate, mergeTemplate } from './templates.js';
+
+/**
+ * Init a Mission Contract — creates a DRAFT MCT-*.json.
+ */
+export function initMission(id, opts = {}) {
+  const { title = '', summary = '', root = process.cwd(), projectId = '', owner = 'PM' } = opts;
+
+  const hcmDir = join(root, '.nemesis', 'HCM');
+  const contractsDir = join(hcmDir, 'contracts');
+
+  if (!existsSync(contractsDir)) {
+    throw new Error('.nemesis/HCM/contracts/ introuvable. Lancez "nemesis init" d\'abord.');
+  }
+
+  const template = loadTemplate('mission-contract', root);
+  const contract = mergeTemplate(template, {
+    contract_meta: {
+      id,
+      mission_id: `MSN-${id.replace('MCT-', '')}`,
+      project_id: projectId,
+      status: 'DRAFT',
+      owner,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    },
+    contract_payload: {
+      cadrage: { title, summary },
+    },
+  });
+
+  const filepath = join(contractsDir, `${id}.json`);
+  if (existsSync(filepath)) {
+    throw new Error(`Mission Contract ${id} existe deja.`);
+  }
+
+  writeFileSync(filepath, JSON.stringify(contract, null, 2) + '\n', 'utf-8');
+  return { filepath, id, status: 'DRAFT' };
+}
+
+/**
+ * List all Mission Contracts.
+ */
+export function listMissions(hcmDir) {
+  const contractsDir = join(hcmDir, 'contracts');
+  if (!existsSync(contractsDir)) return [];
+
+  return readdirSync(contractsDir)
+    .filter(f => f.startsWith('MCT-') && f.endsWith('.json'))
+    .map(f => {
+      try {
+        const data = JSON.parse(readFileSync(join(contractsDir, f), 'utf-8'));
+        return {
+          id: data.contract_meta?.id || f.replace('.json', ''),
+          title: data.contract_payload?.cadrage?.title || '',
+          status: data.contract_meta?.status || 'UNKNOWN',
+        };
+      } catch (_e) { /* fallback: malformed contract JSON */
+        return { id: f.replace('.json', ''), title: '', status: 'ERROR' };
+      }
+    });
+}
+
+/**
+ * Validate a Mission Contract — transitions DRAFT → VALIDATED.
+ * @param {string} id - MCT ID
+ * @param {string} hcmDir
+ * @returns {{ id: string, status: string }}
+ */
+export function validateMission(id, hcmDir) {
+  const contractsDir = join(hcmDir, 'contracts');
+  const filepath = join(contractsDir, `${id}.json`);
+
+  if (!existsSync(filepath)) {
+    throw new Error(`Mission Contract ${id} introuvable.`);
+  }
+
+  const data = JSON.parse(readFileSync(filepath, 'utf-8'));
+  const status = data.contract_meta?.status;
+
+  if (status === 'VALIDATED') {
+    throw new Error(`Mission Contract ${id} est deja VALIDATED.`);
+  }
+
+  if (data.contract_meta) {
+    data.contract_meta.status = 'VALIDATED';
+    data.contract_meta.validated_at = new Date().toISOString();
+    data.contract_meta.updated_at = new Date().toISOString();
+  }
+
+  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  return { id, status: 'VALIDATED' };
+}
+
+/**
+ * Inspect a specific Mission Contract — full content.
+ */
+export function inspectMission(id, hcmDir) {
+  const contractsDir = join(hcmDir, 'contracts');
+  const filepath = join(contractsDir, `${id}.json`);
+
+  if (!existsSync(filepath)) {
+    throw new Error(`Mission Contract ${id} introuvable.`);
+  }
+
+  return JSON.parse(readFileSync(filepath, 'utf-8'));
+}

package/lib/core/notewriter/config.js

@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const NOTEWRITER_DEFAULTS = {
+  note_enabled: true,
+  note_min_level: 'L1',
+  cr_enabled: true,
+  cr_timer_minutes: 30,
+  cr_min_level_for_inclusion: 'L3',
+};
+
+export const VALID_LEVELS = ['L1', 'L2', 'L3', 'L4', 'L5'];
+
+export function readNotewriterConfig(projectRoot) {
+  const servicesPath = join(projectRoot, '.nemesis', 'services.json');
+  if (!existsSync(servicesPath)) return { ...NOTEWRITER_DEFAULTS };
+  try {
+    const data = JSON.parse(readFileSync(servicesPath, 'utf-8'));
+    const nw = data?.services?.notewriter || {};
+    return { ...NOTEWRITER_DEFAULTS, ...nw };
+  } catch (_e) { /* fallback: corrupted services config */
+    return { ...NOTEWRITER_DEFAULTS };
+  }
+}
+
+export function writeNotewriterConfig(projectRoot, config) {
+  const servicesPath = join(projectRoot, '.nemesis', 'services.json');
+  let data = {};
+  if (existsSync(servicesPath)) {
+    try { data = JSON.parse(readFileSync(servicesPath, 'utf-8')); }
+    catch (_e) { /* fallback: corrupted services config */ data = {}; }
+  }
+  if (!data.services) data.services = {};
+  data.services.notewriter = config;
+  writeFileSync(servicesPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

package/lib/core/notewriter/cr.js

@@ -0,0 +1,237 @@
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCrDir, resolvePendingCrPath, ensureDir } from './paths.js';
+import { readNwRegistry, nextCrId, registerCr, getLastCr, getNotesSinceCr } from './registry.js';
+import { readNote } from './notes.js';
+import { error as logError } from '../logger.js';
+
+const CR_SYSTEM_PROMPT = `Tu es un systeme d'observation silencieux.
+Tu produis un compte-rendu incremental a partir de notes d'observation.
+
+## Contexte
+Tu recois :
+- Un resume du CR precedent (si existant)
+- Les notes d'observation de la periode courante
+
+## Format de sortie
+
+Reponds UNIQUEMENT avec un JSON valide :
+
+{
+  "title": "Titre synthetique de la periode",
+  "summary": "Synthese narrative de la periode (3-8 phrases)",
+  "decisions": ["Decision 1 actee", "Decision 2 actee"],
+  "actions": ["Action en attente 1", "Action en attente 2"],
+  "recontextualization": "Bloc narratif pret a injecter a l'agent. Contient : ou on en est, ce qui a ete decide, ce qui reste a faire, etat de la mission. 5-10 phrases."
+}`;
+
+export { CR_SYSTEM_PROMPT };
+
+export function buildCrPrompt(previousCrSummary, notes) {
+  let prompt = '';
+  if (previousCrSummary) {
+    prompt += `## Resume du CR precedent\n${previousCrSummary}\n\n`;
+  }
+  prompt += `## Notes de la periode (${notes.length} notes)\n\n`;
+  for (const note of notes) {
+    prompt += `### ${note.id} [${note.level}]\n`;
+    prompt += `${note.content}\n`;
+    if (note.extractedActions?.length > 0) {
+      prompt += `Actions : ${note.extractedActions.join(', ')}\n`;
+    }
+    prompt += '\n';
+  }
+  return prompt;
+}
+
+export function parseCrResponse(text) {
+  try {
+    let json = text.trim();
+    if (json.startsWith('```')) {
+      json = json.replace(/^```[a-z]*\n?/, '').replace(/\n?```$/, '');
+    }
+    const parsed = JSON.parse(json);
+    return {
+      title: parsed.title || 'CR sans titre',
+      summary: parsed.summary || '',
+      decisions: Array.isArray(parsed.decisions) ? parsed.decisions : [],
+      actions: Array.isArray(parsed.actions) ? parsed.actions : [],
+      recontextualization: parsed.recontextualization || '',
+    };
+  } catch (_e) {
+    return {
+      title: 'CR non parsable',
+      summary: text.slice(0, 500),
+      decisions: [], actions: [],
+      recontextualization: text.slice(0, 300),
+    };
+  }
+}
+
+export async function generateCR(projectRoot, agentName, trigger, callLlm) {
+  // 1. Notes depuis le dernier CR
+  const noteEntries = getNotesSinceCr(projectRoot, agentName);
+  if (noteEntries.length === 0) return null;
+
+  // 2. Charger les notes completes
+  const notes = [];
+  for (const entry of noteEntries) {
+    const note = readNote(projectRoot, agentName, entry.id);
+    if (note) notes.push(note);
+  }
+  if (notes.length === 0) return null;
+
+  // 3. CR precedent
+  const lastCr = getLastCr(projectRoot, agentName);
+  let previousCrSummary = null;
+  let previousCrId = null;
+  if (lastCr) {
+    previousCrId = lastCr.id;
+    const crDir = resolveCrDir(projectRoot, agentName);
+    const crPath = join(crDir, `${lastCr.id}.json`);
+    if (existsSync(crPath)) {
+      try {
+        const crData = JSON.parse(readFileSync(crPath, 'utf-8'));
+        previousCrSummary = crData.summary || null;
+      } catch (_e) { /* fallback: previous CR unreadable */ }
+    }
+  }
+
+  // 4. Appeler le LLM
+  const userPrompt = buildCrPrompt(previousCrSummary, notes);
+  let llmResponse;
+  try {
+    llmResponse = await callLlm(CR_SYSTEM_PROMPT, userPrompt);
+  } catch (err) {
+    logError(`NoteWriter: erreur LLM CR — ${err.message}`);
+    return null;
+  }
+
+  // 5. Parser
+  const parsed = parseCrResponse(llmResponse);
+
+  // 6. Construire le CR
+  const crId = nextCrId(projectRoot, agentName);
+  const now = new Date().toISOString();
+  const cr = {
+    id: crId,
+    projectId: null,
+    agentId: agentName,
+    sessionId: notes[0]?.sessionId || null,
+    title: parsed.title,
+    trigger,
+    period: {
+      from: notes[0]?.timestamp || now,
+      to: notes[notes.length - 1]?.timestamp || now,
+    },
+    previousCrId,
+    previousCrSummary: previousCrSummary || null,
+    summary: parsed.summary,
+    decisions: parsed.decisions,
+    actions: parsed.actions,
+    noteIds: notes.map(n => n.id),
+    noteCount: notes.length,
+    recontextualization: parsed.recontextualization,
+    generatedAt: now,
+  };
+
+  // 7. Ecrire le fichier CR
+  const crDir = resolveCrDir(projectRoot, agentName);
+  ensureDir(crDir);
+  writeFileSync(join(crDir, `${crId}.json`), JSON.stringify(cr, null, 2) + '\n', 'utf-8');
+
+  // 8. Registry
+  registerCr(projectRoot, agentName, {
+    id: crId, timestamp: now, trigger,
+    noteCount: notes.length, previousCrId,
+  });
+
+  // 9. .pending-cr
+  writePendingCr(projectRoot, agentName, cr);
+
+  return cr;
+}
+
+// --- Timer lazy ---
+
+export function shouldGenerateCR(projectRoot, agentName, configTimerMinutes = 30) {
+  const noteEntries = getNotesSinceCr(projectRoot, agentName);
+  if (noteEntries.length === 0) return false;
+
+  const oldestNote = noteEntries[0];
+  if (!oldestNote.timestamp) return false;
+
+  const elapsed = (Date.now() - new Date(oldestNote.timestamp).getTime()) / (1000 * 60);
+  return elapsed >= configTimerMinutes;
+}
+
+// --- Read / List ---
+
+export function readCr(projectRoot, agentName, crId) {
+  const crDir = resolveCrDir(projectRoot, agentName);
+  const crPath = join(crDir, `${crId}.json`);
+  if (!existsSync(crPath)) return null;
+  try { return JSON.parse(readFileSync(crPath, 'utf-8')); }
+  catch (_e) { /* fallback: corrupted CR */ return null; }
+}
+
+export function listCrs(projectRoot, agentName) {
+  const reg = readNwRegistry(projectRoot, agentName);
+  return reg.crs;
+}
+
+// --- .pending-cr ---
+
+export function writePendingCr(projectRoot, agentName, cr) {
+  const pendingPath = resolvePendingCrPath(projectRoot, agentName);
+  ensureDir(join(pendingPath, '..'));
+  const payload = {
+    crId: cr.id,
+    recontextualization: cr.recontextualization,
+    summary: cr.summary,
+    decisions: cr.decisions,
+    actions: cr.actions,
+    writtenAt: new Date().toISOString(),
+  };
+  writeFileSync(pendingPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+}
+
+export function consumePendingCr(projectRoot, agentName) {
+  const pendingPath = resolvePendingCrPath(projectRoot, agentName);
+  if (!existsSync(pendingPath)) return null;
+
+  try {
+    const data = JSON.parse(readFileSync(pendingPath, 'utf-8'));
+
+    // TTL 1h
+    if (data.writtenAt) {
+      const age = Date.now() - new Date(data.writtenAt).getTime();
+      if (age > 60 * 60 * 1000) {
+        unlinkSync(pendingPath);
+        return null;
+      }
+    }
+
+    // Consommer
+    unlinkSync(pendingPath);
+    return formatCrForInjection(data);
+  } catch (_e) {
+    try { unlinkSync(pendingPath); } catch (_e) { /* fallback: already removed */ }
+    return null;
+  }
+}
+
+function formatCrForInjection(data) {
+  let text = `Voici le compte-rendu de la derniere periode de travail :\n\n`;
+  text += `**${data.crId}**\n\n`;
+  text += data.recontextualization || data.summary || '';
+  if (data.decisions?.length > 0) {
+    text += `\n\n**Decisions actees :**\n`;
+    for (const d of data.decisions) text += `- ${d}\n`;
+  }
+  if (data.actions?.length > 0) {
+    text += `\n\n**Actions en attente :**\n`;
+    for (const a of data.actions) text += `- ${a}\n`;
+  }
+  return text;
+}