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.

docs/PANEL_INTEGRATION.md

@@ -0,0 +1,19 @@
+# GSP Linux Agent Panel Integration
+
+Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
+
+The Panel is authoritative. The Linux agent executes the work the Panel requests.
+
+## Legacy Workshop RPC
+
+The dedicated Panel `steam_workshop` module still uses the legacy `steam_workshop` XML-RPC call.
+
+Current compatibility rule:
+
+- if the Panel sends a blank `config_file_path`, the Linux agent runs post-install logic only
+- the generated script must skip all `cat` / regex / config-write logic in that case
+- `WorkshopModsInfo` is still written so the Panel can list/uninstall installed items even when no game config file is edited
+- new installs write per-home records under `WorkshopModsInfo/home_<home_id>/`
+- each record stores mod string, Workshop item ID, title, installed folder/path, Workshop App ID, install status, and timestamps
+- the generated job writes `<game_home>/WorkshopInstallStatus.json` as `running`, `completed`, or `failed`
+- the generated job prints `GSP_WORKSHOP_INSTALL_COMPLETE` or `GSP_WORKSHOP_INSTALL_FAILED` so the Panel can avoid stale `Update in progress` displays if the generic update screen lingers