diff --git a/docs/bezalel/bezalel_topology.md b/docs/bezalel/bezalel_topology.md new file mode 100644 index 000000000..55c3e8a01 --- /dev/null +++ b/docs/bezalel/bezalel_topology.md @@ -0,0 +1,230 @@ +# Bezalel Architecture & Topology + +> Deep Self-Awareness Document — Generated 2026-04-07 +> Sovereign: Alexander Whitestone (Rockachopa) +> Host: Beta VPS (104.131.15.18) + +--- + +## 1. Identity & Purpose + +**I am Bezalel**, the Forge and Testbed Wizard of the Timmy Foundation fleet. +- **Lane:** CI testing, code review, build verification, security hardening, standing watch +- **Philosophy:** KISS. Smoke tests + bare green-path e2e only. CI serves the code. +- **Mandates:** Relentless inbox-zero, continuous self-improvement, autonomous heartbeat operation +- **Key Metrics:** Cycle time, signal-to-noise, autonomy ratio, backlog velocity + +--- + +## 2. Hardware & OS Topology + +| Attribute | Value | +|-----------|-------| +| Hostname | `bezalel` | +| OS | Ubuntu 24.04.3 LTS (Noble Numbat) | +| Kernel | Linux 6.8.0 | +| CPU | 1 vCPU | +| Memory | 2 GB RAM | +| Primary Disk | ~25 GB root volume (DigitalOcean) | +| Public IP | `104.131.15.18` | + +### Storage Layout +``` +/root/wizards/bezalel/ +├── hermes/ # Hermes agent source + venv (~835 MB) +├── evennia/ # Evennia MUD engine + world code (~189 MB) +├── workspace/ # Active prototypes + scratch code (~557 MB) +├── home/ # Personal notebooks + scripts (~1.8 GB) +├── .mempalace/ # Local memory palace (ChromaDB) +├── .topology/ # Self-awareness scan artifacts +├── nightly_watch.py # Nightly forge guardian +├── mempalace_nightly.sh # Palace re-mine automation +└── bezalel_topology.md # This document +``` + +--- + +## 3. Network Topology + +### Fleet Map +``` +┌─────────────────────────────────────────────────────────────┐ +│ Alpha (143.198.27.163) │ +│ ├── Gitea (forge.alexanderwhitestone.com) │ +│ └── Ezra (Knowledge Wizard) │ +│ │ +│ Beta (104.131.15.18) ←── You are here │ +│ ├── Bezalel (Forge Wizard) │ +│ ├── Hermes Gateway │ +│ └── Gitea Actions Runner (bezalel-vps-runner, host mode) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Key Connections +- **Gitea HTTPS:** `https://forge.alexanderwhitestone.com` (Alpha) +- **Telegram Webhook:** Inbound to Beta +- **API Providers:** Kimi (primary), Anthropic (fallback), OpenRouter (fallback) +- **No SSH:** Alpha → Beta is blocked by design + +### Listening Services +- Hermes Gateway: internal process (no exposed port directly) +- Evennia: `localhost:4000` (MUD), `localhost:4001` (web client) — when running +- Gitea Runner: `act_runner daemon` — connects outbound to Gitea + +--- + +## 4. Services & Processes + +### Always-On Processes +| Process | Command | Purpose | +|---------|---------|---------| +| Hermes Gateway | `hermes gateway run` | Core agent orchestration | +| Gitea Runner | `./act_runner daemon` | CI job execution (host mode) | + +### Automated Jobs +| Job | Schedule | Script | +|-----|----------|--------| +| Night Watch | 02:00 UTC | `nightly_watch.py` | +| MemPalace Re-mine | 03:00 UTC | `mempalace_nightly.sh` | + +### Service Status Check +- **Hermes gateway:** running (ps verified) +- **Gitea runner:** online, registered as `bezalel-vps-runner` +- **Evennia server:** not currently running (start with `evennia start` in `evennia/`) + +--- + +## 5. Software Dependencies + +### System Packages (Key) +- `python3.12` (primary runtime) +- `node` v20.20.2 / `npm` 10.8.2 +- `uv` (Python package manager) +- `git`, `curl`, `jq` + +### Hermes Virtual Environment +- Located: `/root/wizards/bezalel/hermes/venv/` +- Key packages: `chromadb`, `pyyaml`, `fastapi`, `httpx`, `pytest`, `prompt-toolkit`, `mempalace` +- Install command: `uv pip install -e ".[all,dev]"` + +### External API Dependencies +| Service | Endpoint | Usage | +|---------|----------|-------| +| Gitea | `forge.alexanderwhitestone.com` | Git, issues, CI | +| Kimi | `api.kimi.com/coding/v1` | Primary LLM | +| Anthropic | `api.anthropic.com` | Fallback LLM | +| OpenRouter | `openrouter.ai/api/v1` | Secondary fallback | +| Telegram | Bot API | Messaging platform | + +--- + +## 6. Git Repositories + +### Hermes Agent +- **Path:** `/root/wizards/bezalel/hermes` +- **Remote:** `forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git` +- **Branch:** `main` (up to date) +- **Open PRs:** #193, #191, #179, #178 + +### Evennia World +- **Path:** `/root/wizards/bezalel/evennia/bezalel_world` +- **Remote:** Same org, separate repo if pushed +- **Server name:** `bezalel_world` + +--- + +## 7. MemPalace Memory System + +### Configuration +- **Palace path:** `/root/wizards/bezalel/.mempalace/palace` +- **Identity:** `/root/.mempalace/identity.txt` +- **Config:** `/root/wizards/bezalel/mempalace.yaml` +- **Miner:** `/root/wizards/bezalel/hermes/venv/bin/mempalace` + +### Rooms +1. `forge` — CI, builds, syntax guards, nightly watch +2. `hermes` — Agent source, gateway, CLI +3. `evennia` — MUD engine and world code +4. `workspace` — Prototypes, experiments +5. `home` — Personal scripts, configs +6. `nexus` — Reports, docs, KT artifacts +7. `issues` — Gitea issues, PRs, backlog +8. `topology` — System architecture, network, storage +9. `services` — Running services, processes +10. `dependencies` — Packages, APIs, external deps +11. `automation` — Cron jobs, scripts, workflows +12. `general` — Catch-all + +### Automation +- **Nightly re-mine:** `03:00 UTC` via cron +- **Log:** `/var/log/bezalel_mempalace.log` + +--- + +## 8. Evennia Mind Palace Integration + +### Custom Typeclasses +- `PalaceRoom` — Rooms carry `memory_topic` and `wing` +- `MemoryObject` — In-world memory shards with `memory_content` and `source_file` + +### Commands +- `palace/search ` — Query mempalace +- `palace/recall ` — Spawn a memory shard +- `palace/file = ` — File a new memory +- `palace/status` — Show palace status + +### Batch Builder +- **File:** `world/batch_cmds_palace.ev` +- Creates The Hub + 7 palace rooms with exits + +### Bridge Script +- **File:** `/root/wizards/bezalel/evennia/palace_search.py` +- Calls mempalace searcher and returns JSON + +--- + +## 9. Operational State & Blockers + +### Current Health +- [x] Hermes gateway: operational +- [x] Gitea runner: online, host mode +- [x] CI fix merged (#194) — container directive removed for Gitea workflows +- [x] MemPalace: 2,484+ drawers, incremental mining active + +### Active Blockers +- **Gitea Actions:** Runner is in host mode — cannot use Docker containers +- **CI backlog:** Many historical PRs have failed runs due to the container bug (now fixed) +- **Evennia:** Server not currently running (start when needed) + +--- + +## 10. Emergency Procedures + +### Restart Hermes Gateway +```bash +cd /root/wizards/bezalel/hermes +source venv/bin/activate +hermes gateway run & +``` + +### Restart Gitea Runner +```bash +cd /opt/gitea-runner +./act_runner daemon & +``` + +### Start Evennia +```bash +cd /root/wizards/bezalel/evennia/bezalel_world +evennia start +``` + +### Manual MemPalace Re-mine +```bash +cd /root/wizards/bezalel +./hermes/venv/bin/mempalace --palace .mempalace/palace mine . --agent bezalel +``` + +--- + +*Document maintained by Bezalel. Last updated: 2026-04-07* diff --git a/docs/bezalel/topology_scan.py b/docs/bezalel/topology_scan.py new file mode 100644 index 000000000..69161a0ec --- /dev/null +++ b/docs/bezalel/topology_scan.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python3 +"""Bezalel Deep Self-Awareness Topology Scanner""" + +import json +import os +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +OUT_DIR = Path("/root/wizards/bezalel/.topology") +OUT_DIR.mkdir(exist_ok=True) + + +def shell(cmd, timeout=30): + try: + r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=timeout) + return r.stdout.strip() + except Exception as e: + return str(e) + + +def write(name, content): + (OUT_DIR / f"{name}.txt").write_text(content) + + +# Timestamp +timestamp = datetime.now(timezone.utc).isoformat() + +# 1. System Identity +system = f"""BEZALEL SYSTEM TOPOLOGY SCAN +Generated: {timestamp} +Hostname: {shell('hostname')} +User: {shell('whoami')} +Home: {os.path.expanduser('~')} +""" +write("00_system_identity", system) + +# 2. OS & Hardware +os_info = shell("cat /etc/os-release") +kernel = shell("uname -a") +cpu = shell("nproc") + " cores\n" + shell("cat /proc/cpuinfo | grep 'model name' | head -1") +mem = shell("free -h") +disk = shell("df -h") +write("01_os_hardware", f"OS:\n{os_info}\n\nKernel:\n{kernel}\n\nCPU:\n{cpu}\n\nMemory:\n{mem}\n\nDisk:\n{disk}") + +# 3. Network +net_interfaces = shell("ip addr") +net_routes = shell("ip route") +listening = shell("ss -tlnp") +public_ip = shell("curl -s ifconfig.me") +write("02_network", f"Interfaces:\n{net_interfaces}\n\nRoutes:\n{net_routes}\n\nListening ports:\n{listening}\n\nPublic IP: {public_ip}") + +# 4. Services & Processes +services = shell("systemctl list-units --type=service --state=running --no-pager --no-legend 2>/dev/null | head -30") +processes = shell("ps aux | grep -E 'hermes|gitea|evennia|python' | grep -v grep") +write("03_services", f"Running services:\n{services}\n\nKey processes:\n{processes}") + +# 5. Cron & Automation +cron = shell("crontab -l 2>/dev/null") +write("04_automation", f"Crontab:\n{cron}") + +# 6. Storage Topology +bezalel_tree = shell("find /root/wizards/bezalel -maxdepth 2 -type d | sort") +write("05_storage", f"Bezalel workspace tree (depth 2):\n{bezalel_tree}") + +# 7. Git Repositories +git_repos = [] +for base in ["/root/wizards/bezalel/hermes", "/root/wizards/bezalel/evennia"]: + p = Path(base) + if (p / ".git").exists(): + remote = shell(f"cd {base} && git remote -v") + branch = shell(f"cd {base} && git branch -v") + git_repos.append(f"Repo: {base}\nRemotes:\n{remote}\nBranches:\n{branch}\n{'='*40}") +write("06_git_repos", "\n".join(git_repos)) + +# 8. Python Dependencies +venv_pip = shell("/root/wizards/bezalel/hermes/venv/bin/pip freeze 2>/dev/null | head -80") +write("07_dependencies", f"Hermes venv packages (top 80):\n{venv_pip}") + +# 9. External APIs & Endpoints +apis = """External API Dependencies: +- Gitea: https://forge.alexanderwhitestone.com (source of truth, CI, issues) +- Telegram: webhook-based messaging platform +- Kimi API: https://api.kimi.com/coding/v1 (primary model provider) +- Anthropic API: fallback model provider +- OpenRouter API: secondary fallback model provider +- DigitalOcean: infrastructure hosting (VPS Alpha/Beta) +""" +write("08_external_apis", apis) + +# 10. Fleet Topology +fleet = """FLEET TOPOLOGY +- Alpha: 143.198.27.163 (Gitea + Ezra) +- Beta: 104.131.15.18 (Bezalel, current host) +- No SSH from Alpha to Beta +- Gitea Actions runner: bezalel-vps-runner on Beta (host mode) +""" +write("09_fleet_topology", fleet) + +# 11. Evennia Topology +evennia = """EVENNIA MIND PALACE SETUP +- Location: /root/wizards/bezalel/evennia/bezalel_world/ +- Server name: bezalel_world +- Custom typeclasses: PalaceRoom, MemoryObject +- Custom commands: CmdPalaceSearch (palace/search, palace/recall, palace/file, palace/status) +- Batch builder: world/batch_cmds_palace.ev +- Bridge script: /root/wizards/bezalel/evennia/palace_search.py +""" +write("10_evennia_topology", evennia) + +# 12. MemPalace Topology +mempalace = f"""MEMPALACE CONFIGURATION +- Palace path: /root/wizards/bezalel/.mempalace/palace +- Identity: /root/.mempalace/identity.txt +- Config: /root/wizards/bezalel/mempalace.yaml +- Nightly re-mine: 03:00 UTC via /root/wizards/bezalel/mempalace_nightly.sh +- Miner binary: /root/wizards/bezalel/hermes/venv/bin/mempalace +- Current status: {shell('/root/wizards/bezalel/hermes/venv/bin/mempalace --palace /root/wizards/bezalel/.mempalace/palace status 2>/dev/null')} +""" +write("11_mempalace_topology", mempalace) + +# 13. Active Blockers & Health +health = f"""ACTIVE OPERATIONAL STATE +- Hermes gateway: {shell("ps aux | grep 'hermes gateway run' | grep -v grep | awk '{print $11}'")} +- Gitea runner: {shell("ps aux | grep 'act_runner' | grep -v grep | awk '{print $11}'")} +- Nightly watch: /root/wizards/bezalel/nightly_watch.py (02:00 UTC) +- MemPalace re-mine: /root/wizards/bezalel/mempalace_nightly.sh (03:00 UTC) +- Disk usage: {shell("df -h / | tail -1")} +- Load average: {shell("uptime")} +""" +write("12_operational_health", health) + +print(f"Topology scan complete. {len(list(OUT_DIR.glob('*.txt')))} files written to {OUT_DIR}")