logfin expand

docs/AGENT_ACTIVITY_EVENTS.md

@@ -0,0 +1,52 @@
+# Windows Agent Activity Events
+
+The Windows/Cygwin 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 `OGP64/OGP/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 Windows 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 Cygwin/Windows PID metadata
+- Windows 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 Windows 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

@@ -15,6 +15,20 @@ The Panel is authoritative. The Windows agent executes the work the Panel reques
 
 The Windows agent should mirror the Linux agent behaviorally as much as possible so the Panel can treat both platforms as one product family.
 
+## 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 Windows 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
+
 ## Status validation
 
 The Panel remains the source of truth for assigned ports. The Windows agent validates only the ports supplied by the Panel for a specific server.