Observabilité des agents VFG — plan d'implémentation sécurisé

Ce billet fige le plan d'implémentation pour l'observabilité des agents VFG : architecture retenue, contrats d'événements, hooks multi-clients, Chronowflow, proxy Ollama, scripts Windows, tutoriel opérateur, handoffs et validation finale. Objectif : voir qui travaille où, sans bloquer le prompt et sans exposer de secrets.

Architecture retenue

Chaîne unique

Hooks agents → VFGate :5191 → FG_Chronos :4340 → Chronowflow :4477

Enrichissement optionnel

Ollama :11434 → ai-usage-hub :11435 → VFGate

Décisions (ADR)

• Les hooks natifs déclenchent la télémétrie : un skill ou un appel MCP dépendrait du comportement du modèle.
• VFGate reçoit et route les événements.
• FG_Chronos constitue le ledger temporel durable.
• Chronowflow devient la vue principale détaillée.
• Cockpit reste la synthèse globale, mais son adaptation est différée tant que son WIP actuel est exclu.
• Les pannes de télémétrie sont non bloquantes.
• Les collisions de répertoire produisent une alerte rouge sans refuser le prompt.
• Aucun prompt complet n'est conservé : aperçu masqué de 120 caractères maximum.

Préparation, Git et protection du travail existant

• Ne modifier ni committer aucun fichier de FG_Pulse ou VFG_Cockpit.
• Ne pas inclure les autres dossiers non suivis du méta-dépôt VFG-Workspace.
• Auditer et tester FG_Chronos, puis créer un commit de référence limité exclusivement à FG_Chronos/.
• Vérifier Chronowflow propre et synchronisé avant modification.
• Vérifier VFGate en lecture seule ; utiliser son API existante sans modifier le dépôt si possible.
• Cloner FGDidou/ai-usage-hub dans D:\VFG_PT__\_dev\ai-usage-hub.

Avant chaque tâche

• relever le commit de départ et l'état Git ;
• refuser de commencer si un changement extérieur apparaît dans les fichiers attribués ;
• enregistrer le périmètre dans le handoff.

Après chaque tâche

• tests ciblés ;
• mise à jour du handoff local ;
• commit atomique ;
• enregistrement du hash, des tests et des fichiers touchés dans le handoff global.

Séquence de commits prévue

1. chore(chronos): track temporal ledger baseline
2. feat(chronos): add agent turn event contract
3. feat(chronos): relay agent presence from vfgate
4. feat(presence): add cross-client hook emitter and installer
5. feat(chronowflow): display live agent sessions
6. feat(ai-usage): publish ollama request telemetry
7. feat(runtime): autostart local observability stack
8. docs: add setup tutorial and recovery handoff

Aucun push distant automatique : les commits restent locaux jusqu'à validation globale.

Contrats et comportement

Topic VFGate

Publier sous routing.topic = "agent.presence" :

• agent.turn.started
• agent.turn.progress
• agent.turn.completed
• agent.turn.interrupted
• agent.turn.failed
• agent.subagent.started
• agent.subagent.completed

Payload normalisé

• client, provider, model
• session_id, turn_id, parent_agent_id
• cwd, repo_root, git_branch
• task_preview
• tool_count, occurred_at

Résoudre le dépôt avec git rev-parse --show-toplevel ; utiliser cwd en secours.

FG_Chronos

• Ajouter agent.turn aux types FG_Chronos.
• Transformer chaque VME en événement Chronos déterministe CHR-VME-{vme_id} afin que les reprises ne créent aucun doublon.
• Ajouter GET /v1/query/agents/active, qui retourne :
  • tours et sous-agents actifs ;
  • durée et dernière activité ;
  • progression par nombre d'outils ;
  • répertoires normalisés ;
  • groupes de collisions.

Relais et résilience

• Le relais VFGate → Chronos interroge le journal toutes les 500 ms et conserve un checkpoint local.
• Si VFGate est indisponible, l'émetteur écrit dans une file JSONL locale protégée contre les écritures concurrentes, puis quitte avec succès en moins de 500 ms.
• L'aperçu de tâche est nettoyé des retours ligne et motifs de secrets avant troncature. Le prompt brut ne quitte jamais le processus du hook.

Hooks, règle et skill obligatoires

Créer un seul émetteur Node et un skill canonique vfg-agent-presence.

Configuration fusionnée automatiquement, sans écraser les entrées existantes :

Le skill / rule impose

• un agent = une tâche = un répertoire ou worktree exclusif ;
• interdiction de neutraliser le hook ;
• vérification du répertoire avant travail ;
• absence de secrets dans le titre de tâche ;
• signalement de toute collision ;
• télémétrie non bloquante ;
• mise à jour du handoff avant arrêt ou transfert.

Adaptateurs

• Codex : skill utilisateur et instruction globale.
• Claude Code : skill utilisateur et instruction globale.
• Cursor : règle alwaysApply.
• Kimi : plugin activé avec chargement automatique du skill.

Le hook reste la garantie technique même si le modèle n'invoque pas le skill.

Chronowflow et ai-usage-hub

Chronowflow

• Remplacer le flux simulé par les événements FG_Chronos.
• Conserver les captures manuelles dans une couche distincte.
• Ajouter une grille de carrés au-dessus du chronarbre :
  • vert pulsé : travail actif ;
  • ambre : activité devenue ancienne ;
  • gris : terminé, puis masqué après 60 secondes ;
  • rouge : interruption ou échec ;
  • contour rouge : plusieurs sessions actives dans le même dépôt.
• Afficher client, modèle, dépôt, branche, aperçu, durée, outils et dernière activité.
• Un clic sélectionne la session et son fil chronologique.
• Reconstruire entièrement l'état après rechargement depuis Chronos, sans dépendre de localStorage.

ai-usage-hub

• Faire transiter Ollama par :11435, avec l'instance réelle sur :11434.
• Publier début, fin, modèle, durée et tokens vers VFGate.
• Corréler la requête au tour actif lorsqu'une correspondance unique existe.
• Une requête Ollama directe sans hook reste visible comme « répertoire inconnu ».
• Ne pas forcer Codex, Claude ou Kimi cloud à utiliser le proxy : leurs hooks restent la source de présence.

Configuration automatique Windows

Fournir quatre commandes idempotentes.

install-agent-presence.ps1

• sauvegarde horodatée des configurations ;
• fusion des hooks JSON/TOML ;
• installation du skill et des règles ;
• configuration des URL locales ;
• installation de la tâche planifiée.

start-agent-presence.ps1

• vérifie les ports ;
• démarre les processus manquants en fenêtres masquées ;
• attend les healthchecks ;
• ouvre Chronowflow.

doctor-agent-presence.ps1

• vérifie versions, hooks, tokens, ports, processus, relais et fraîcheur des événements ;
• n'affiche jamais les secrets.

uninstall-agent-presence.ps1

• retire seulement les blocs identifiés comme gérés ;
• restaure les sauvegardes si demandé ;
• retire la tâche planifiée sans supprimer les données Chronos.

Tâche planifiée VFG-Agent-Presence

Démarre à l'ouverture de session utilisateur et lance :

• VFGate :5191
• FG_Chronos :4340
• Chronowflow :4477
• ai-usage-hub :11435
• Ollama :11434 si nécessaire

Elle utilise les droits utilisateur courants et ne publie aucun service hors de 127.0.0.1.

Tutoriel livré

Créer un tutoriel opérateur expliquant :

1. L'architecture et le rôle de chaque service.
2. L'installation automatique en une commande.
3. La vérification avec doctor.
4. Le premier prompt Codex dans VS Code.
5. Les essais Claude Code, Cursor et Kimi.
6. L'utilisation d'Ollama par le proxy.
7. La signification des couleurs.
8. La création d'un worktree par tâche.
9. Le diagnostic d'un carré absent ou bloqué.
10. La consultation des événements VFGate et Chronos.
11. Le redémarrage manuel de la pile.
12. La désinstallation et la restauration des configurations.
13. La future activation du résumé Cockpit lorsque son WIP sera libéré.
14. La future bascule VPS/Tailscale sans changer le format d'événement.

Handoff et résistance à la surcharge de contexte

Maintenir un handoff global unique avec :

• objectif et architecture ;
• décisions et raisons ;
• ports et endpoints ;
• contrat d'événement ;
• état de chaque tâche ;
• propriétaire et répertoire exclusif ;
• commits réalisés par dépôt ;
• tests passés et échecs connus ;
• configurations installées et sauvegardes ;
• prochaine action exacte ;
• procédure de reprise après compaction ou changement d'agent.

Chaque dépôt modifié conserve aussi un handoff court lié au handoff global.

Après une compaction de contexte, l'agent doit reprendre exclusivement depuis :

1. le handoff global ;
2. le handoff du dépôt ;
3. git status ;
4. les derniers commits ;
5. les résultats de tests consignés.

Aucune décision importante ne doit exister uniquement dans la conversation.

Organisation en sous-agents

Utiliser des sous-agents légers uniquement pour des tâches bornées, avec un seul propriétaire par dépôt :

• Agent Chronos : contrat, stockage, relais et requête active.
• Agent Chronowflow : API de lecture et interface.
• Agent ai-usage-hub : proxy Ollama et enrichissement.
• Agent principal : architecture, configuration globale, validation croisée, handoffs et commits du méta-dépôt.

Règles de coordination

• jamais deux agents dans le même dépôt ou git worktree ;
• chaque agent reçoit fichiers autorisés, critères d'acceptation et commande de test ;
• aucun agent ne pousse au distant ;
• un agent ne termine pas sans commit atomique et compte rendu ;
• le principal vérifie le commit et actualise le handoff avant la vague suivante ;
• les tâches dépendantes attendent le commit du contrat Chronos ;
• maximum trois sous-agents simultanés, le quatrième emplacement restant au coordinateur.

Validation finale

• Carré visible moins de deux secondes après un prompt.
• Codex, Claude Code, Cursor et Kimi identifiés correctement.
• Sous-agents visibles séparément.
• Collision du même dépôt visible dans Chronowflow sans blocage.
• Progression actualisée après les outils.
• Stop, interruption et erreur représentés correctement.
• Requête Ollama enregistrée avec modèle, durée et tokens.
• Rechargement de Chronowflow reconstruit les sessions.
• Panne VFGate/Chronos sans blocage du prompt, puis replay sans doublon.
• Aucun prompt complet ou secret présent dans VFGate, Chronos, logs ou handoffs.
• Installation et désinstallation rejouables deux fois sans doublon.
• Redémarrage Windows validé avec lancement automatique.
• Tous les tests des dépôts modifiés passent.
• FG_Pulse et VFG_Cockpit restent bit-à-bit inchangés.