minecraft-ai-god-paper-fork/SESSION.md

# SESSION.md — Minecraft AI God (Paper Fork)

Persistent AI session memory for this project. See `/root/bin/SESSION.md` for the global template and guide.

## Context Files

- `/root/bin/core_homelab.md` — cluster topology, SSH aliases
- `/root/bin/services_directory.md` — active service IPs and domains
- `/root/bin/SESSION.md` — global session memory and patterns
- `./CONTEXT.md` — Minecraft infrastructure, server config, RCON helper
- `./README.md` — Paper fork overview (plugins, build templates, LangGraph gateway)
- Sister repo session memory: `/root/bin/Sethpc-Minecraft/SESSION.md`

---

This document links the two Minecraft AI God projects together, describes their Gitea repos, and serves as the AI session memory for both.

---

## Memory Discipline

- Update `SESSION.md` immediately when a durable fact, decision, or fix is discovered.
- Before every final reply, run a memory check and append any missing durable notes.
- End every reply with one line: `Session memory: updated` or `Session memory: no new durable facts.`

---

## The Two Projects

### Sister repo — minecraft-ai-god (Vanilla)

- **Local path:** `/root/bin/Sethpc-Minecraft`
- **Gitea:** `https://git.sethpc.xyz/Seth/minecraft-ai-god`
- **Purpose:** Vanilla Minecraft 1.21.x, no plugins or mods. All automation via log watching + RCON. Targets the mc1 server (port 25565) and shrink-world server (port 25566) on CT 644.
- **Key services:** `mc-godmode.service`, `mc-shrink-kit.service`, `mc-aigod.service`
- **AI features:** `pray` chat trigger → Ollama LLM → structured JSON → RCON execution; divine intervention timer; shrink-world kit/stats watcher

### This repo — minecraft-ai-god-paper-fork (Paper Advanced Fork)

- **Local path:** `/root/bin/Sethpc-Minecraft-PaperFork`
- **Gitea:** `https://git.sethpc.xyz/Seth/minecraft-ai-god-paper-fork`
- **Purpose:** Dedicated Paper server on port 25567 with plugins (FastAsyncWorldEdit, LuckPerms). Extends the vanilla branch with build templates, expanded command set, sudo translator mode, and LangGraph-style session gateway.
- **Key services:** `mc-paper-ai.service`, `mc-aigod-paper.service`, `mc-langgraph-gateway.service`
- **AI features:** All vanilla features + `sudo build/make/create` deterministic templates, `sudo lookup/wiki/search`, LangGraph gateway sidecar (FastAPI on 127.0.0.1:8091), SQLite session persistence

---

## Relationship Between the Two

This Paper fork is a **direct evolution** of the vanilla repo. They share:

- Same `pray`/`bible`/`sudo` trigger style and chat patterns
- Same two-call LLM split (message + commands JSON schema)
- Same RCON helper (raw socket, no library)
- Same command validation + syntax repair pipeline
- Same intervention timer design (Poisson process, presence guard)

This fork **adds on top of** the vanilla base:

- Plugin-enabled command families (`fill`, `setblock`, `clone`)
- Deterministic build templates before LLM translation
- LangGraph gateway with session memory and tool loop
- `server_type` gating so paper commands don't leak to vanilla targets

Both can run simultaneously — they use separate ports, services, and config files.

---

## Gitea Backup Workflow

Both repos push every committed change to Gitea. This is the standard workflow:

```bash
# From either local repo dir:
git add -A
git commit -m "<description of change>"
git push origin main
```

Both remotes are pre-configured with token auth:

- Vanilla: `https://Seth:<token>@git.sethpc.xyz/Seth/minecraft-ai-god.git`
- Paper fork: `https://Seth:<token>@git.sethpc.xyz/Seth/minecraft-ai-god-paper-fork.git`

The Gitea instance lives at `git.sethpc.xyz` (CT 146, node-173, 192.168.0.125).  
API key: see `GITEA_API.md` in this repo.

**Convention:** commit every meaningful change immediately. Commits are the changelog — no squashing, no batching unrelated changes.

---

## Keeping This File Current

Run `/update-context` in OpenCode at the end of any session to automatically:
1. Review the conversation for new decisions, fixes, and discoveries
2. Append them to `SESSION.md` in both repos
3. Commit and push both repos to Gitea

The command is defined globally at `~/.config/opencode/commands/update-context.md`.

---

## AI Conversation Notes

This section captures decisions and context accumulated across conversations with the AI assistant (OpenCode/Claude). Update it as significant choices are made.

### Architecture decisions

- **No plugins on vanilla servers.** All mc1 and shrink-world automation is pure log-tail + RCON. This keeps the vanilla experience intact and requires no server restarts for updates.
- **Paper fork is separate, not a branch.** Running both as separate services on separate ports was chosen over a single multi-mode script to keep failure domains isolated.
- **LLM backend:** Ollama at `192.168.0.179:11434` for the vanilla service. This fork uses `192.168.0.141:11434` (steel141, local GPU) for better throughput on heavier models (gemma3:12b message model, qwen3-coder:30b command model).
- **Session gateway (this fork only):** The LangGraph-style FastAPI sidecar adds multi-turn memory without requiring a full LangGraph install. Safety enforcement stays in `mc_aigod_paper.py`, not the gateway.
- **Build templates:** Deterministic templates are tried first for `sudo build/make/create` requests. LLM translation is the fallback. This reduces surprises for structure generation tasks.
- **Localized retrieval for sudo reasoning (2026-03-17):** `langgraph_gateway.py` now supports a local knowledge corpus (`/var/lib/mc-langgraph-gateway/knowledge`) with index/search/read tools (`local.search`, `local.read`), optional startup bootstrap from Minecraft/Paper docs URLs, and automatic search->read retrieval hop in sudo tool mode before command generation.
- **Post-deploy behavior check (2026-03-17):** retrieval is active (`tool_trace` shows `local.search` + `local.read`) for `sudo destroy my surroundings`, but generated command remained `execute as <player> run fill ~-5 ~-5 ~-5 ~5 ~5 ~5 air` and produced no useful visible outcome in gameplay (empty/weak RCON feedback). Retrieval alone did not guarantee effective action selection.
- **Sudo execution hardening follow-up (2026-03-17):** added command-shape normalization for sudo (`execute as <player> run ...` -> `execute at <player> run ...`), blocked execute-wrapper bypass in validator (unsafe inner tails like `gameMode` inside `execute ... run`), and added adaptive destructive fallback for failed `destroy/nuke` intents (absolute `fill ... air` around player + TNT summons / TNT kit fallback when position unavailable).
- **Sudo effectiveness feedback loop (2026-03-17):** sudo now scores execution effectiveness from RCON results for all intents, reports translated commands + outcomes + ineffective flag back to gateway session memory (`mode=sudo_feedback`, `feedback_only=true`), and gateway stores this feedback without running extra LLM/tool calls.
- **Lookup contextual memory fix (2026-03-17):** `sudo lookup/search/wiki` now resolves pronoun references (e.g., "that command", "do it again") against the player's most recent executed sudo command, includes that command in lookup context payloads, and passes sudo history into gateway lookup context to improve follow-up reasoning.
- **Gamemode/effect sudo fix (2026-03-17):** Added `gamemode` to safe prefixes/whitelist and command palette, added syntax normalizer for malformed variants (`gameMode s`, short aliases, missing target) and execute-wrapped gamemode forms; confirmed valid RCON forms are `gamemode <mode> <player>` and `effect give <player> <effect> <duration> <amplifier> [hideParticles]`.
- **AI-driven build/template flow (2026-03-17):** `process_sudo` now defaults to non-deterministic build planning (legacy deterministic builder templates disabled unless `sudo_deterministic_build_templates=true`), supports AI-emitted `template ...` meta-commands in sudo execution loop, and includes an AI template planner override for build/make/create prompts when initial translation does not emit template workflow steps.
- **Failed-execution retry pipeline upgrade (2026-03-17):** sudo now runs a generic retry-repair pass on ineffective results before intent fallback. Added TNT-specific repair for malformed `summon tnt ... <count>` outputs (expands into bounded multiple summon commands) and invulnerability-effect repair to valid protection effects. Added `tnt` to destructive-intent keywords so TNT requests can trigger destructive fallback when needed.
- **TNT retry syntax correction (2026-03-17):** retry expansion for malformed TNT count commands initially emitted invalid relative coords with `~+1`/`~+2`; corrected generator to use valid forms (`~1`, `~2`) so repaired TNT summons no longer fail with `Expected double`.
- **User preference (2026-03-17):** prioritize context/prompt refinement and better model grounding over adding more deterministic hardcoded action paths.
- **Context-first refinement pass (2026-03-17):** added sudo failure memory (`sudo_failures`) and anti-repeat context block (`RECENT FAILED SUDO PATTERNS`) into paper sudo translator input and gateway sudo context payload; prompt rules now explicitly forbid repeated failed shapes, old enchant NBT syntax, and `summon tnt ... <count>` style outputs.
- **Prompt safety clarifications (2026-03-17):** updated paper God/system prompts to enforce `effect give ...` syntax, `weather clear|rain|thunder` only, and avoid accidental high vertical teleports in benevolent outputs unless explicitly requested.
- **Sudo scope grounding (2026-03-17):** paper sudo prompts now explicitly keep target scope narrow (`me/my` -> requesting player), discouraging broad `@a` outputs unless explicitly requested.
- **Unresolved post-update issues (2026-03-17):** (1) AI template planner override can trigger on non-build sudo intents (example: `make me invisible` routed into `template search/pick/build`), and (2) sudo follow-up questions like `did that command ...?` may not return an informational answer unless phrased with explicit lookup prefixes.
- **Resolved sudo routing issues (2026-03-17):** tightened build-intent detection so template planner override only triggers for actual structure/template intents (no longer on generic `make me ...` phrasing), and broadened sudo info-mode detection to treat natural question-style prompts (e.g., `did that command ...?`) as lookup queries even without explicit `lookup/search/wiki` prefix.
- **Remaining issues after routing fix deploy (2026-03-17):** (1) sudo still outputs old bow enchant NBT (`bow{Enchantments:[...]}`) in some runs and fails with trailing-data parse error, and (2) God prayer outputs still occasionally include unnecessary teleport actions (`tp ~ ~5 ~`) that users report as unhelpful side effects.
- **Bugfix pass after in-game retest (2026-03-17):** added command-repair normalizers for (a) old bow enchant NBT to 1.21 component syntax (`minecraft:bow[enchantments={...}]`), and (b) legacy fire fill syntax (`... fire 0 replace air` -> `... minecraft:fire replace air`), plus dynamic sudo command budget scaling for TNT prompts based on requested quantity (capped by `sudo_tnt_max_commands`, default 80).
- **Lookup and benevolent TP context refinements (2026-03-17):** lookup mode now has local fallback answering for contextual gameplay questions (e.g., invisibility vs mobs) when retrieval returns no hits, and prompts/gateway guidance now explicitly discourage teleport use in helpful responses unless movement is explicitly requested.
- **Post-retest fixes (2026-03-17):** added execute-tail syntax repair so command fixers apply inside `execute ... run ...` payloads (fixes old bow NBT + fill fire variants emitted under execute wrappers), and added TNT quantity expansion from prompt count for summon-heavy intents (bounded by `sudo_tnt_max_commands`, default 80) when model output under-produces summons.
- **Retest outcome (2026-03-17 late):** bow repair now works in live runs (`give strongest bow` successfully converted old NBT to `minecraft:bow[enchantments={...}]` and delivered item). Remaining issues: fire-spread requests still often execute as no-op/invalid hybrid fill chains (`execute ... run fill ... fire ...` with mixed legacy args), and TNT intent can still collapse into single-command failure then destructive fallback (large `fill ... air` + few TNT) instead of honoring requested count semantics.
- **Late-night retest results (2026-03-18):** strongest-bow path is confirmed fixed; lookup follow-up (`did that command do what I asked?`) still intermittently returns no result; fire-spread prompt still no-ops/invalid despite syntax repair; TNT quantity prompts (`spawn 80/20 tnt`) still execute a single summon in some runs, indicating quantity expansion is not consistently applied before execution.
- **Follow-up fixes after late-night retest (2026-03-18):** added per-player `last_sudo_feedback` memory and deterministic lookup fallback answer for `did that command do what I asked?`; expanded execute-tail repair coverage and fire fill metadata repair (`... fire 0 replace <block>`); disabled destructive air-fill fallback for TNT intents; added fire-intent fallback retry and robust TNT expansion by parsing summon tail from nested execute wrappers.
- **Project governance for bug intake (2026-03-17):** `bug_log` reports from all players are useful advisory input, but direction/prioritization authority remains with project owner (`slingshooter08`); non-owner reports should be weighted accordingly.
- **God voice update (2026-03-17):** Increased default God persona emphasis on irony, dark humor, and sarcastic one-liners in both command and message system prompts (vanilla + Paper variants) while keeping command strictness unchanged.
- **Bug-log triage (2026-03-17):** `bug_log` entry confirmed an unintended-feeling movement reward in prayer flow (`execute as slingshooter08 run tp slingshooter08 ~ ~10 ~`) during a build-oriented prayer; prioritize pray-path teleport safety guards and intent alignment.
- **Bug follow-up (2026-03-17):** second `bug_log` entry reported God feeling "too nice" after greedy follow-up prayer; prompt context updated to bias repeated greedy demands toward corrective responses (rebuke/debuff/symbolic punishment) instead of extra rewards.
- **Teleport safety guard (2026-03-17):** added execution-time TP safety wrapper in prayer/intervention path (`execute_response`) to auto-apply `slow_falling` + `resistance` before risky upward teleports, reducing accidental player death from unintended high drops.
- **Bug-log signal upgrade (2026-03-17):** `bug_log` now writes filtered raw server log lines (RCON thread noise removed) and includes recent AI action lines from `/var/log/mc_aigod_paper.log` for better root-cause visibility.
- **Unaddressed bug triage (2026-03-17):** third `bug_log` entry ("output not in correct format") maps to prayer execution using invalid command `weather storm` (RCON: Incorrect argument). Current validator allows `weather` prefix but lacks argument normalization (`storm` -> `rain`) and no retry/repair pass for pray-path commands.
- **Weather normalization fix (2026-03-17):** added explicit prompt/context rule and code normalizer mapping `weather storm|rainstorm|thunderstorm` -> `weather thunder` before validation/execution (paper + vanilla), then redeployed both services.
- **New bug cluster observed (2026-03-17):** additional paper `bug_log` entries report failed command outcomes around selector-based targets and legacy enchant syntax in sudo (`minecraft:bow{Enchantments:...}`), indicating retry/repair still needed for 1.21 enchantment conversion and selector reliability feedback.

### Infrastructure decisions

- **mc1 autoStart:** Set to `true` in MCSManager instance config (`/opt/mcsmanager/daemon/data/InstanceConfig/d39f55861cb34204a92a18a9e1c78ca6.json`) so the server starts on CT 644 boot. `mc-godmode.service` uses `tail -F` and handles the log appearing late gracefully.
- **mc-godmode.service startup:** Already enabled (`systemctl is-enabled` = enabled), `WantedBy=multi-user.target`, `After=mcsm-daemon.service`. The service was not failing — the MC server itself wasn't auto-starting (fixed by enabling autoStart in MCSManager config).
- **Paper server location:** `/opt/paper-ai-25567/` on CT 644. Separate from MCSManager-managed instances.

### Open threads / next ideas

- Prayer history log (JSON) for review and tuning
- God mood / divine disposition score persisted across restarts
- Redis backend for gateway sessions (currently SQLite only)
- MCP-based tool adapters in the gateway tool loop
- Richer LangGraph state machine planner node (currently lightweight heuristic router)
- Optional tool trace exposure in-game debug mode
- Web dashboard for recent prayers + God responses (n8n or simple Flask)
- Stricter command schema output at the model/gateway side