2c780d3e60
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# Info-Board Neu - Player-Agent Lifecycle und Health-Modell
|
|
|
|
## Ziel
|
|
|
|
Dieses Dokument beschreibt die erste belastbare Laufzeitstufe des `player/agent` fuer v1.
|
|
|
|
Es legt fest, wie der Agent seinen internen Zustand fuehrt, welche strukturierten Log-Ereignisse er ausgibt und wie ein kontrollierter Stop funktioniert.
|
|
|
|
## V1-Entscheidung
|
|
|
|
- der Agent fuehrt zunaechst ein internes Health-Modell ohne externen HTTP-Endpunkt
|
|
- Lifecycle-Wechsel werden ueber einen in-memory Snapshot verfolgt
|
|
- Server-Erreichbarkeit wird getrennt vom Lifecycle als eigener Connectivity-Zustand gefuehrt
|
|
- Logs werden als stabile `key=value`-Ereignisse ausgegeben
|
|
- Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM`
|
|
|
|
## Health-Snapshot
|
|
|
|
Der Laufzeitsnapshot enthaelt mindestens:
|
|
|
|
- `status`
|
|
- `server_connectivity`
|
|
- `screen_id`
|
|
- `server_base_url`
|
|
- `mqtt_broker`
|
|
- `heartbeat_every_seconds`
|
|
- `started_at`
|
|
- `last_heartbeat_at`
|
|
|
|
Der Snapshot dient in v1 der internen Laufzeitbeobachtung und Testsicherheit.
|
|
|
|
## Statusmodell
|
|
|
|
Fuer die aktuelle Ausbaustufe gelten diese Stati:
|
|
|
|
- `starting` vor dem Start der Run-Loop
|
|
- `running` sobald Konfiguration uebernommen und der erste Heartbeat verarbeitet wurde
|
|
- `stopped` nach kontrolliertem Verlassen der Run-Loop
|
|
|
|
Ein separater Fehlerstatus wird in dieser Stufe noch nicht eingefuehrt.
|
|
Technische Startfehler bleiben weiterhin normale Rueckgabefehler beim Initialisieren oder Starten.
|
|
|
|
## Connectivity-Modell
|
|
|
|
Getrennt vom Lifecycle fuehrt der Agent fuer die Server-Erreichbarkeit aktuell diese Zustaende:
|
|
|
|
- `unknown` vor dem ersten erfolgreichen oder fehlgeschlagenen Status-Report
|
|
- `online` nach einem erfolgreich bestaetigten HTTP-Status-Report
|
|
- `degraded` nach einem fehlgeschlagenen HTTP-Status-Report
|
|
|
|
Damit bleibt der Lifecycle sauber von Netz- und Gegenstellenproblemen getrennt.
|
|
Ein Report-Fehler stoppt den Agenten nicht, sondern veraendert nur den Connectivity-Zustand.
|
|
|
|
## Strukturierte Log-Ereignisse
|
|
|
|
Der Agent emittiert in v1 mindestens diese Ereignisse:
|
|
|
|
- `event=agent_starting`
|
|
- `event=agent_configured`
|
|
- `event=heartbeat_tick`
|
|
- `event=status_report_sent`
|
|
- `event=status_report_failed`
|
|
- `event=agent_stopped`
|
|
|
|
Ziel ist keine vollstaendige Logging-Plattform, sondern ein stabiler, maschinenlesbarer Anfang fuer lokale Verifikation, spaetere Journald-Auswertung und Device-Debugging.
|
|
|
|
## Heartbeat-Verhalten
|
|
|
|
- beim Start wird direkt ein erster Heartbeat verarbeitet und geloggt
|
|
- danach laeuft der Heartbeat im konfigurierten Intervall weiter
|
|
- jeder Heartbeat aktualisiert `last_heartbeat_at`
|
|
|
|
Das direkte erste Tick-Verhalten vereinfacht lokale Checks und Tests, weil ein frisch gestarteter Agent sofort einen nachvollziehbaren Lebensnachweis liefert.
|
|
|
|
## Shutdown-Verhalten
|
|
|
|
- `cmd/agent` erstellt einen signalgebundenen Context
|
|
- bei `SIGINT` oder `SIGTERM` verlaesst die Run-Loop kontrolliert den Ticker
|
|
- vor Rueckkehr wird `event=agent_stopped` geloggt und der Snapshot auf `stopped` gesetzt
|
|
|
|
## V1-Abgrenzung
|
|
|
|
Nicht Teil dieser Stufe:
|
|
|
|
- externer Health-Endpunkt
|
|
- MQTT-Verbindungsstatus
|
|
- Snapshot-Persistenz
|
|
- Kommandos oder Sync-Status
|
|
|
|
Die erste Backend-Reachability-Pruefung ist in dieser Stufe bereits ueber den HTTP-Status-Report abgebildet.
|
|
Ein expliziter `offline`-Zustand, MQTT-Reachability und weitergehende Schwellenlogik folgen spaeter.
|
|
|
|
Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird.
|