logfin expand

docs/AGENT_ACTIVITY_EVENTS.md

@@ -0,0 +1,52 @@
+# Linux Agent Activity Events
+
+The Linux agent can report meaningful server lifecycle events to the GSP Panel activity log. It does not send routine XML-RPC chatter, file reads, status polls with no state change, or every local agent log line.
+
+## Configuration
+
+Set these values in `Cfg/Config.pm`:
+
+```perl
+agent_event_url => 'https://panel.example.com/agent_event_receiver.php',
+remote_server_id => '1',
+```
+
+If `agent_event_url` is empty, the agent attempts to derive it from `web_api_url`. The `key` value must match the Panel remote server encryption key because it is used to sign event payloads.
+
+## Authentication
+
+Events are JSON POST requests signed with HMAC-SHA256:
+
+- `X-GSP-Agent-Id`: Panel `remote_server_id`
+- `X-GSP-Agent-Timestamp`: Unix timestamp
+- `X-GSP-Agent-Signature`: `sha256=` plus HMAC of `timestamp.body`
+
+The Panel validates the signature, remote server identity, event type, severity, and `home_id` ownership before writing the activity log.
+
+## Offline Queue
+
+If the Panel is unavailable, the Linux agent appends events to:
+
+```text
+events/pending-events.jsonl
+```
+
+The queue is retried after later successful event deliveries and rotates when it exceeds 1 MB. Server start, stop, and restart operations do not wait on Panel event delivery.
+
+## Lifecycle Detection
+
+The agent uses existing runtime evidence:
+
+- screen/session status
+- tracked PID metadata
+- process existence
+- required game/query/RCON port validation
+- short-lived status hints such as `STARTING`, `STOPPING`, and `STOPPED`
+
+It does not create or read `SERVER_STOPPED` marker files.
+
+## Reported Events
+
+The Linux agent reports confirmed start and stop outcomes, unresponsive process states, missing/restored port transitions, unexpected `ONLINE -> OFFLINE` transitions, and scheduled restart sequences when the scheduler invokes restart actions.
+
+External kills, including a companion bot terminating a server process, are recorded after status polling observes the validated state change.