Add agent endpoint specifications (Phase 1)

Agent_Endpoint_Specifications_Phase1.md

@@ -0,0 +1,158 @@
+# Agent Endpoint Specifications — Phase 1
+
+> Status: ✅ Documented from source
+
+All routes served on `:18888`. Internal only — API is the only caller.
+
+---
+
+## GET /status
+
+Returns the runtime state of the game server managed by the agent.
+
+### Response
+
+```json
+{
+  "state": "running",
+  "processRunning": true,
+  "ready": true,
+  "readySource": "minecraft_ping",
+  "readyError": "",
+  "lastReadyAt": "2026-03-10T18:00:00Z",
+  "installStep": "",
+  "crashCount": 1,
+  "lastCrashTime": "2026-03-10T18:10:22Z",
+  "lastCrashExitCode": 1,
+  "lastCrashSignal": 0,
+  "lastCrashUptimeSeconds": 142,
+  "lastCrashLogTail": [
+    "[Server thread/ERROR]: Failed to start server",
+    "java.lang.OutOfMemoryError"
+  ],
+  "error": null,
+  "config": { "..." : "..." },
+  "timestamp": 1234567890
+}
+```
+
+### Crash Semantics
+
+- `crashCount` increments only on unexpected process exit
+- Intentional stops (via `/stop`) do not increment crash count
+- Readiness failure is reported as `state = error`
+
+---
+
+## POST /config
+
+Provision + start in a single async call. Returns `202 Accepted` immediately.
+
+```json
+{ "ok": true, "state": "installing" }
+```
+
+---
+
+## POST /start
+
+Manual start. Requires config already saved. Not available for `dev` containers.
+
+```json
+{ "ok": true, "state": "starting" }
+```
+
+---
+
+## POST /stop
+
+Stops the server process. Returns `204 No Content`.
+
+---
+
+## POST /restart
+
+Stop → wait for exit (20s) → start → wait for readiness.
+Not available for `dev` containers.
+
+```json
+{ "ok": true, "state": "starting" }
+```
+
+---
+
+## GET /health
+
+Always returns `200 ok`. Used by API poller to check agent liveness.
+
+---
+
+## GET /version
+
+```json
+{ "version": "v1.2.3" }
+```
+
+---
+
+## GET /game/players
+
+Minecraft only. Returns player presence.
+
+```json
+{
+  "online": 3,
+  "max": 20,
+  "players": ["Alice", "Bob", "Carol"]
+}
+```
+
+---
+
+## Mods
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/game/mods` | GET | List installed mods |
+| `/game/mods/install` | POST | Install mod from Modrinth |
+| `/game/mods/{id}` | GET / DELETE / PATCH | Get, delete, or toggle mod |
+
+---
+
+## Files
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/game/files/list?path=<rel>` | GET | List directory (max 200 entries) |
+| `/game/files?path=<rel>` | GET / POST / DELETE | Read, write, or delete a file |
+| `/game/files/stat?path=<rel>` | GET | Stat file — returns `isWritable`, `hasBackup`, `source` |
+| `/game/files/read?path=<rel>` | GET | Read file as string (≤2MB) |
+| `/game/files/download?path=<rel>` | GET | Download file as binary (streamed) |
+| `/game/files/upload?path=<rel>` | POST | Upload file (streamed, allowlist enforced) |
+| `/game/files/revert?path=<rel>` | POST | Restore file from shadow backup |
+
+---
+
+## Console
+
+| Route | Description |
+|-------|-------------|
+| `GET /console/command?cmd=<cmd>` | Send command to server stdin via PTY |
+| `WS /console/ws` | PTY-backed interactive console |
+
+---
+
+## Agent Self-Management
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/agent/update` | POST | Check and apply agent update |
+| `/agent/update/status` | GET | Last update check result |
+
+---
+
+## Metrics
+
+| Route | Description |
+|-------|-------------|
+| `GET /metrics/process` | Agent process metrics (CPU, memory) |