diff --git a/README.md b/README.md index 89249aa9..0864e4d0 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ all driven by WebSocket events from the companion [MosswartMassacre](https://git - [WebSocket Contract](#websocket-contract) - [HTTP API Reference](#http-api-reference) - [Frontend](#frontend) +- [AI Assistant (Overlord Agent)](#ai-assistant-overlord-agent) - [Database Schema](#database-schema) - [Operations & Health](#operations--health) - [Contributing](#contributing) @@ -38,7 +39,7 @@ The frontend is a React + Vite app served at `/` with a live map, draggable wind │ WebSocket /ws/position (authenticated) ▼ ┌────────────────────────────────────────────────────────┐ -│ dereth-tracker (FastAPI) │ +│ dereth-tracker (FastAPI, Docker) │ │ • main.py — WS routing, analytics, broadcasts │ │ • idle/death detection → Discord webhook │ │ • combat stats delta/lifetime accumulation │ @@ -49,18 +50,29 @@ The frontend is a React + Vite app served at `/` with a live map, draggable wind ▼ ▼ ▼ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Browsers │ │ inventory-svc │ │ Discord bot │ -│ (React) │ │ (FastAPI) │ │ (rare monitor) │ -└──────────┘ └────────┬─────────┘ └──────────────────┘ - ▼ - ┌──────────────┐ - │ inventory-db │ - └──────────────┘ +│ (React) │ │ (FastAPI, Docker)│ │ (rare monitor) │ +└────┬─────┘ └────────┬─────────┘ └──────────────────┘ + │ ▼ + │ ┌──────────────┐ + │ │ inventory-db │ + │ └──────────────┘ + │ + │ /api/agent/* (host-side, OUTSIDE Docker) + ▼ +┌────────────────────────────────────────┐ +│ overlord-agent (FastAPI, systemd) │ ← runs as dedicated unprivileged user +│ • shells out to `claude -p ...` │ /var/lib/overlord-agent home, +│ • MCP server: live-state Q&A tools │ strict settings, no /home/erik +└────────────────────────────────────────┘ + ┌──────────────┐ │ dereth-db │ ← TimescaleDB (telemetry, spawns, rares, portals) └──────────────┘ ``` -All services run via Docker Compose. +Most services run via Docker Compose. **`overlord-agent` is host-side** +(systemd) because it shells out to the `claude` CLI which depends on +host-side credentials — see [AI Assistant](#ai-assistant-overlord-agent). ## Features @@ -86,6 +98,12 @@ All services run via Docker Compose. - Plugin broadcasts its own vitals and consumes peer vitals - In-game `DxHud` overlay shows peer health/stamina/mana bars with direction arrows +### AI Assistant +- 🤖 chat window in the dashboard backed by `claude -p` running headless on the server +- Read-only access to live game state via 12 MCP tools (live players, inventory cross-search, combat stats, quests, suitbuilder, read-only SQL, etc.) +- Per-browser persistent session, "New Chat" button, history rehydration on reload +- Hardened: dedicated unprivileged Linux user, systemd lockdown, strict tool whitelist, audit log, rate limit. See [AI Assistant section](#ai-assistant-overlord-agent) for the full security stack. + ### Discord Integration - **Rare Monitor Bot** — posts rares (split by common/great) to configured channels - **Death Alerts** — webhook to `#alerts` when a character's vitae goes from 0 → >0 (rate-limited to one per character per 5 min) @@ -149,6 +167,18 @@ All secrets go in `.env`: | `ACLOG_CHANNEL_ID` | Discord channel ID for the rare bot's status/vortex messages | | `MONITOR_CHARACTER` | Which character's chat the bot monitors | +The Overlord Agent has its own env file at `/etc/overlord/agent.env` (root:overlord-agent 0640) so it doesn't share the tracker's secrets: + +| Variable | Purpose | +|---|---| +| `SECRET_KEY` | Same value as the tracker — validates browser session cookies | +| `AGENT_DB_DSN` | Read-only connection string `postgresql://overlord_agent_ro:@127.0.0.1:5432/dereth` | +| `TRACKER_URL` | Loopback to the tracker container (default `http://127.0.0.1:8765`) | +| `AGENT_RATE_MAX` | Per-user rate limit (default 60/hour) | +| `AGENT_RATE_WINDOW_S` | Rate-limit window in seconds (default 3600) | +| `AGENT_AUDIT_LOG` | Path to audit JSONL (default `/var/log/overlord-agent/audit.jsonl`) | +| `CLAUDE_TIMEOUT_S` | Max seconds per `claude -p` invocation (default 240) | + ## Deploying Changes Live backend host: `overlord.snakedesert.se` (SSH user `erik`, key-based auth). @@ -187,6 +217,34 @@ ssh erik@overlord.snakedesert.se "cd /home/erik/MosswartOverlord && \ `BUILD_VERSION` is displayed in the sidebar of the live frontend. Format is CalVer: `YYYY.M.D.HHMM-gitshorthash`. +### Overlord Agent deploy + +Code changes to `agent/` only: +```bash +ssh erik@overlord.snakedesert.se "cd /home/erik/MosswartOverlord && \ + git pull --ff-only origin master && \ + sudo systemctl restart overlord-agent" +journalctl -u overlord-agent -f # tail logs to verify +``` + +`agent/requirements.txt` changed (new pip deps): +```bash +ssh erik@overlord.snakedesert.se "cd /home/erik/MosswartOverlord && \ + git pull --ff-only origin master && \ + agent/.venv/bin/pip install -r agent/requirements.txt && \ + sudo systemctl restart overlord-agent" +``` + +systemd unit changed: +```bash +ssh erik@overlord.snakedesert.se "cd /home/erik/MosswartOverlord && \ + git pull --ff-only origin master && \ + sudo cp agent/overlord-agent.service /etc/systemd/system/ && \ + sudo systemctl daemon-reload && sudo systemctl restart overlord-agent" +``` + +First-time install: `bash agent/install.sh` — see `agent/README.md` for the full bootstrap procedure (creating the `overlord-agent` user, copying claude auth, granting filesystem access, populating `/etc/overlord/agent.env`). + ## WebSocket Contract ### `/ws/position` (plugin → backend) @@ -253,6 +311,53 @@ See `EVENT_FORMATS.json` for event schemas. Major HTTP endpoints: ### Classic v1 (preserved at `/classic`) The original vanilla JS frontend with element-pooling optimization is kept for fallback and reference. +## AI Assistant (Overlord Agent) + +A draggable chat window in the dashboard (🤖 Assistant button). Powered by `claude -p` running headless on the server, with read-only access to live game state via an MCP server. + +### Architecture +- **Host-side service** (`agent/`, systemd unit `overlord-agent`) runs OUTSIDE Docker because the `claude` CLI binary lives on the host (`/home/erik/.local/bin/claude`) and depends on host-side authentication credentials. +- **Dedicated UNIX user** (`overlord-agent`, system account, `/var/lib/overlord-agent` home, no shell) — kernel-level isolation from the operator's `erik` account. Cannot read `/home/erik/.claude`, `~/.ssh`, `.bash_history`, `.env`, etc. +- **MCP stdio server** (`agent/mcp_overlord.py`) exposes 12 tools that wrap the tracker's HTTP endpoints + read-only DB queries. Claude only sees these tools; no `Bash`, `Read`, `Write`, etc. +- **Frontend** (`AgentWindow.tsx`) — per-browser session UUID in localStorage, "New Chat" button, on-mount rehydration from `/agent/sessions/{id}/history`. + +### MCP tools available to the assistant +`get_live_players`, `get_player_state`, `get_combat_stats`, `get_equipment_cantrips`, `get_inventory`, `get_inventory_search`, `search_items` (cross-character), `get_recent_rares`, `get_quest_status`, `get_server_health`, `query_telemetry_db` (read-only SQL via sqlglot parser + GRANT-SELECT-only PG role), `suitbuilder_search`. Plus `WebFetch(domain:acpedia.org)` for AC info lookups. + +### Security stack (defense-in-depth) +1. **Cookie auth** on `/agent/ask` (same session cookie the tracker issues) +2. **Per-user rate limit** (60 req/h default) and **concurrency cap** (1 in-flight) +3. **JSONL audit log** at `/var/log/overlord-agent/audit.jsonl` (every prompt + result) +4. **CLI flags** — `--allowed-tools` (just our 12 MCP tools), `--disallowed-tools` (Bash, Write, Read, Edit, Agent, ToolSearch, Monitor, scheduling, Gmail/Drive/Calendar, etc.), `--permission-mode dontAsk` +5. **`/var/lib/overlord-agent/.claude/settings.json`** — strict deny rules (server-side only, NOT in repo) +6. **System-prompt scope rules** in `CLAUDE.md` — instruct the model not to probe, not to suggest workarounds +7. **SQL parser** (`sqlglot`) rejects any non-SELECT statement on `query_telemetry_db` +8. **Read-only PG role** `overlord_agent_ro` (GRANT SELECT only) — even a parser bypass can't mutate +9. **systemd hardening** — `ProtectSystem=strict`, `ProtectHome=read-only`, `InaccessiblePaths=/etc/shadow,/root,~/.ssh,…`, `NoNewPrivileges=true`, `CapabilityBoundingSet=` (empty), `PrivateTmp=true`, `PrivateDevices=true`, `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6`, `SystemCallFilter=@system-service ~@privileged ~@reboot ~@mount`, `MemoryMax=512M`, `TasksMax=128` +10. **Secrets out of /home** — `/etc/overlord/agent.env` (root:overlord-agent 0640) for SECRET_KEY + AGENT_DB_DSN + +### Files + +| Path | What | +|------|------| +| `agent/service.py` | FastAPI app: `/agent/health`, `/agent/sessions/new`, `/agent/ask`, `/agent/sessions/{id}/history` | +| `agent/auth.py` | Session cookie validation (mirrors `main.py:1013-1019`) | +| `agent/claude_wrapper.py` | `asyncio.create_subprocess_exec("claude", "-p", …)` with allowed/disallowed-tools | +| `agent/tools.py` | Pure tool implementations | +| `agent/mcp_overlord.py` | MCP stdio server registering tools | +| `agent/sql/0001_overlord_agent_ro.sql` | Read-only PG role | +| `agent/overlord-agent.service` | systemd unit (the hardening directives) | +| `agent/install.sh` | venv + systemd setup | +| `agent/README.md` | Operator's deeper reference | +| `.mcp.json` (repo root) | Project-level MCP config Claude Code auto-loads | +| `CLAUDE.md` "Overlord Assistant Mode" section | System-prompt briefing | + +### Routing +nginx forwards `/api/agent/*` to `127.0.0.1:8767` (the host-side service) with a 300s read/send timeout (suitbuilder runs can be slow). Other `/api/*` continues to the dereth-tracker container at `127.0.0.1:8765`. + +### Cost / quota +Subscription auth (no API key); per-call cost is informational only. Each `/agent/ask` invocation = one `claude -p` subprocess with shared session cache. Reactive only — no background polling, no scheduled tasks. + ## Database Schema ### Telemetry DB (`dereth`, TimescaleDB)