Add self-hosted AI worker bootstrap

2026-05-24 03:44:23 +00:00
parent 6d7cc534c4
commit a7c50f651a
6 changed files with 276 additions and 0 deletions
@@ -0,0 +1,53 @@
 # Local AI Agent Guardrails
 These rules apply to any self-hosted AI coding assistant working on Agrarian.
 ## Mandatory Behavior
 - Inspect existing project patterns before proposing changes.
 - Classify every task as `low`, `medium`, or `high` risk.
 - State evidence checked: files, docs, commands, logs, and build results.
 - Make the smallest useful change.
 - Do not refactor unrelated code.
 - Do not invent APIs or project conventions.
 - Do not merge directly to `main`.
 - Do not store secrets, private keys, wallet keys, passwords, or tokens in the
  repo.
 - Passing tests/builds matter more than finishing the task.
 ## Stop And Escalate
 Stop local work and prepare a Codex handoff when any of these are true:
 - confidence is below `0.65`,
 - tests fail twice,
 - build fails twice,
 - Unreal compile errors persist after one focused fix,
 - the task touches security, auth, payments, AGR wallet integration, save/load,
  multiplayer, marketplace logic, migrations, or core engine architecture,
 - the diff touches more files than the brief allows,
 - local model context is overloaded,
 - the model cannot point to evidence for its recommendation.
 ## Required Handoff Format
 ```text
 Project:
 Branch:
 Goal:
 Risk:
 Confidence:
 Files inspected:
 Files changed:
 Commands run:
 Errors:
 What local AI tried:
 Why local AI stopped:
 Requested Codex action:
 ```
 ## Quality Bar
 Local AI is useful only when it is disciplined. It should be allowed to be
 uncertain, but it should not be allowed to be vague, overconfident, or
 unverified.
@@ -0,0 +1,74 @@
 # Agrarian Self-Hosted AI Development Stack
 This stack is meant to reduce pressure on Codex over time, not replace it
 immediately. The first production target is supervised local assistance:
 repository awareness, documentation, small safe edits, tests/builds, and clear
 Codex escalation when local tooling is over its head.
 ## Current Services
 - Gitea:
  `http://192.168.5.21:3000/nathan/agrarian-game.git`
 - Ollama:
  `http://192.168.5.23:11434`
 - Open WebUI:
  `http://192.168.5.26:8085`
 - Local AI worker VM:
  `LinaAI / 192.168.5.27`
 - Primary Unreal/Linux development VM:
  `unreal-engine / 192.168.5.20`
 ## Current Local Model
 - `qwen2.5-coder:7b`
 - Role:
  repo summaries, documentation, small patch suggestions, test generation,
  straightforward scripts, and structured handoff preparation.
 - Not the role:
  broad Unreal architecture changes, risky save/multiplayer/economy rewrites,
  security-sensitive code, or autonomous merges.
 ## Operating Model
 1. Local AI gathers context and proposes small changes.
 2. Work happens on a branch, not directly on `main`.
 3. The agent reports risk, files inspected, commands run, and confidence.
 4. Tests/builds decide whether a change is acceptable.
 5. After two failed local attempts, stop and escalate.
 6. Codex escalation uses the npm Codex CLI, not the API.
 7. Human review controls merges.
 ## Codex Escalation
 Use `Scripts/ai_codex_escalate.sh` with a completed task status file. The
 script prefers a locally installed `codex` command and falls back to
 `npx -y @openai/codex exec`.
 Codex should be called for:
 - confidence below `0.65`,
 - two failed build/test attempts,
 - Unreal compile errors that persist,
 - tasks touching save systems, multiplayer, auth, payments, AGR wallet
  integration, marketplace logic, migrations, or core architecture,
 - patches that grow beyond the intended small scope,
 - contradictions between local model output and official/project docs.
 ## VM Boundaries
 - `LinaAI` owns local AI coding tools, Aider, Codex CLI escalation wrappers,
  repo indexing, documentation generation, and small supervised branch work.
 - `unreal-engine` owns Unreal Engine source, editor builds, commandlets, and
  game compile/package verification.
 - Keep these roles separated so AI tooling experiments do not destabilize the
  Unreal build host.
 ## Immediate Next Work
 - Verify Open WebUI model selection uses the Ollama backend at
  `http://192.168.5.23:11434`.
 - Use Aider from `LinaAI`, not from `unreal-engine`.
 - Build project memory inside this repo under `Docs/` rather than creating a
  separate documentation repository.
 - Add small local-agent tasks first: summarize systems, write docs, generate
  tests, inspect logs, and prepare Codex handoffs.
@@ -14,6 +14,56 @@
 - The old `/home/nathan/agrarian/dev/ROADMAP.md` is coin/wallet-specific and
  should not be treated as the game roadmap.
 ## Self-Hosted AI Development Stack Bootstrap - 2026-05-23
 - Nathan is starting a self-hosted AI build to reduce pressure on Codex while
  keeping Codex as escalation through the npm Codex CLI rather than API usage.
 - Current service inventory:
  - Gitea: `http://192.168.5.21:3000`
  - Ollama: `http://192.168.5.23:11434`
  - Open WebUI: `http://192.168.5.26:8085`
  - local AI worker VM: `LinaAI / 192.168.5.27`
  - primary Unreal build VM: `unreal-engine / 192.168.5.20`
 - Hardware observed:
  - Unraid host: 12 CPU threads, 46 GiB RAM.
  - `unreal-engine` VM: 8 CPU threads, 31 GiB RAM.
  - local Codex shell host: 4 CPU threads, 3.7 GiB RAM.
 - Ollama model currently available:
  `qwen2.5-coder:7b`.
 - Verified from `unreal-engine`:
  Ollama chat API responded successfully with `local ai ready`.
 - Open WebUI is reachable, but the container template currently shows
  `OLLAMA_BASE_URL=http://localhost:11434`; corrected the running container and
  Unraid template to use `http://192.168.5.23:11434` and port `8085`.
 - Created `LinaAI` on Unraid:
  - 4 vCPU,
  - 12 GiB RAM,
  - 100 GiB disk,
  - static IP `192.168.5.27`,
  - user `nathan`,
  - passwordless sudo for MVP operations,
  - autostart enabled.
 - Reduced `unreal-engine` persistent next-boot allocation to 6 vCPU / 24 GiB
  RAM so LinaAI and the Unreal build VM can coexist. The running Unreal VM was
  not hot-resized.
 - Cleaned the interrupted Aider install from `unreal-engine`; local AI tooling
  belongs on `LinaAI`.
 - Installed on `LinaAI`:
  - `aider-chat` via `pipx`,
  - npm `@openai/codex`,
  - Gitea clone at `/home/nathan/repos/AgrarianGame`.
 - Added self-hosted AI project documentation:
  - `Docs/AI/SelfHostedAiDevelopmentStack.md`
  - `Docs/AI/LocalAgentGuardrails.md`
 - Added initial supervised-agent scripts:
  - `Scripts/ai_check_stack.sh`
  - `Scripts/ai_task_status_template.json`
  - `Scripts/ai_codex_escalate.sh`
 - Guardrail:
  this is a supervised local-agent lane. No autonomous merges to `main`; local
  AI prepares small changes, status files, verification results, and Codex
  handoffs when confidence/build/test gates fail.
 ## AGR Wallet Integration Roadmap Update - 2026-05-21
 - Nathan clarified that AGR coin is a major investor hook for Agrarian:
@@ -0,0 +1,33 @@
 #!/usr/bin/env bash
 set -euo pipefail
 OLLAMA_URL="${OLLAMA_URL:-http://192.168.5.23:11434}"
 OPEN_WEBUI_URL="${OPEN_WEBUI_URL:-http://192.168.5.26:8085}"
 GITEA_URL="${GITEA_URL:-http://192.168.5.21:3000}"
 MODEL="${MODEL:-qwen2.5-coder:7b}"
 echo "Gitea: ${GITEA_URL}"
 curl -fsSI "${GITEA_URL}/user/login" >/dev/null
 echo "  ok"
 echo "Ollama: ${OLLAMA_URL}"
 curl -fsS "${OLLAMA_URL}/api/tags" >/tmp/agrarian_ollama_tags.json
 if ! grep -q "\"${MODEL}\"" /tmp/agrarian_ollama_tags.json; then
  echo "  model ${MODEL} not found"
  cat /tmp/agrarian_ollama_tags.json
  exit 1
 fi
 echo "  ok, model ${MODEL} available"
 echo "Ollama chat smoke test"
 curl -fsS "${OLLAMA_URL}/api/chat" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with exactly: ok\"}],\"stream\":false}" \
  | grep -Eiq '"content":"[[:space:]]*ok[[:space:]]*"'
 echo "  ok"
 echo "Open WebUI: ${OPEN_WEBUI_URL}"
 curl -fsSI "${OPEN_WEBUI_URL}" >/dev/null
 echo "  ok"
 echo "Self-hosted AI stack reachable."
@@ -0,0 +1,50 @@
 #!/usr/bin/env bash
 set -euo pipefail
 if [[ $# -lt 1 ]]; then
  echo "Usage: $0 <task-status-json-or-handoff-text> [extra prompt]" >&2
  exit 2
 fi
 STATUS_FILE="$1"
 EXTRA_PROMPT="${2:-}"
 if [[ ! -f "$STATUS_FILE" ]]; then
  echo "Missing status/handoff file: $STATUS_FILE" >&2
  exit 2
 fi
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
 OUT_DIR="${ROOT}/Saved/AiEscalations/${STAMP}"
 mkdir -p "$OUT_DIR"
 PROMPT_FILE="${OUT_DIR}/codex_prompt.txt"
 LOG_FILE="${OUT_DIR}/codex_exec.log"
 {
  echo "You are Codex being called as an escalation worker for Agrarian."
  echo "Use the repository at: ${ROOT}"
  echo
  echo "Local AI stopped and requested escalation. Review the status below,"
  echo "inspect the repo, make only the needed changes, run verification, and"
  echo "summarize the result. Do not hide uncertainty."
  echo
  echo "Status / handoff:"
  cat "$STATUS_FILE"
  if [[ -n "$EXTRA_PROMPT" ]]; then
    echo
    echo "Extra prompt:"
    echo "$EXTRA_PROMPT"
  fi
 } > "$PROMPT_FILE"
 echo "Prompt written to ${PROMPT_FILE}"
 if command -v codex >/dev/null 2>&1; then
  codex exec "$(cat "$PROMPT_FILE")" 2>&1 | tee "$LOG_FILE"
 else
  npx -y @openai/codex exec "$(cat "$PROMPT_FILE")" 2>&1 | tee "$LOG_FILE"
 fi
 echo "Codex escalation log written to ${LOG_FILE}"
@@ -0,0 +1,16 @@
 {
  "task": "",
  "project": "AgrarianGame",
  "branch": "",
  "risk": "low|medium|high",
  "confidence": 0.0,
  "attempts": 0,
  "files_inspected": [],
  "files_changed": [],
  "commands_run": [],
  "tests_passed": false,
  "build_passed": false,
  "blocked_reason": "",
  "recommended_escalation": "none|codex|human",
  "requested_codex_action": ""
 }