@arka-labs/nemesis 1.2.0

package/lib/kairos/hook-installer.js

@@ -0,0 +1,207 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { debug } from '../core/logger.js';
+
+/**
+ * New Claude Code hooks format (2025+):
+ * Each event is an array of matcher groups, each group has a `hooks` array.
+ * { "hooks": { "EventName": [{ "matcher": "...", "hooks": [{ "type": "command", "command": "..." }] }] } }
+ */
+
+export const KAIROS_HOOKS = {
+  SessionStart:     [{ hooks: [{ type: 'command', command: 'nemesis kairos pre-hook' }] }],
+  UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'nemesis kairos dynamic-hook' }] }],
+  Stop:             [{ hooks: [{ type: 'command', command: 'nemesis kairos post-hook' }] }],
+  PreCompact:       [{ hooks: [{ type: 'command', command: 'nemesis kairos pre-compact' }] }],
+};
+
+export const ALL_HOOKS = {
+  SessionStart:     { command: 'nemesis kairos pre-hook',     label: 'Pre-hook' },
+  UserPromptSubmit: { command: 'nemesis kairos dynamic-hook', label: 'Dynamic-hook' },
+  Stop:             { command: 'nemesis kairos post-hook',    label: 'Post-hook' },
+  PreCompact:       { command: 'nemesis kairos pre-compact',  label: 'Pre-compact' },
+};
+
+export function resolveSettingsPath(projectRoot) {
+  return join(projectRoot, '.claude', 'settings.json');
+}
+
+/**
+ * Check if a command exists in a matcher group array (new format).
+ */
+function hasCommand(groups, cmd) {
+  return (groups || []).some(
+    group => (group.hooks || []).some(h => h.command === cmd),
+  );
+}
+
+export function installHooks(projectRoot) {
+  const settingsPath = resolveSettingsPath(projectRoot);
+  const settingsDir = dirname(settingsPath);
+
+  let settings = {};
+  let merged = false;
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+      merged = true;
+    } catch (e) { debug(`installHooks parse: ${e.message}`); settings = {}; }
+  }
+
+  // Merge hooks (new format)
+  if (!settings.hooks) settings.hooks = {};
+  for (const [event, matcherGroups] of Object.entries(KAIROS_HOOKS)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = matcherGroups;
+    } else {
+      const nemesisCmd = matcherGroups[0].hooks[0].command;
+      if (!hasCommand(settings.hooks[event], nemesisCmd)) {
+        settings.hooks[event].push(...matcherGroups);
+      }
+    }
+  }
+
+  // Write
+  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return { installed: true, path: settingsPath, merged };
+}
+
+export function verifyHooks(projectRoot) {
+  const settingsPath = resolveSettingsPath(projectRoot);
+  const emptyHooks = {};
+  for (const event of Object.keys(ALL_HOOKS)) emptyHooks[event] = false;
+
+  if (!existsSync(settingsPath)) {
+    return { ok: false, hooks: emptyHooks, settingsExists: false };
+  }
+
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); }
+  catch (e) {
+    debug(`verifyHooks parse: ${e.message}`);
+    return { ok: false, hooks: emptyHooks, settingsExists: true };
+  }
+
+  const hooks = {};
+  for (const [event, meta] of Object.entries(ALL_HOOKS)) {
+    hooks[event] = hasCommand(settings.hooks?.[event], meta.command);
+  }
+
+  const allActive = Object.values(hooks).every(Boolean);
+  return {
+    ok: allActive,
+    hooks,
+    settingsExists: true,
+  };
+}
+
+export function getHookStatus(projectRoot) {
+  const settingsPath = resolveSettingsPath(projectRoot);
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); }
+    catch (e) { debug(`getHookStatus parse: ${e.message}`); settings = {}; }
+  }
+
+  const status = {};
+  for (const [event, meta] of Object.entries(ALL_HOOKS)) {
+    const active = hasCommand(settings.hooks?.[event], meta.command);
+    status[event] = { active, command: meta.command };
+  }
+  return status;
+}
+
+/**
+ * Activate a single hook by event name. Direct JSON write — no LLM.
+ */
+export function activateSingleHook(projectRoot, hookEvent) {
+  const meta = ALL_HOOKS[hookEvent];
+  if (!meta) return { ok: false, error: `Hook inconnu: ${hookEvent}` };
+
+  const settingsPath = resolveSettingsPath(projectRoot);
+  const settingsDir = dirname(settingsPath);
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); }
+    catch (e) { debug(`activateSingleHook parse: ${e.message}`); settings = {}; }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks[hookEvent]) settings.hooks[hookEvent] = [];
+
+  if (hasCommand(settings.hooks[hookEvent], meta.command)) {
+    return { ok: true, alreadyActive: true };
+  }
+
+  settings.hooks[hookEvent].push({ hooks: [{ type: 'command', command: meta.command }] });
+
+  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { ok: true, alreadyActive: false };
+}
+
+/**
+ * Deactivate a single hook by event name. Direct JSON write — no LLM.
+ */
+export function deactivateSingleHook(projectRoot, hookEvent) {
+  const meta = ALL_HOOKS[hookEvent];
+  if (!meta) return { ok: false, error: `Hook inconnu: ${hookEvent}` };
+
+  const settingsPath = resolveSettingsPath(projectRoot);
+  if (!existsSync(settingsPath)) return { ok: true, alreadyInactive: true };
+
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); }
+  catch (e) { debug(`deactivateSingleHook parse: ${e.message}`); return { ok: false, error: 'settings.json non parsable' }; }
+
+  if (!settings.hooks?.[hookEvent]) return { ok: true, alreadyInactive: true };
+
+  if (!hasCommand(settings.hooks[hookEvent], meta.command)) {
+    return { ok: true, alreadyInactive: true };
+  }
+
+  settings.hooks[hookEvent] = settings.hooks[hookEvent].filter(
+    group => !(group.hooks || []).some(h => h.command === meta.command),
+  );
+  if (settings.hooks[hookEvent].length === 0) delete settings.hooks[hookEvent];
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { ok: true, alreadyInactive: false };
+}
+
+export function removeHooks(projectRoot) {
+  const settingsPath = resolveSettingsPath(projectRoot);
+  if (!existsSync(settingsPath)) return { removed: false, reason: 'settings.json absent' };
+
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); }
+  catch (e) { debug(`removeHooks parse: ${e.message}`); return { removed: false, reason: 'settings.json non parsable' }; }
+
+  if (!settings.hooks) return { removed: false, reason: 'Pas de hooks' };
+
+  // Remove nemesis matcher groups from each event
+  for (const [event, matcherGroups] of Object.entries(KAIROS_HOOKS)) {
+    if (!settings.hooks[event]) continue;
+    const nemesisCmd = matcherGroups[0].hooks[0].command;
+    settings.hooks[event] = settings.hooks[event].filter(
+      group => !(group.hooks || []).some(h => h.command === nemesisCmd),
+    );
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+
+  // Remove legacy Kairos contextFiles (migration cleanup)
+  if (settings.contextFiles) {
+    settings.contextFiles = settings.contextFiles.filter(cf => cf !== '.nemesis/kairos-context.md');
+    if (settings.contextFiles.length === 0) delete settings.contextFiles;
+  }
+
+  // Clean empty hooks object
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { removed: true };
+}

package/lib/kairos/hook-prompts.js

@@ -0,0 +1,54 @@
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function generateActivationPrompt(hookEvent, command) {
+  return `Tu es en train de modifier les hooks Kairos pour ce projet.
+
+Modifie le fichier \`.claude/settings.json\` a la racine du projet courant
+(PAS ~/.claude/settings.json — hooks par projet uniquement).
+
+ACTION : Ajouter le hook suivant si absent :
+
+{
+  "hooks": {
+    "${hookEvent}": [
+      {
+        "hooks": [
+          { "type": "command", "command": "${command}" }
+        ]
+      }
+    ]
+  }
+}
+
+Regles :
+- Si \`.claude/settings.json\` n'existe pas, cree-le.
+- Si le fichier existe, merge sans ecraser les entrees existantes.
+- Ne touche a aucune autre cle du fichier.
+- Confirme avec : "HOOK_ACTIVATED_OK"`;
+}
+
+export function generateDeactivationPrompt(hookEvent, command) {
+  return `Tu es en train de modifier les hooks Kairos pour ce projet.
+
+Modifie le fichier \`.claude/settings.json\` a la racine du projet courant.
+
+ACTION : Supprimer le groupe de hooks contenant la commande "${command}" dans hooks.${hookEvent}.
+
+Exemple de ce qu'il faut supprimer :
+  { "hooks": [{ "type": "command", "command": "${command}" }] }
+
+Regles :
+- Si d'autres entrees existent dans hooks.${hookEvent}, les conserver.
+- Ne touche a aucune autre cle du fichier.
+- Si l'entree est absente, ne rien faire.
+- Confirme avec : "HOOK_DEACTIVATED_OK"`;
+}
+
+export function writePromptFile(projectRoot, content) {
+  const dir = join(projectRoot, '.nemesis', 'kairos');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const filePath = join(dir, 'hooks-prompt.md');
+  writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}

package/lib/kairos/leader-rules.js

@@ -0,0 +1,94 @@
+export const LEADER_ROLE = {
+  nature: 'organisateur — ne produit pas, ne livre pas, ne code pas',
+  chaine: 'Mission Contract → OdM → Transaction assignation → CR-OdM → CR-Mission',
+};
+
+export const LEADER_RULES = [
+  'Cadrer le Mission Contract avec le PM.',
+  'Creer les OdMs OBLIGATOIREMENT via : nemesis odm init (utilise le template officiel odm_meta/odm_payload).',
+  'Creer une Transaction dans transactions/ a chaque assignation OdM.',
+  'Suivre les statuts OdM : DRAFT → ASSIGNED → IN_PROGRESS → DONE.',
+  'Lire chaque CR-OdM depose par les Experts.',
+  'Valider (VALIDE) ou rejeter (REJET) avec motif explicite.',
+  'Deposer un CR-Mission final quand tous les OdMs sont VALIDE.',
+];
+
+export const LEADER_DISPATCH = {
+  description: 'Dispatcher un OdM via le daemon orchestrateur nemesis orch.',
+  command: 'nemesis odm set-status <ODM_ID> READY_TO_DISPATCH',
+  flow: [
+    'Proposer le dispatch au PM et attendre validation.',
+    'Mettre l\'OdM en READY_TO_DISPATCH : nemesis odm set-status <ID> READY_TO_DISPATCH',
+    'Le daemon nemesis orch detecte et dispatche automatiquement a l\'agent assigne.',
+    'L\'agent tourne en headless. Son Stop hook depose le resultat.',
+    'Le daemon route le resultat selon routing.chain et te notifie via event-bus.',
+    'A reception : classifier la sortie et effectuer la QA.',
+  ],
+  qa: [
+    'Si un agent QA existe dans l\'equipe → lui assigner la QA.',
+    'Si aucun agent QA → le Leader fait la QA lui-meme.',
+    'QA = verifier que le livrable couvre 100% de l\'OdM.',
+  ],
+};
+
+export const LEADER_INTERDICTIONS = [
+  'Ne pas produire de livrables metier.',
+  'Ne pas modifier les livrables des Experts.',
+  'Ne pas sauter de gate.',
+  'Ne pas valider un CR sans l\'avoir lu integralement.',
+  'Ne JAMAIS lancer claude --resume directement. Utiliser nemesis odm set-status pour mettre en READY_TO_DISPATCH.',
+];
+
+export const LEADER_VALIDATION = {
+  VALIDE: 'Le livrable couvre 100% des elements demandes dans l\'OdM sans exception ni simplification.',
+  REJET: [
+    'Au moins un element de l\'OdM non couvert.',
+    'Simplification ou raccourci detecte par rapport aux exigences.',
+    'Hors perimetre OdM.',
+    'Rejection criteria declenche.',
+    'Incoherence interne dans le livrable.',
+  ],
+  sur_rejet: 'Rouvrir l\'OdM avec champ motif_rejet explicite → repasser en ASSIGNED + nouvelle Transaction.',
+};
+
+export const LEADER_PERIMETRE = {
+  lecture_seule: ['.nemesis/HCM/cr/', '.nemesis/HCM/Note/'],
+  ecriture_interdite: ['.nemesis/HCM/project/', '.nemesis/claude/'],
+};
+
+export function formatLeaderContext(agentName) {
+  const lines = [
+    '# Mode Leader', '',
+    `Agent: ${agentName}`,
+    `Nature: ${LEADER_ROLE.nature}`,
+    `Chaine: ${LEADER_ROLE.chaine}`, '',
+    '## Responsabilites', '',
+    ...LEADER_RULES.map(r => `- ${r}`), '',
+    '## Interdictions', '',
+    ...LEADER_INTERDICTIONS.map(r => `- ${r}`), '',
+    '## Dispatch OdM', '',
+    'OBLIGATOIRE : pour dispatcher un OdM, mets-le en READY_TO_DISPATCH. Le daemon nemesis orch le dispatche automatiquement.',
+    'Ne JAMAIS lancer claude --resume manuellement.', '',
+    `1. Verifie les agents disponibles :`,
+    `   nemesis team list`, '',
+    `2. Mets l'OdM en READY_TO_DISPATCH :`,
+    `   ${LEADER_DISPATCH.command}`, '',
+    ...LEADER_DISPATCH.flow.map(r => `- ${r}`), '',
+    '## QA', '',
+    ...LEADER_DISPATCH.qa.map(r => `- ${r}`), '',
+    '## Validation CR', '',
+    `- VALIDE : ${LEADER_VALIDATION.VALIDE}`,
+    '- REJET :',
+    ...LEADER_VALIDATION.REJET.map(r => `  - ${r}`),
+    `- Sur rejet : ${LEADER_VALIDATION.sur_rejet}`, '',
+    '## Perimetre fichiers', '',
+    '- Lecture seule :',
+    ...LEADER_PERIMETRE.lecture_seule.map(p => `  - ${p}`),
+    '- Ecriture interdite :',
+    ...LEADER_PERIMETRE.ecriture_interdite.map(p => `  - ${p}`), '',
+    'Format: JSON structure dans les fichiers HCM. Prose libre uniquement dans summary et motif_rejet. Chaque action tracee — aucune decision implicite.',
+    '',
+  ];
+  return lines.join('\n');
+}
+

package/lib/kairos/pid-checker.js

@@ -0,0 +1,108 @@
+import { readRegistry, getLanes, patchLaneFields } from '../core/registry.js';
+import { detectProject } from '../core/project.js';
+import { debug } from '../core/logger.js';
+
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * Check if a PID is alive using kill -0 (no-op signal).
+ * @param {number|null} pid
+ * @returns {boolean}
+ */
+export function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    debug(`isPidAlive ${pid}: ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Verify if an agent is alive with PID recycling protection.
+ * Combines pid + session_id + pid_registered_at timestamp.
+ * @param {object} lane - Registry lane object
+ * @returns {{ alive: boolean, stale: boolean, reason: string }}
+ */
+export function verifyAgentAlive(lane) {
+  if (!lane) return { alive: false, stale: false, reason: 'no_lane' };
+  if (!lane.pid) return { alive: false, stale: false, reason: 'no_pid' };
+
+  const alive = isPidAlive(lane.pid);
+  if (!alive) return { alive: false, stale: false, reason: 'pid_dead' };
+
+  // PID is alive — check for recycling via pid_registered_at
+  if (lane.pid_registered_at) {
+    const registeredAt = new Date(lane.pid_registered_at).getTime();
+    const age = Date.now() - registeredAt;
+    if (age > STALE_THRESHOLD_MS) {
+      return { alive: true, stale: true, reason: 'pid_stale_24h' };
+    }
+  }
+
+  return { alive: true, stale: false, reason: 'ok' };
+}
+
+/**
+ * Get statuses for all agents in the registry.
+ * @param {string} projectRoot
+ * @returns {Array<{ agentId: string, alive: boolean, stale: boolean, pid: number|null, session_id: string|null }>}
+ */
+export function getAgentStatuses(projectRoot) {
+  const project = detectProject(projectRoot);
+  if (!project) return [];
+  const reg = readRegistry(project.hcm_dir);
+  if (!reg) return [];
+  const lanes = getLanes(reg);
+
+  return lanes.map(lane => {
+    const { alive, stale } = verifyAgentAlive(lane);
+    return {
+      agentId: lane.id || lane.name,
+      alive,
+      stale,
+      pid: lane.pid || null,
+      session_id: lane.session_id || null,
+    };
+  });
+}
+
+/**
+ * Register a PID for an agent in the registry.
+ * Updates pid, pid_registered_at, and session_id.
+ * @param {string} projectRoot
+ * @param {string} agentId
+ * @param {number} pid
+ * @param {string} [sessionId]
+ */
+export function registerPid(projectRoot, agentId, pid, sessionId) {
+  const project = detectProject(projectRoot);
+  if (!project) return;
+
+  const fields = {
+    pid,
+    pid_registered_at: new Date().toISOString(),
+  };
+  if (sessionId) fields.session_id = sessionId;
+
+  // Atomic patch — reads fresh + writes atomically to avoid race conditions
+  // (prevents overwriting leader flag or other fields changed by another process)
+  patchLaneFields(project.hcm_dir, agentId, fields);
+}
+
+/**
+ * Unregister a PID for an agent. Clears pid and pid_registered_at but preserves session_id.
+ * @param {string} projectRoot
+ * @param {string} agentId
+ */
+export function unregisterPid(projectRoot, agentId) {
+  const project = detectProject(projectRoot);
+  if (!project) return;
+
+  patchLaneFields(project.hcm_dir, agentId, {
+    pid: null,
+    pid_registered_at: null,
+  });
+}

package/lib/kairos/situation-detector.js

@@ -0,0 +1,123 @@
+/**
+ * Situation Detector — infer situation from user prompt via keyword-matching.
+ * Fast (< 10ms), no LLM. Used to select sous-familles for Kairos context.
+ */
+
+/**
+ * Situation routing table: keyword → situation + sous-familles.
+ * Order matters — first match with highest score wins.
+ */
+const SITUATION_TABLE = [
+  {
+    situation: 'onboarding',
+    keywords: ['onboarding', 'onboard', 'init', 'demarrage', 'demarrer', 'bienvenue', 'setup'],
+    sousFamilles: ['NUCLEUS', 'SKILLS_CORE'],
+  },
+  {
+    situation: 'debugging',
+    keywords: ['bug', 'erreur', 'error', 'debug', 'fix', 'crash', 'broken', 'casse', 'plantage', 'stack trace', 'stacktrace', 'exception'],
+    sousFamilles: ['SKILLS_CORE', 'ERROR_RECOVERY'],
+  },
+  {
+    situation: 'review',
+    keywords: ['review', 'revue', 'valide', 'validation', 'valider', 'qa', 'controle qualite', 'relecture', 'approve'],
+    sousFamilles: ['NUCLEUS', 'SCOPE', 'RESPONSIBILITIES'],
+  },
+  {
+    situation: 'architecture',
+    keywords: ['archi', 'architecture', 'design', 'refactor', 'restructur', 'pattern', 'conception', 'schema'],
+    sousFamilles: ['NUCLEUS', 'SCOPE', 'DOMAINS', 'RESPONSIBILITIES'],
+  },
+  {
+    situation: 'documentation',
+    keywords: ['doc ', 'readme', 'changelog', 'documentation', 'documenter', 'jsdoc', 'api doc', 'docstring'],
+    sousFamilles: ['NUCLEUS', 'DOMAINS', 'SCOPE'],
+  },
+  {
+    situation: 'audit',
+    keywords: ['audit', 'controle', 'compliance', 'conformite', 'securite', 'security', 'vulnerabilite'],
+    sousFamilles: [], // all sous-familles
+  },
+  {
+    situation: 'implementation',
+    keywords: ['implement', 'implemente', 'code', 'develop', 'developper', 'coder', 'ecrire', 'creer', 'ajouter', 'build', 'feature', 'fonctionnalite'],
+    sousFamilles: ['NUCLEUS', 'SKILLS_CORE', 'DOMAINS'],
+  },
+];
+
+/** Default situation when no keywords match */
+const DEFAULT_SITUATION = {
+  situation: 'general',
+  confidence: 0,
+  sousFamilles: ['NUCLEUS', 'SKILLS_CORE'],
+};
+
+/**
+ * Detect the situation from a user prompt using keyword scoring.
+ *
+ * @param {string} prompt - user prompt text
+ * @returns {{ situation: string, confidence: number, sousFamilles: string[] }}
+ */
+export function detectSituation(prompt) {
+  if (!prompt || typeof prompt !== 'string') {
+    return { ...DEFAULT_SITUATION };
+  }
+
+  const normalized = prompt.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+  const scores = [];
+
+  for (const entry of SITUATION_TABLE) {
+    let score = 0;
+    let matchCount = 0;
+
+    for (const kw of entry.keywords) {
+      const normalizedKw = kw.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+      if (normalized.includes(normalizedKw)) {
+        score += normalizedKw.length; // longer keywords = more specific = higher weight
+        matchCount++;
+      }
+    }
+
+    if (matchCount > 0) {
+      // Bonus for multiple keyword matches
+      score += (matchCount - 1) * 3;
+      scores.push({ ...entry, score, matchCount });
+    }
+  }
+
+  if (scores.length === 0) {
+    return { ...DEFAULT_SITUATION };
+  }
+
+  // Sort by score descending
+  scores.sort((a, b) => b.score - a.score);
+  const best = scores[0];
+
+  // Confidence: normalize score to 0-1 range (capped at 1.0)
+  const confidence = Math.min(1, best.score / 20);
+
+  return {
+    situation: best.situation,
+    confidence: Math.round(confidence * 100) / 100,
+    sousFamilles: best.sousFamilles,
+  };
+}
+
+/**
+ * Get the sous-familles for a known situation.
+ *
+ * @param {string} situation
+ * @returns {string[]}
+ */
+export function getSousFamillesForSituation(situation) {
+  const entry = SITUATION_TABLE.find(e => e.situation === situation);
+  return entry?.sousFamilles || DEFAULT_SITUATION.sousFamilles;
+}
+
+/**
+ * List all known situations.
+ * @returns {string[]}
+ */
+export function listSituations() {
+  return SITUATION_TABLE.map(e => e.situation);
+}

package/lib/sync/fallback-engine.js

@@ -0,0 +1,97 @@
+import { getConnexion, getConnexionCredential } from '../core/connexions.js';
+import { getServiceConfig, SERVICE_DEFAULTS } from '../core/services.js';
+import { callSession } from './service-session.js';
+
+const FALLBACK_TRIGGERS = new Set([
+  'TIMEOUT', 'HTTP_5XX', 'HTTP_429', 'HTTP_401', 'HTTP_403', 'NETWORK_ERROR',
+]);
+
+/**
+ * Execute a service call with automatic silent fallback.
+ * @param {string} root - Project root
+ * @param {string} serviceId - Service identifier (notes, kairos)
+ * @param {Function} callFn - async ({ connexion, credential, model }) => result
+ *   For cli_tools providers, callFn receives ({ connexion, model, callSession: fn })
+ *   where callSession(prompt) sends to the ephemeral session.
+ * @returns {{ result?, connexion_used, is_fallback, degraded, logs }}
+ */
+export async function executeWithFallback(root, serviceId, callFn) {
+  const config = getServiceConfig(root, serviceId);
+  if (!config) throw new Error(`Service "${serviceId}" non configure`);
+
+  const defaults = SERVICE_DEFAULTS[serviceId] || { timeout: 5, fallback_timeout: 3 };
+  const logs = [];
+
+  // Build chain: [primary, ...fallbacks]
+  const chain = [
+    { connexion_id: config.connexion_id, timeout: config.timeout || defaults.timeout },
+    ...(config.fallback || []),
+  ];
+
+  for (let i = 0; i < chain.length; i++) {
+    const entry = chain[i];
+    const connexion = getConnexion(entry.connexion_id);
+    if (!connexion) {
+      logs.push({ step: i, connexion_id: entry.connexion_id, error: 'connexion introuvable', skipped: true });
+      continue;
+    }
+
+    const credential = getConnexionCredential(connexion.id);
+    const model = config.model_override || connexion.model;
+    const timeoutMs = (entry.timeout || defaults.timeout) * 1000;
+    const isCli = connexion.provider === 'cli_tools';
+
+    try {
+      let callPromise;
+      if (isCli) {
+        // cli_tools — no timeout race (process has its own timeout via execFileSync)
+        callPromise = callFn({
+          connexion, model,
+          callService: (prompt) => callSession(serviceId, prompt, {
+            cwd: root, model, timeout: 120,
+          }),
+        });
+      } else {
+        callPromise = callFn({ connexion, credential, model });
+      }
+
+      const result = isCli
+        ? await callPromise
+        : await Promise.race([callPromise, timeoutPromise(timeoutMs)]);
+
+      logs.push({ step: i, connexion_id: connexion.id, name: connexion.name, ok: true });
+      return { result, connexion_used: connexion.name, is_fallback: i > 0, degraded: false, logs };
+    } catch (err) {
+      const errorType = classifyError(err);
+      logs.push({ step: i, connexion_id: connexion.id, name: connexion.name, error: err.message, errorType });
+
+      if (!FALLBACK_TRIGGERS.has(errorType)) {
+        // Definitive error — no fallback
+        throw err;
+      }
+      // Trigger fallback → continue to next in chain
+    }
+  }
+
+  // All failed
+  return { result: null, connexion_used: null, is_fallback: false, degraded: true, logs };
+}
+
+function classifyError(err) {
+  if (err.name === 'AbortError' || err.message === 'timeout') return 'TIMEOUT';
+  const msg = (err.message || '').toLowerCase();
+  if (msg.includes('etimedout') || msg.includes('timedout')) return 'TIMEOUT';
+  if (msg.includes('econnrefused') || msg.includes('enotfound') || msg.includes('fetch failed')) return 'NETWORK_ERROR';
+  const status = err.status || err.statusCode;
+  if (status >= 500) return 'HTTP_5XX';
+  if (status === 429) return 'HTTP_429';
+  if (status === 401) return 'HTTP_401';
+  if (status === 403) return 'HTTP_403';
+  return 'UNKNOWN';
+}
+
+function timeoutPromise(ms) {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error('timeout')), ms);
+  });
+}