diff --git a/Agent_Endpoint_Specifications_Phase1.md b/Agent_Endpoint_Specifications_Phase1.md deleted file mode 100644 index c06eaa9..0000000 --- a/Agent_Endpoint_Specifications_Phase1.md +++ /dev/null @@ -1,158 +0,0 @@ -# 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=` | GET | List directory (max 200 entries) | -| `/game/files?path=` | GET / POST / DELETE | Read, write, or delete a file | -| `/game/files/stat?path=` | GET | Stat file — returns `isWritable`, `hasBackup`, `source` | -| `/game/files/read?path=` | GET | Read file as string (≤2MB) | -| `/game/files/download?path=` | GET | Download file as binary (streamed) | -| `/game/files/upload?path=` | POST | Upload file (streamed, allowlist enforced) | -| `/game/files/revert?path=` | POST | Restore file from shadow backup | - ---- - -## Console - -| Route | Description | -|-------|-------------| -| `GET /console/command?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) |