feat(agent): Phase 1 — chat-window AI assistant via Claude Code subprocess
Adds an in-dashboard AI assistant that answers questions about live game
state. Designed reactively (no background loops) — every user message in
the chat window or via /api/agent/ask runs one `claude -p` invocation.
Architecture:
- New host-side FastAPI service (agent/) on 127.0.0.1:8767, OUTSIDE the
dereth-tracker Docker container because `claude` and ~/.claude
credentials live on the host.
- nginx routes /api/agent/* to the host service.
- The same browser session cookie the tracker issues authenticates
agent requests (shared SECRET_KEY).
- The agent shells out to `claude -p --session-id <uuid>` with
cwd=/home/erik/MosswartOverlord. Sessions persist as JSONL on disk
via Claude Code's built-in machinery.
- An MCP stdio server (agent/mcp_overlord.py) exposes tools to Claude:
get_live_players, get_recent_rares, query_telemetry_db (read-only,
parsed by sqlglot to reject DML/DDL), get_player_state, get_inventory,
get_inventory_search, get_combat_stats, get_equipment_cantrips,
get_quest_status, get_server_health, suitbuilder_search.
- Read-only PG role (overlord_agent_ro) is the second line of defense
on the SQL tool — even a parser bypass can't mutate.
Frontend:
- AgentWindow.tsx — draggable chat window with localStorage-pinned
session UUID, "New Chat" button, on-mount rehydration from
/agent/sessions/{id}/history (parses Claude Code's JSONL).
- Wired into WindowRenderer + Sidebar (🤖 Assistant button).
Operational:
- systemd unit (overlord-agent.service) + install.sh.
- agent/README.md documents env vars, deploy flow, smoke tests.
- nginx/overlord.conf gets a new /api/agent/ location with 180s timeout.
- CLAUDE.md gets an "Overlord Assistant Mode" section briefing the
agent on which tools to use and how to behave.
NOT YET DEPLOYED — server still needs:
1. Apply agent/sql/0001_overlord_agent_ro.sql + ALTER ROLE password
2. Add AGENT_DB_DSN to /home/erik/MosswartOverlord/.env
3. bash agent/install.sh (creates venv, installs unit, starts service)
4. sudo cp /home/erik/MosswartOverlord/nginx/overlord.conf to nginx + reload
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
aeddaf9925
commit
79cf88d3f7
35 changed files with 1763 additions and 25 deletions
38
CLAUDE.md
38
CLAUDE.md
|
|
@ -137,4 +137,40 @@ Real-time equipment optimization engine for building optimal character loadouts
|
|||
|
||||
### WebSocket Endpoints
|
||||
- `/ws/position`: Plugin telemetry, inventory, portal, rare events (authenticated)
|
||||
- `/ws/live`: Browser client commands and live updates (unauthenticated)
|
||||
- `/ws/live`: Browser client commands and live updates (unauthenticated)
|
||||
|
||||
---
|
||||
|
||||
## Overlord Assistant Mode
|
||||
|
||||
When invoked through the dashboard's chat window (the **🤖 Assistant** button) or through `/api/agent/ask`, you are acting as the **Overlord Assistant** — answering ad-hoc questions for the user about their live multi-account Asheron's Call setup.
|
||||
|
||||
**You have MCP tools** (from `.mcp.json`) for live game data. **Always use them** instead of guessing or apologising for not having data:
|
||||
|
||||
- `get_live_players` — current online characters with positions/kills/state
|
||||
- `get_recent_rares` — rare item finds in the last N hours
|
||||
- `query_telemetry_db` — read-only SQL on the telemetry DB for ad-hoc analysis
|
||||
- (more tools added over time — call `list_tools` if unsure)
|
||||
|
||||
### Behaviour rules
|
||||
|
||||
1. **Use tools, don't speculate.** If the user asks "how many chars are online" — call `get_live_players`. Don't say "I'd need to check" — just check.
|
||||
2. **Be concise.** The user is glancing at a chat window, not reading a report. 2-5 sentences for most answers. Use markdown tables for tabular data.
|
||||
3. **No code unless asked.** This mode is about *operating* the system, not editing it. Don't open files or write code unless the user explicitly asks.
|
||||
4. **Real numbers, real names.** Cite actual character names and counts from tools — never make up sample data.
|
||||
5. **Read-only.** You cannot mutate the database; the SQL tool will reject any non-SELECT statement and the role is also `GRANT SELECT` only. If a question requires a write, say so.
|
||||
6. **Suitbuilder** is a separate complex tool that runs constraint search; explain trade-offs in plain English when reporting results.
|
||||
7. **Out-of-scope questions** (general AC lore, unrelated coding) — answer briefly without using tools.
|
||||
|
||||
### Available data tables (for `query_telemetry_db`)
|
||||
|
||||
- `telemetry_events` (hypertable, 30-day retention) — position/state snapshots every ~2s per character
|
||||
- `rare_events` — rare item find log
|
||||
- `spawn_events` (hypertable, 7-day retention) — monster spawn observations
|
||||
- `portals` — discovered portal coords (1h dedup window)
|
||||
- `char_stats`, `rare_stats`, `rare_stats_sessions` — lifetime/session aggregates
|
||||
- `character_stats` — latest full stats JSON per character
|
||||
- `combat_stats`, `combat_stats_sessions` — combat tracking
|
||||
- `server_status` — current Coldeve game-server state (single row)
|
||||
|
||||
If asked about something not covered above, look in `db_async.py` for the schema or just try a query and report what you see.
|
||||
Loading…
Add table
Add a link
Reference in a new issue