[Feature Request] Watchdog, hooks d'événements et tableau de bord d'observabilité

[theshwal]

English summary

People running OpenFox sessions in the background (locally, in CI, or via CLI) need a way to know whether a session is working, progressing, waiting for input, stalled, blocked or finished without repeatedly asking "where is it?" or keeping an LLM active just to monitor progress. This request proposes a passive Watchdog layer — events, status snapshots and a simple read-only dashboard — strictly separate from the execution engine, with explicit limits on what the MVP should and should not do. This is a discussion, not a roadmap proposal; we are open to maintainers' feedback on architecture, transport and the smallest useful MVP.

Problème humain observé

Quand une session OpenFox tourne en arrière-plan (en local, en SSH, en CI, ou pilotée via la CLI évoquée dans l'Issue #199), on ne dispose pas d'un moyen simple et factuel de savoir :

• est-ce qu'elle travaille réellement en ce moment ;
• est-ce qu'elle progresse vraiment (vs. elle boucle / rature) ;
• est-ce qu'elle attend une action de l'utilisateur (question, confirmation, validation de plan) ;
• est-ce qu'elle est bloquée ou simplement inactive ;
• est-ce qu'elle est terminée (succès, échec, annulation).

Aujourd'hui, pour le savoir, on doit soit consulter l'UI, soit demander « où en est-on ? » au modèle, ce qui gaspille des tokens et donne une réponse en prose peu fiable. Maintenir un LLM dédié à la surveillance est également coûteux et redondant.

Distinction importante

Pour pouvoir distinguer « travaille » de « progresse réellement », deux horodatages doivent être exposés séparément :

• lastActivityAt : dernière trace de vie brute (événement réseau, log, tick), même si le modèle boucle.
• lastProgressAt : dernière avancée factuelle (critère validé, étape terminée, livrable produit, vérification passée).

L'absence de progrès depuis longtemps, alors que lastActivityAt est récent, est précisément le signal « stalled » observé dans l'issue #108.

États proposés (à discuter)

Vocabulaire indicatif, à aligner avec ce que les mainteneurs envisagent :

• queued : en attente de démarrage.
• running : active, mais sans garantie de progrès.
• progressing : activité et progrès observés.
• waiting_for_user : une action humaine est requise (question, confirmation, validation).
• stalled : activité sans progrès depuis un seuil à définir.
• blocked : bloquée par une dépendance interne (erreur, garde-fou, dépendance manquante).
• completed : terminée avec succès.
• failed : terminée en erreur.
• cancelled : arrêtée explicitement.

Contrat JSON versionné

Pour que le dashboard et les agents externes (Hermes, CLI évoquée dans #199) puissent consommer les informations sans parser de la prose LLM, un contrat JSON versionné est nécessaire. Minimum attendu :

• version explicite (schemaVersion).
• identifiant de session, identifiant de projet, mode (Plan / Build / Verify).
• phase courante, étape courante, critères (total / validés / en attente / échoués).
• lastActivityAt, lastProgressAt, et un progress exprimé en preuves factuelles (critères validés, étapes terminées, vérifications passées) — pas un pourcentage ni une durée inventée.
• actionRequired : description structurée d'attente, le cas échéant.
• links : liens profonds vers l'UI OpenFox.

Événements de haut niveau (liste indicative)

À exposer via un flux public (WebSocket, SSE, fichier, ou hook HTTP) :

• plan.ready
• user.action_required
• workflow.step.started
• workflow.step.completed
• session.stalled
• session.blocked
• verification.failed
• task.completed
• session.failed

Ces événements doivent être factuels et corrélés à un identifiant de session stable.

Hooks

Trois modes de réception, à choisir selon le contexte :

• flux public du serveur (WebSocket / SSE) ;
• commande locale (le watchdog est lui-même un consommateur du flux) ;
• hook HTTP sortant (pour des intégrations type tableau de bord distant ou alerting).

Le système doit prévoir :

• filtrage par projet, session, type d'événement ;
• corrélation (identifiant unique d'événement, requestId / sessionId) ;
• reprise (le consommateur peut se reconnecter et rattraper un flux) ;
• déduplication côté consommateur ;
• garde-fous de sécurité (pas d'actions destructives via les hooks).

Dashboard simple (lecture seule)

Un premier palier pourrait être un tableau de bord HTML/CSS/JS en lecture seule, indiquant pour chaque session :

• carte projet + session ;
• phase, étape, critères ;
• dernier progrès et action requise ;
• sons limités (uniquement user.action_required et session.failed) ;
• liens profonds vers l'UI OpenFox.

Ce dashboard est volontairement passif : il observe, il n'agit pas.

MVP : passif uniquement

Le MVP de cette Issue B est volontairement restreint à :

• observation (lecture de l'état structuré) ;
• émission d'événements ;
• dashboard read-only ;
• sons et liens ;
• aucune relance, aucun retry, aucun abort automatique.

Toute action de reprise, retry ou annulation doit passer par l'interface officielle de contrôle (GUI ou la CLI de l'Issue #199), pas par le watchdog.

Évolution ultérieure (à valider avec les mainteneurs)

• Reprise automatique d'une session stalled, sous contrôle explicite et via l'API officielle.
• Retry et abort, également via l'API officielle.
• Corrélation multi-sessions (projet, file d'attente).

Hors périmètre explicite

• Lecture directe de la base SQLite.
• Parsing de la prose LLM pour inférer un état.
• Faux pourcentage de progression ou durée estimée inventée.
• Toute tentative de faire du watchdog une nouvelle source de vérité.

Questions ouvertes aux mainteneurs

• Comment définir de façon prudente lastProgressAt sans tomber dans le piège du « progrès simulé » ?
• Le watchdog doit-il être dans le dépôt OpenFox ou un consommateur externe (Discussion code-review-graph save 93x tokens per session #179 a déjà cette couleur) ?
• Quel transport pour les hooks : WebSocket, SSE, hook HTTP sortant, fichier ?
• Quel est, selon vous, le plus petit MVP réellement utile ?

Références

• Issue Some edit file tool call make the workflow stop #108 : exemple concret de session qui « tourne » sans progrès réel.
• Discussion open design integration #198 : intégration Open Design, qui suppose une vision claire de l'état des sessions.
• Issue [Feature Request] CLI de pilotage et interface d'automatisation pour OpenFox #199 : CLI de pilotage, qui consommera les mêmes états et événements.

[theshwal]

Proposed narrower scope and related issues

After reviewing the existing architecture, I think this issue could be implemented more narrowly than originally described.

OpenFox already has an append-only EventStore, per-session sequencing, snapshots, live WebSocket delivery and folded session state. The initial implementation should extend those existing mechanisms rather than introduce another lifecycle model, event journal or source of truth.

Related issues

• [Feature Request] CLI de pilotage et interface d'automatisation pour OpenFox #199 should consume the same read-only session status from the CLI.
• Support of Hooks #64 may later cover generic hooks, but should remain outside the initial scope.
• Some edit file tool call make the workflow stop #108, [Bug] OpenFox remains stuck running while llama.cpp is no longer responding #151 and Chat error 400 #212 are useful acceptance scenarios for sessions that appear active, are waiting, become stuck or terminate with an error.
• [Feature Request] Suivi des ressources système de l'hôte et des process OpenFox #203 is complementary host/process telemetry and should remain separate.
• Bug: les streams sans usage remettent le contexte de session à 0 et empêchent la compaction #211 does not appear necessary for the initial scope.

Suggested MVP

The existing REST conventions suggest a lightweight endpoint such as:

GET /api/sessions/:id/status

The current GET /api/sessions/:id response includes messages, context state, queue state, pending questions, pending confirmations and the active workflow execution. It is appropriate for loading a complete session, but unnecessarily expensive for repeated status checks.

The dedicated endpoint could return only reliably known information:

{
  "status": {
    "sessionId": "...",
    "state": "running",
    "phase": "build",
    "workflowStep": null,
    "waitingForUser": false,
    "lastActivityAt": "...",
    "terminalReason": null
  }
}

The status should:

• be derived from the existing session state and EventStore;
• avoid loading or serializing the conversation;
• avoid a second event journal or parallel session state machine;
• avoid periodic heartbeat events;
• remain read-only and outside agent execution.

For live updates, the existing EventStore subscription and WebSocket sequencing should be reused. No additional persisted event stream or replay mechanism should be necessary.

Stall detection

A stalled indication should be evaluated separately, after the lightweight status surface exists.

It should initially be a derived indication rather than a persisted session state, and should only be exposed when OpenFox has a reliable factual signal that progress has stopped.

When progress cannot be measured reliably, the status should remain unknown rather than being inferred from LLM prose.

KV-cache invariant

Cache Impact: No

This status surface would only read existing session and event state. It must remain entirely outside the LLM request path and must not modify or rebuild prompts, tools, skills, dynamic context or warmup state.

It must not invoke an LLM or inject observability data into model messages or system reminders.

A focused regression test should confirm that repeated status reads leave the cached prompt, cached tools, dynamic-context hash and warmup state unchanged.

Suggested order

1. Add the lightweight read-only status projection and endpoint.
2. Consume it from the CLI under [Feature Request] CLI de pilotage et interface d'automatisation pour OpenFox #199.
3. Add a small UI representation if useful.
4. Evaluate stall detection from real usage and the acceptance scenarios above.
5. Keep generic hooks, automatic recovery and host telemetry as separate follow-up work.

This would keep the first contribution small, follow the existing REST, EventStore and WebSocket architecture, and establish a reusable status surface for #199 and later observability features.