Add LangGraph gateway, template manager, teleport border guard, enchantment context, server_type prep, session persistence

2026-03-16 19:28:52 -04:00
parent 08e8f067ad
commit b7451e3290
7 changed files with 2034 additions and 38 deletions
@@ -0,0 +1,140 @@
+# LangGraph Gateway - Implemented MVP (Paper Fork)
+
+## Status
+
+Implemented in this fork as a FastAPI sidecar:
+
+- Script: `/usr/local/bin/langgraph_gateway.py`
+- Service: `mc-langgraph-gateway.service`
+- Config: `/etc/mc_langgraph_gateway.json`
+- Bind: `127.0.0.1:8091`
+
+`mc_aigod_paper.py` can route pray/sudo/system flows through this gateway when:
+
+```json
+"use_langgraph_gateway": true
+```
+
+Safety enforcement remains in `mc_aigod_paper.py` (whitelist, fixups, caps, auth checks).
+
+---
+
+## Implemented API
+
+### Start session
+`POST /v1/session/start`
+
+Request:
+```json
+{
+  "player": "slingshooter08",
+  "mode": "god"
+}
+```
+
+Response:
+```json
+{
+  "session_id": "sess_xxxxx"
+}
+```
+
+### Send message
+`POST /v1/session/{session_id}/message`
+
+Request:
+```json
+{
+  "role": "user",
+  "text": "pray I need wood for shelter",
+  "context": {"server_state": {}, "player_state": "...", "recent_events": "..."},
+  "allow_tools": true,
+  "max_tool_steps": 4
+}
+```
+
+Response:
+```json
+{
+  "message": "Divine response text",
+  "commands": ["give slingshooter08 minecraft:oak_log 64"],
+  "tool_trace": [{"tool": "minecraft.wiki_lookup", "ok": true, "results_count": 2}]
+}
+```
+
+### Close session
+`POST /v1/session/{session_id}/close`
+
+### Health
+`GET /healthz`
+
+---
+
+## Session + Memory Model
+
+- In-memory sessions keyed by `session_id`
+- `mc_aigod_paper.py` keeps player+mode -> session_id mapping
+- `/v1/session/start` reuses active session for same player+mode when possible
+- Session TTL configurable (`session_ttl_seconds`, default 6h)
+- Last message turns are fed back into gateway model calls
+- SQLite persistence enabled by default via `session_db_path` (survives gateway restarts)
+
+Redis backend is not implemented yet (optional future step).
+
+---
+
+## Modes Wired
+
+- `god` -> prayer flow
+- `sudo` -> translator flow
+- `god_system` -> interventions and first-login system events
+
+---
+
+## Tool Loop (MVP)
+
+Bounded tool loop implemented with max step cap:
+
+- `minecraft.wiki_lookup`
+- `web.search`
+
+Current planner is lightweight heuristic router; this is intentionally bounded and conservative.
+
+---
+
+## Runtime Safeguards (still in mc_aigod_paper.py)
+
+Even with gateway enabled, commands are still post-processed by runtime safety:
+
+- command family whitelist
+- syntax repair + normalization
+- max commands cap
+- sudo user authorization
+- first-login constraints (e.g. max one player kill)
+
+So gateway/model/tool errors cannot directly bypass execution constraints.
+
+Gateway also applies an early command sanitation pass before returning output:
+
+- strips leading `/`
+- drops prose/non-command payloads
+- enforces mode-specific command prefixes
+- deduplicates and caps command count
+
+---
+
+## Known Current Behavior
+
+- Session state survives gateway restarts when SQLite persistence is enabled.
+- Tool traces are logged in `mc_aigod_paper.log` but not shown in-game.
+- Redis persistence backend is not implemented yet.
+
+---
+
+## Next Steps
+
+1. Add optional Redis persistence backend
+2. Add richer tool planner node (LangGraph proper state machine)
+3. Add optional tool trace exposure in debug mode
+4. Add stricter command schema output in gateway (model-side)
+5. Add MCP-based tool adapters