Vue d'ensemble du harness agentique Synedre OS

Vue d'ensemble du harness agentique

Le harness est le dispositif central de Synedre OS qui transforme toute demande entrante — un email reçu, un message dans le cockpit, un déclencheur planifié — en action concrète et déployée : du code commité, une réponse rédigée, un site mis à jour. Il fonctionne sans état métier hors base de données.

Trois principes structurants

• Base de données en source unique de vérité. La base PostgreSQL centralise toutes les entités métier : VPS, clients, chantiers, agents, cicatrices, runs. Les fichiers de documentation ne portent que des runbooks et des schémas d'architecture. Aucune information métier ne vit hors base.
• Asymétrie entre déploiement et livraison. Le déploiement en préprod est lancé automatiquement par le système, sans validation humaine. La livraison en production est gatée par la flotte : chaque environnement client porte un indicateur autorisant ou non le ship automatique ; en mode non surveillé, la livraison de nuit exige en outre une preuve de QA verte.
• Gouvernance par garde-fous. Des hooks intercèdent avant chaque action outillée de l'agent, un scan antivirus est obligatoire avant toute ouverture de pièce jointe, et une procédure en sept étapes encadre la création de tout chantier. Toute violation est enregistrée comme dette d'architecture prioritaire.

Les trois couches d'exécution

Le harness repose sur trois couches qui partagent toutes la même base de données, mais par des transports distincts.

Le cockpit (interface web)

Une application web Nuxt standalone constitue le cockpit /hub/*, accessible sur le VPS du vaisseau-mère. Elle accède à la base via un adaptateur de requêtes qui traduit à la volée certaines constructions SQL vers leur équivalent PostgreSQL natif. Le cockpit est découpé en une vingtaine de modules fonctionnels indépendants.

Certaines traductions sont automatiques (gestion des placeholders, préfixes de schéma, gestion des conflits d'insertion, arithmétique de dates). D'autres constructions spécifiques doivent être portées manuellement : mises à jour conditionnelles à l'insertion, récupération du dernier identifiant inséré, agrégation de chaînes, recherche dans des listes, formatage de dates.

Le moteur d'orchestration (couche Python)

Une collection de façades Python assure l'orchestration complète : classification des demandes entrantes par le moteur Atlas, exécution des automates, gestion de la mémoire, audits, email, et déploiement. L'accès à la base se fait par exécution de commandes SQL au sein du container de base de données.

Les scripts et l'ordonnancement (couche shell/Node)

Des scripts shell et Node gèrent les wrappers de déploiement, le lancement des agents en sous-processus interactifs, l'extraction des pièces jointes, les sauvegardes et les tests de bout en bout. L'ordonnancement de la quasi-totalité des automates repose sur le crontab système — le scheduler intégré à l'application web étant hors service depuis mai 2026.

Schéma de topologie

                      DEMANDE
   email forwardé ───┐        ┌─── chat console cockpit /hub/runs
   boîte agentique   │        │    (scopé vaisseau-mère ou tenant)
                     ▼        ▼
        ┌───────────────────────────────────────────────────────┐
        │  COUCHE ORCHESTRATION  (façades Python)               │
        │  Atlas : poll boîte · classification · spawn          │
        │  Exécution : worker de tâches · moteur réflexe        │
        │  Mémoire / audits / email / deploy                    │
        │  Invocation agent Claude = lanceur node-pty           │
        │                      (JAMAIS en mode pipeline -p)     │
        └──────────────┬───────────────────────┬────────────────┘
       accès DB        │                        │ transfer fichiers + relance service
                       ▼                        ▼
        ┌───────────────────────────┐   ┌──────────────────────────┐
        │  BASE DE DONNÉES          │   │  COCKPIT  (app Nuxt)      │
        │  PostgreSQL               │◄──┤  /hub/*  sur le VPS       │
        │  ~270 tables + vues       │   │  adaptateur SQL + modules │
        └───────────────────────────┘   └──────────────────────────┘
                       ▲
        crontab        │  wrapper cron → façades Python
        (ordonnanceur) │  scripts shell/Node (backups, scans, deploy)
                       │
        ┌──────────────┴────────────────────────────────────────┐
        │  COUCHE SCRIPTS  (deploy, hooks, cron, tests)          │
        │  ./deploy / ./ship → bibliothèque de déploiement       │
        │  hooks PreToolUse / Stop / …                           │
        └────────────────────────────────────────────────────────┘

Points de vigilance topologiques

• Le container de base de données, la base elle-même et le schéma portent trois noms distincts — ne pas les confondre.
• Plusieurs entités exposées comme des tables sont en réalité des vues héritées de la migration progressive du système. Les lectures passent par la vue ; les écritures ciblent la table physique sous-jacente.
• L'entité « chantier » est répartie sur deux familles de tables issues de deux ères du système ; les deux doivent être maintenues de façon cohérente.
• Le cockpit fonctionne en mode autonome : il n'étend plus le cœur du produit PaaS public. La sécurité d'accès repose sur l'infrastructure réseau (tunnel + garde d'accès nginx) ; un middleware injecte automatiquement une session fondateur, ce qui satisfait les vérifications d'authentification côté cockpit.

Cycle de vie complet d'une demande

Le chemin canonique va de l'email reçu jusqu'à l'action déployée. Deux portes d'entrée alimentent le même moteur : la boîte agentique (email forwardé) et la console scopée du cockpit (chat Atlas).

Étape 0 — Ingestion

Un email forwardé vers la boîte agentique est détecté par le poll IMAP planifié toutes les minutes. Il est enregistré en base en deux entrées liées : le message brut et son enveloppe de traitement (statut received).

Étape 0b — Scan des pièces jointes (doctrine P0)

Si le message contient des pièces jointes, un scan antivirus et heuristique est déclenché avant toute autre opération. Tant que le verdict n'est pas clean, la classification est bloquée.

Étape 1 — Classification

Le moteur Atlas soumet le message à un modèle de langage (via le fournisseur IA configuré) et obtient un intent parmi un ensemble strict et contrôlé : run, chantier, question, noise, negociation, conseil. Une injection de prompt est impossible car l'énumération est validée côté serveur. La classification matérialise au plus une ligne dans la table correspondant à l'intent détecté.

Étape 2 — Spawn et orchestration

Un processus planifié toutes les cinq minutes (avec un décalage de deux minutes pour passer après la classification) récupère les demandes classifiées éligibles. Un verrou consultatif en base évite tout double-spawn concurrent. L'agent Claude est lancé en sous-processus interactif via un lanceur Node/pty avec les paramètres suivants :

• Pas de persistance de session entre deux spawns — isolation complète, zéro fuite de contexte inter-runs.
• Modèle : Sonnet.
• Outils autorisés : liste blanche explicite (optionnelle, par exemple lecture seule pour la QA).
• Timeout : 2 400 secondes (configurable à l'appel ; le lanceur applique 900 secondes par défaut).
• Les variables de connexion à la base et le contexte d'exécution sont injectés dans l'environnement du sous-processus.

Pièges d'intégration documentés :

• L'argument --add-dir est varargs : il doit apparaître avant tous les autres flags.
• --allowed-tools est également varargs : sa valeur doit être suivie d'un flag nommé, jamais du prompt final.
• La fermeture du flux de log doit intervenir après l'émission de l'événement de sortie du pty — l'inversion provoque une troncature silencieuse.
• Le drain de stdout doit être complété avant process.exit() pour éviter la troncature en sortie de pipe.

L'agent écrit son résultat dans un fichier temporaire puis se termine. Le post-spawn orchestre ensuite deux branches :

• Branche sans code (run / question / négociation) : envoi d'un récapitulatif email, statut actioned.
• Branche avec code (chantier) : déploiement automatique en préprod, puis QA à deux niveaux par route :

1. Niveau 1 : vérification HTTP (code de statut + patterns d'erreur par expression régulière).
2. Niveau 2 : navigation Playwright en mode headless (erreurs console, erreurs de page, capture d'écran).

Les erreurs 401 et les erreurs HTTP/2 sur les routes préprod protégées par authentification sont filtrées et ignorées. En cas d'échec, le spawn est relancé jusqu'à trois fois avant escalade humaine.

Étape 3 — Chantier (si intent = chantier)

La création d'un chantier suit une procédure en sept étapes : audit des agents disponibles, rédaction de la lettre de mission, recrutement d'au moins deux agents. La création est atomique en base (tables chantier, travaux et tâches insérées en une seule transaction). L'exécution passe ensuite par le worker de tâches (planifié à la minute) ou le moteur réflexe selon la nature des tâches. La cascade de statuts remonte de la tâche au travail puis au chantier. Une équipe QA peut être recrutée si nécessaire.

Le chantier atteint le statut test après déploiement préprod et revue humaine ; la livraison en production (./ship) le fait passer à done.

Étape 4 — Apprentissage (asynchrone)

Chaque succès ou échec notable génère une cicatrice. Celle-ci alimente la mémoire vectorielle, suggère une règle apprenante soumise à validation humaine dans le cockpit, et intègre ensuite les runbooks ou règles de comportement — actifs dès la session suivante de l'agent.

Email sortant

Aucun message ne part jamais directement vers un client : tout email sortant transite par la façade de messagerie en mode brouillon, soumis à validation explicite avant envoi. L'agent Atlas écrit à l'administrateur du système, jamais au demandeur original.

Ordonnancement

L'ensemble des automates récurrents est piloté par le crontab système (le scheduler intégré à l'application web est hors service depuis mai 2026). Les fréquences clés sont les suivantes :

Processus	Fréquence	Rôle
Poll de la boîte agentique (+ scan + classification)	Toutes les minutes	Ingestion des emails entrants
Spawn Atlas	Toutes les 5 min (décalé de 2 min)	Lancement des agents sur les demandes classifiées
Worker de tâches	Toutes les minutes	Exécution des tâches de chantier
Automates récurrents divers	Variable (≈ 69 entrées actives)	Sauvegardes, watchers, audits, maintenance

Glossaire des concepts cardinaux

Les termes suivants forment le vocabulaire structurant de Synedre OS. Chaque concept désigne un rôle précis dans l'architecture ; leur distinction évite les confusions opérationnelles.

Concept	Définition
Atlas	L'orchestrateur central. Atlas est une persona enregistrée en base de données — un agent de la famille direction — sans processus propre en veille permanente. « Être Atlas » signifie instancier une session de raisonnement avec le cadre cognitif Atlas, lequel pilote la classification des demandes entrantes, le lancement des agents délégués et leur orchestration en cascade.
Agent	Une persona — identité, cadre cognitif et périmètre métier — injectée dans le contexte d'un modèle de langage pour exécuter une tâche. Synedre OS compte trente agents actifs, répartis en quatre familles : direction, cadrage, exécution et validation. Un agent raisonne (cycle ReAct) ; il n'exécute pas une routine figée.
Automate	Un script déterministe qui exécute une routine codée en dur. Un automate peut invoquer un modèle de langage, mais son flux de contrôle reste prédéfini — c'est l'opposé conceptuel de l'agent. Chaque automate est inscrit dans un registre central et produit une entrée de journal à chaque exécution.
Chantier	Une mission structurée multi-étapes : l'unité de travail de plus haut niveau. Un chantier est créé atomiquement avec au moins un travail et une tâche. La hiérarchie est : 1 chantier = N travaux = N tâches.
Travail	Un lot granulaire d'un chantier — une phase ou un sous-objectif — avec son agent responsable, son périmètre et ses critères de sortie. Les travaux portent les cascades de statut et le mécanisme de déblocage (travail-bis).
Tâche	L'unité atomique assignée à un agent nommé, avec une estimation de consommation de tokens et un modèle recommandé.
Run	Une exécution scopée pilotée par Atlas sur un périmètre donné — le vaisseau-mère ou un VPS client — dont le contexte (machine, client, boîte mail) est chargé au démarrage. Un run est déclenché par un email entrant ou depuis la console. À ne pas confondre avec l'unité d'exécution déléguée à un agent, qui est un objet distinct dans le modèle de données.
Cicatrice	Une leçon gravée issue d'un échec (kind = failure) ou d'un succès reproductible (kind = victory). Chaque cicatrice est indexée en base vectorielle pour le rappel sémantique, scorée par importance et constitue la porte d'entrée de la boucle d'apprentissage.
Orbite	Anneau d'organisation visuelle des agents (1, 2 ou 3). Important : la valeur numérique stockée en base par agent est distincte du rendu visuel dans le tableau de bord, qui recalcule l'anneau depuis la famille de l'agent (direction → anneau 1, cadrage/exécution → anneau 2, validation → anneau 3). C'est la famille qui fait foi, pas la valeur numérique brute.
Façade	Un point d'entrée unique et obligatoire pour une capacité donnée, rendant toute opération non-contournable. Les façades couvrent notamment l'envoi d'email, l'appel aux modèles d'IA, le scan des pièces jointes et l'accès à la base de données. Elles sont généralement doublées d'un crochet de pré-exécution qui bloque tout accès direct.

Autres termes utiles dans la documentation :

• Knock-gate — dispositif de filtrage en amont du hub combinant cookie de session et jeton d'accès ; rend le hub inaccessible sans authentification préalable.
• Pseudo-TTY — mécanisme système obligatoire pour instancier un agent programmatiquement ; l'invocation en sous-processus direct est proscrite.
• Scan-first — doctrine : aucune pièce jointe n'est ouverte ou traitée avant qu'un verdict clean ait été rendu par le moteur antivirus.
• Travail-bis — travail portant une référence vers un travail bloqué (paused) qu'il a pour mission de débloquer une fois résolu.

Les frontières dures (non-négociables)

Les règles suivantes sont appliquées par l'ensemble du harness et ne souffrent aucune exception. Elles sont rappelées ici sous forme condensée ; chaque page thématique en détaille les modalités techniques.

• Base de données unique. Aucun contenu métier ne réside dans des fichiers de configuration ou des documents statiques. Toute donnée structurée est persistée en base centrale.
• Anti-fuite de secrets (P0). Aucun secret n'apparaît en clair dans un fichier versionné. Les secrets vivent dans des fichiers d'environnement hors dépôt et ne sont référencés que par leur nom de variable. Cinq niveaux de confidentialité sont définis.
• Scan antivirus avant ouverture. Une pièce jointe reçue n'est jamais ouverte ni transmise tant que le moteur de détection n'a pas rendu un verdict clean.
• Zéro communication client initiée par l'IA. Tout envoi d'email vers un client transite par la façade d'envoi avec validation humaine préalable (show-before-send). Les prises de rendez-vous passent par un lien Calendly ; l'IA ne compose pas de message direct sans revue.
• Procédure en sept étapes. Aucun chantier n'est ouvert hors de la procédure de création atomique avec squelette pré-défini. Tout chantier sur le périmètre d'un client implique au minimum deux agents distincts.
• Commit en flux continu. Aucun travail ne peut être marqué terminé sans que les modifications soient commitées. L'agent commit ; l'opérateur humain ne saisit jamais les commandes de versionnement manuellement. Un crochet bloquant en fin de session fait respecter cette règle.

Carte de la documentation

Le dossier de documentation technique est organisé en pages thématiques. Chaque page couvre un sous-système autonome.

Page	Sous-système couvert
La couche données	Base de données centrale, conventions de préfixes de tables, couche d'adaptation relationnelle, classes d'entités Python, vues de compatibilité, internationalisation.
Le cœur agentique	Atlas, modèle d'agents, classification d'intention, instanciation via pseudo-TTY, orchestration déploiement → QA → email, orbites, calibration des modèles.
Chantiers, travaux & tâches	Hiérarchie des unités de travail, création atomique avec squelette, procédure en sept étapes, verrou multi-session, cascades de statut, mécanisme travail-bis.
Automates, crons & runs	Catalogue des façades, enveloppe d'exécution planifiée, registre des automates, distinction run principal / unité d'exécution déléguée, double scheduleur.
Le Hub	Application de supervision, modules et couches, pages du tableau de bord, points d'entrée d'API, authentification knock-gate + auto-session, consoles.
Inbox, Atlas Inbox & email	Deux pipelines de réception IMAP (hub vs Atlas), façade d'envoi, scan antivirus, doctrine zéro-comm-client.
Mémoire & apprentissage	Mémoire à trois niveaux (fichiers de référence / base de connaissances / base vectorielle), rappel RAG, boucle cicatrices → suggestions → leçons, façade IA.
Déploiement & infrastructure	Asymétrie des commandes de livraison, dispatching par fichier de configuration, build centralisé + transfert compressé, auto-déploiement du vaisseau-mère, inventaire des VPS clients, gestion des secrets, règle commit-avant-déploiement.
Catalogue des façades & points d'entrée	Recensement de toutes les façades par famille, mode d'invocation (planifié / CLI / compétence / crochet / bibliothèque), crochets répertoriés.
Compétences, agents & crochets	Compétences injectables, sous-agents délégables, configuration des crochets de session (pré/post exécution), permissions et variables d'environnement.