Aller au contenu principal

ADR-0164 : Bibliothèque Navin activée par projet, règles de projet, MCP et canaux rattachés au projet

Contexte​

La plateforme réutilise le code de Navin (navin-ai-v2/navin). Le paquet Navin contient 265 compétences (skills/), 17 plugins (builtin_plugins/), 20 commandes (builtin_commands/), 14 agents (builtin_agents/), le catalogue marketplace.json, 31 préréglages de serveurs MCP (webui/mcp_presets_api.py, MCP_PRESETS), 10 canaux de messagerie (channels/*.py et leur contrat de configuration channels/_setup.py) et la lecture des règles de projet des agents de code (agent/project_rules.py). Les clients de la plateforme doivent pouvoir réutiliser chacun de ces éléments dans leurs projets, avec l'isolation tenant puis projet, sans dépendre d'un poste où Navin est installé.

Décision​

  1. Copie versionnée : tools/navin_library/sync.py copie la bibliothèque dans catalog/navin (compétences, plugins, commandes et agents avec leurs noms de dossier, marketplace.json), extrait sans importer le code Navin (module ast) les préréglages MCP (mcp-presets.json), les contrats des canaux (channels.json) et les sources de règles (rule-sources.json), et écrit index.json avec l'empreinte sha256 de chaque élément. Les tirets longs sont remplacés par - à la copie. --check échoue quand la copie ne correspond plus à la source. Le dossier n'est jamais modifié à la main.
  2. Activation par projet (V197, eai.navin_library_activations, RLS forcée) : une compétence activée est enregistrée dans le Skill Registry du tenant avec la signature navin-library:<nom> (signataire navin-library), vérifiée par eai.domains.skills.signing contre l'empreinte du SKILL.md dans l'index ; le Skill Loader la sert donc comme une compétence signée. Un plugin active ses compétences, commandes et agents (colonne via_plugin) et les retire avec lui. Une compétence de la bibliothèque qu'aucun projet n'utilise plus passe deprecated.
  3. MCP par projet : eai.mcp_servers et eai.channels reçoivent project_id et preset. Un serveur créé depuis un préréglage HTTP passe par la passerelle MCP existante ; un champ secret n'est accepté que comme référence openbao:// ou env://, et le nouveau type d'authentification query_param ajoute le paramètre secret au moment de l'appel, jamais dans l'URL stockée. Un préréglage stdio s'exécute là où sa commande s'exécute : la page MCP du Navin Manager (nm.mcp_servers, V068, permissions mcp:read et mcp:manage) le gère par tenant et par projet, teste la connexion (initialize, tools/list) et scelle ses secrets en AES-256-GCM ; le Control Plane l'enregistre ensuite par son point d'accès HTTP.
  4. Canaux réutilisables : le contrat des canaux accepte discord, telegram, matrix, mattermost et signal, et spec.connection (provider, adapter, settings, secret_refs) nomme l'adaptateur Navin. L'installation vérifie le contrat de configuration (champs, types, choix, exigences, secrets par référence uniquement). Le pont de canaux du SDK Python (enterprise_ai.channels.bridge) relaie les messages d'un adaptateur vers POST /v1/channels/{name}/inbound.
  5. Règles de projet (V197, eai.project_rules) : import des fichiers .navin/rules/*.md, .cursor/rules/*.mdc (alwaysApply, description, globs), .cursorrules, .clinerules, .windsurfrules et .github/copilot-instructions.md ; GET /v1/projects/{id}/rules/prompt rend la section de prompt de Navin (règles permanentes incluses et bornées, règles conditionnelles listées avec leurs globs).

Alternatives écartées​

  • Importer le paquet Python navin dans le Control Plane : il tire tout le poste de travail Navin et son runtime. La copie de fichiers et l'extraction ast ne dépendent que de la bibliothèque standard.
  • Stocker les secrets des préréglages dans les tables du Control Plane : les secrets d'agents restent dans OpenBao ou le Credential Broker, jamais lisibles par un agent.

Conséquences​

Une nouvelle version de Navin se reprend en relançant tools/navin_library/sync.py ; le test test_navin_library.py échoue tant que l'index, marketplace.json et les fichiers copiés ne correspondent pas. Le code Navin copié porte la licence du dépôt navin-ai-v2, éditée par Navinspire IA, éditeur de la plateforme.

Preuves​

services/control-plane/tests/test_navin_library.py, services/control-plane/tests/test_navin_library_projects.py, navin-manager/server/tests/test_mcp_servers.py, navin-manager/ui/src/test/mcp.test.tsx, les tests de conformité des quatre SDK.