From 45fb9b2bf4f982ae98e7effda0a41a4b96320768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesko=20Ansch=C3=BCtz?= Date: Sun, 22 Mar 2026 16:55:29 +0100 Subject: [PATCH] Dokumentiere Agent-Lifecycle fuer v1 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- docs/PLAYER-AGENT-LIFECYCLE.md | 76 ++++++++++++++++++++++++++++++++++ player/agent/README.md | 4 +- 2 files changed, 79 insertions(+), 1 deletion(-) create mode 100644 docs/PLAYER-AGENT-LIFECYCLE.md diff --git a/docs/PLAYER-AGENT-LIFECYCLE.md b/docs/PLAYER-AGENT-LIFECYCLE.md new file mode 100644 index 0000000..fb5d52b --- /dev/null +++ b/docs/PLAYER-AGENT-LIFECYCLE.md @@ -0,0 +1,76 @@ +# 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 +- Logs werden als stabile `key=value`-Ereignisse ausgegeben +- Stop erfolgt signalgesteuert ueber `SIGINT` oder `SIGTERM` + +## Health-Snapshot + +Der Laufzeitsnapshot enthaelt mindestens: + +- `status` +- `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. + +## Strukturierte Log-Ereignisse + +Der Agent emittiert in v1 mindestens diese Ereignisse: + +- `event=agent_starting` +- `event=agent_configured` +- `event=heartbeat_tick` +- `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 +- Backend-Reachability-Pruefung +- Snapshot-Persistenz +- Kommandos oder Sync-Status + +Diese Punkte folgen erst, wenn echte Netzwerk- und Sync-Funktionalitaet eingebaut wird. diff --git a/player/agent/README.md b/player/agent/README.md index 55b8d17..fa4092b 100644 --- a/player/agent/README.md +++ b/player/agent/README.md @@ -18,4 +18,6 @@ Geplante Unterstruktur: Aktuell vorhanden: - Env-basierte und dateibasierte Konfiguration -- einfacher Laufzeit-Loop mit Heartbeat-Ticks im Log +- strukturierte Start-/Heartbeat-/Stop-Logs +- interner Health-Snapshot fuer Laufzeitzustand und Timestamps +- signalgesteuerter Stop ueber `SIGINT` und `SIGTERM`