Compare commits
2 Commits
step35/678
...
fix/665
| Author | SHA1 | Date | |
|---|---|---|---|
|
0c9cddb185 | ||
|
|
c2361a29a8 |
299
GENOME.md
299
GENOME.md
@@ -1,209 +1,144 @@
|
||||
# GENOME.md — the-nexus
|
||||
# GENOME.md — Timmy_Foundation/timmy-home
|
||||
|
||||
Generated by `pipelines/codebase_genome.py`.
|
||||
|
||||
## Project Overview
|
||||
|
||||
`the-nexus` is a hybrid repo that combines three layers in one codebase:
|
||||
Timmy Foundation's home repository for development operations and configurations.
|
||||
|
||||
1. A browser-facing world shell rooted in `index.html`, `boot.js`, `bootstrap.mjs`, `app.js`, `style.css`, `portals.json`, `vision.json`, `manifest.json`, and `gofai_worker.js`
|
||||
2. A Python realtime bridge centered on `server.py` plus harness code under `nexus/`
|
||||
3. A memory / fleet / operator layer spanning `mempalace/`, `mcp_servers/`, `multi_user_bridge.py`, and supporting scripts
|
||||
- Text files indexed: 3181
|
||||
- Source and script files: 231
|
||||
- Test files: 95
|
||||
- Documentation files: 755
|
||||
|
||||
The repo is not a clean single-purpose frontend and not just a backend harness. It is a mixed world/runtime/ops repository where browser rendering, WebSocket telemetry, MCP-driven game harnesses, and fleet memory tooling coexist.
|
||||
|
||||
Grounded repo facts from this checkout:
|
||||
- Browser shell files exist at repo root: `index.html`, `app.js`, `style.css`, `manifest.json`, `gofai_worker.js`
|
||||
- Data/config files also live at repo root: `portals.json`, `vision.json`
|
||||
- Realtime bridge exists in `server.py`
|
||||
- Game harnesses exist in `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py`
|
||||
- Memory/fleet sync exists in `mempalace/tunnel_sync.py`
|
||||
- Desktop/game automation MCP servers exist in `mcp_servers/desktop_control_server.py` and `mcp_servers/steam_info_server.py`
|
||||
- Validation exists in `tests/test_browser_smoke.py`, `tests/test_portals_json.py`, `tests/test_index_html_integrity.py`, and `tests/test_repo_truth.py`
|
||||
|
||||
The current architecture is best understood as a sovereign world shell plus operator/game harness backend, with accumulated documentation drift from multiple restoration and migration efforts.
|
||||
|
||||
## Architecture Diagram
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
browser[Index HTML Shell\nindex.html -> boot.js -> bootstrap.mjs -> app.js]
|
||||
assets[Root Assets\nstyle.css\nmanifest.json\ngofai_worker.js]
|
||||
data[World Data\nportals.json\nvision.json]
|
||||
ws[Realtime Bridge\nserver.py\nWebSocket broadcast hub]
|
||||
gofai[In-browser GOFAI\nSymbolicEngine\nNeuroSymbolicBridge\nsetupGOFAI/updateGOFAI]
|
||||
harnesses[Python Harnesses\nnexus/morrowind_harness.py\nnexus/bannerlord_harness.py]
|
||||
mcp[MCP Adapters\nmcp_servers/desktop_control_server.py\nmcp_servers/steam_info_server.py]
|
||||
memory[Memory + Fleet\nmempalace/tunnel_sync.py\nmempalace.js]
|
||||
bridge[Operator / MUD Bridge\nmulti_user_bridge.py\ncommands/timmy_commands.py]
|
||||
tests[Verification\ntests/test_browser_smoke.py\ntests/test_portals_json.py\ntests/test_repo_truth.py]
|
||||
docs[Contracts + Drift Docs\nBROWSER_CONTRACT.md\nREADME.md\nCLAUDE.md\nINVESTIGATION_ISSUE_1145.md]
|
||||
|
||||
browser --> assets
|
||||
browser --> data
|
||||
browser --> gofai
|
||||
browser --> ws
|
||||
harnesses --> mcp
|
||||
harnesses --> ws
|
||||
bridge --> ws
|
||||
memory --> ws
|
||||
tests --> browser
|
||||
tests --> data
|
||||
tests --> docs
|
||||
docs --> browser
|
||||
repo_root["repo"]
|
||||
angband["angband"]
|
||||
ansible["ansible"]
|
||||
briefings["briefings"]
|
||||
codebase_genome["codebase_genome"]
|
||||
config["config"]
|
||||
configs["configs"]
|
||||
conftest["conftest"]
|
||||
dns_records["dns-records"]
|
||||
evennia["evennia"]
|
||||
evennia_tools["evennia_tools"]
|
||||
repo_root --> angband
|
||||
repo_root --> ansible
|
||||
repo_root --> briefings
|
||||
repo_root --> codebase_genome
|
||||
repo_root --> config
|
||||
repo_root --> configs
|
||||
```
|
||||
|
||||
## Entry Points and Data Flow
|
||||
## Entry Points
|
||||
|
||||
### Primary entry points
|
||||
- `codebase_genome.py` — python main guard (`python3 codebase_genome.py`)
|
||||
- `gemini-fallback-setup.sh` — operational script (`bash gemini-fallback-setup.sh`)
|
||||
- `morrowind/hud.sh` — operational script (`bash morrowind/hud.sh`)
|
||||
- `pipelines/codebase_genome.py` — python main guard (`python3 pipelines/codebase_genome.py`)
|
||||
- `scripts/agent_pr_gate.py` — operational script (`python3 scripts/agent_pr_gate.py`)
|
||||
- `scripts/audit_trail.py` — operational script (`python3 scripts/audit_trail.py`)
|
||||
- `scripts/auto_restart_agent.sh` — operational script (`bash scripts/auto_restart_agent.sh`)
|
||||
- `scripts/autonomous_issue_creator.py` — operational script (`python3 scripts/autonomous_issue_creator.py`)
|
||||
- `scripts/backlog_cleanup.py` — operational script (`python3 scripts/backlog_cleanup.py`)
|
||||
- `scripts/backlog_triage.py` — operational script (`python3 scripts/backlog_triage.py`)
|
||||
- `scripts/backlog_triage_cron.sh` — operational script (`bash scripts/backlog_triage_cron.sh`)
|
||||
- `scripts/backup_pipeline.sh` — operational script (`bash scripts/backup_pipeline.sh`)
|
||||
|
||||
- `index.html` — root browser entry point
|
||||
- `boot.js` — startup selector; `tests/boot.test.js` shows it chooses file-mode vs HTTP/module-mode and injects `bootstrap.mjs` when served over HTTP
|
||||
- `bootstrap.mjs` — module bootstrap for the browser shell
|
||||
- `app.js` — main browser runtime; owns world state, GOFAI wiring, metrics polling, and portal/UI logic
|
||||
- `server.py` — WebSocket broadcast bridge on `ws://0.0.0.0:8765`
|
||||
- `nexus/morrowind_harness.py` — GamePortal/MCP harness for OpenMW Morrowind
|
||||
- `nexus/bannerlord_harness.py` — GamePortal/MCP harness for Bannerlord
|
||||
- `mempalace/tunnel_sync.py` — pulls remote fleet closets into the local palace over HTTP
|
||||
- `multi_user_bridge.py` — HTTP bridge for multi-user chat/session integration
|
||||
- `mcp_servers/desktop_control_server.py` — stdio MCP server exposing screenshots/mouse/keyboard control
|
||||
## Data Flow
|
||||
|
||||
### Data flow
|
||||
|
||||
1. Browser startup begins at `index.html`
|
||||
2. `boot.js` decides whether the page is being served correctly; in HTTP mode it injects `bootstrap.mjs`
|
||||
3. `bootstrap.mjs` hands off to `app.js`
|
||||
4. `app.js` loads world configuration from `portals.json` and `vision.json`
|
||||
5. `app.js` constructs the Three.js scene and in-browser reasoning components, including `SymbolicEngine`, `NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
|
||||
6. Browser state and external runtimes connect through `server.py`, which broadcasts messages between connected clients
|
||||
7. Python harnesses (`nexus/morrowind_harness.py`, `nexus/bannerlord_harness.py`) spawn MCP subprocesses for desktop control / Steam metadata, capture state, execute actions, and feed telemetry into the Nexus bridge
|
||||
8. Memory/fleet tools like `mempalace/tunnel_sync.py` import remote palace data into local closets, extending what the operator/runtime layers can inspect
|
||||
9. Tests validate both the static browser contract and the higher-level repo-truth/memory contracts
|
||||
|
||||
### Important repo-specific runtime facts
|
||||
|
||||
- `portals.json` is a JSON array of portal/world/operator entries; examples in this checkout include `morrowind`, `bannerlord`, `workshop`, `archive`, `chapel`, and `courtyard`
|
||||
- `server.py` is a plain broadcast hub: clients send messages, the server forwards them to other connected clients
|
||||
- `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py` both implement a GamePortal pattern with MCP subprocess clients over stdio and WebSocket telemetry uplink
|
||||
- `mempalace/tunnel_sync.py` is not speculative; it is a real client that discovers remote wings, searches remote rooms, and writes `.closet.json` payloads locally
|
||||
1. Operators enter through `codebase_genome.py`, `gemini-fallback-setup.sh`, `morrowind/hud.sh`.
|
||||
2. Core logic fans into top-level components: `angband`, `ansible`, `briefings`, `codebase_genome`, `config`, `configs`.
|
||||
3. Validation is incomplete around `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py`, `timmy-local/cache/agent_cache.py`, `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py`, so changes there carry regression risk.
|
||||
4. Final artifacts land as repository files, docs, or runtime side effects depending on the selected entry point.
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### Browser runtime
|
||||
|
||||
- `app.js`
|
||||
- Defines in-browser reasoning/state machinery, including `class SymbolicEngine`, `class NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
|
||||
- Couples rendering, local symbolic reasoning, metrics polling, and portal/UI logic in one very large root module
|
||||
- `BROWSER_CONTRACT.md`
|
||||
- Acts like an executable architecture contract for the browser surface
|
||||
- Declares required files, DOM IDs, Three.js expectations, provenance rules, and WebSocket expectations
|
||||
|
||||
### Realtime bridge
|
||||
|
||||
- `server.py`
|
||||
- Single hub abstraction: a WebSocket broadcast server maintaining a `clients` set and forwarding messages from one client to the others
|
||||
- This is the seam between browser shell, harnesses, and external telemetry producers
|
||||
|
||||
### GamePortal harness layer
|
||||
|
||||
- `nexus/morrowind_harness.py`
|
||||
- `nexus/bannerlord_harness.py`
|
||||
- Both define MCP client wrappers, `GameState` / `ActionResult`-style data classes, and an Observe-Decide-Act telemetry loop
|
||||
- The harnesses are symmetric enough to be understood as reusable portal adapters with game-specific context injected on top
|
||||
|
||||
### Memory / fleet layer
|
||||
|
||||
- `mempalace/tunnel_sync.py`
|
||||
- Encodes the fleet-memory sync client contract: discover wings, pull broad room queries, write closet files, support dry-run
|
||||
- `mempalace.js`
|
||||
- Minimal browser/Electron bridge to MemPalace commands via `window.electronAPI.execPython(...)`
|
||||
- Important because it shows a second memory integration surface distinct from the Python fleet sync path
|
||||
|
||||
### Operator / interaction bridge
|
||||
|
||||
- `multi_user_bridge.py`
|
||||
- `commands/timmy_commands.py`
|
||||
- These bridge user-facing conversations or MUD/Evennia interactions back into Timmy/Nexus services
|
||||
- `codebase_genome.py` — classes `FunctionInfo`:19; functions `extract_functions()`:58, `generate_test()`:116, `scan_repo()`:191, `find_existing_tests()`:209, `main()`:231
|
||||
- `evennia/timmy_world/game.py` — classes `World`:91, `ActionSystem`:421, `TimmyAI`:539, `NPCAI`:550; functions `get_narrative_phase()`:55, `get_phase_transition_event()`:65
|
||||
- `evennia/timmy_world/world/game.py` — classes `World`:19, `ActionSystem`:326, `TimmyAI`:444, `NPCAI`:455; functions none detected
|
||||
- `timmy-world/game.py` — classes `World`:19, `ActionSystem`:349, `TimmyAI`:467, `NPCAI`:478; functions none detected
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — classes none detected; functions none detected
|
||||
- `uniwizard/self_grader.py` — classes `SessionGrade`:23, `WeeklyReport`:55, `SelfGrader`:74; functions `main()`:713
|
||||
- `uni-wizard/v3/intelligence_engine.py` — classes `ExecutionPattern`:27, `ModelPerformance`:44, `AdaptationEvent`:58, `PatternDatabase`:69; functions none detected
|
||||
- `scripts/know_thy_father/crossref_audit.py` — classes `ThemeCategory`:30, `Principle`:160, `MeaningKernel`:169, `CrossRefFinding`:178; functions `extract_themes_from_text()`:192, `parse_soul_md()`:206, `parse_kernels()`:264, `cross_reference()`:296, `generate_report()`:440, `main()`:561
|
||||
|
||||
## API Surface
|
||||
|
||||
### Browser / static surface
|
||||
- CLI: `python3 codebase_genome.py` — python main guard (`codebase_genome.py`)
|
||||
- CLI: `bash gemini-fallback-setup.sh` — operational script (`gemini-fallback-setup.sh`)
|
||||
- CLI: `bash morrowind/hud.sh` — operational script (`morrowind/hud.sh`)
|
||||
- CLI: `python3 pipelines/codebase_genome.py` — python main guard (`pipelines/codebase_genome.py`)
|
||||
- CLI: `python3 scripts/agent_pr_gate.py` — operational script (`scripts/agent_pr_gate.py`)
|
||||
- CLI: `python3 scripts/audit_trail.py` — operational script (`scripts/audit_trail.py`)
|
||||
- CLI: `bash scripts/auto_restart_agent.sh` — operational script (`scripts/auto_restart_agent.sh`)
|
||||
- CLI: `python3 scripts/autonomous_issue_creator.py` — operational script (`scripts/autonomous_issue_creator.py`)
|
||||
- Python: `extract_functions()` from `codebase_genome.py:58`
|
||||
- Python: `generate_test()` from `codebase_genome.py:116`
|
||||
- Python: `scan_repo()` from `codebase_genome.py:191`
|
||||
- Python: `find_existing_tests()` from `codebase_genome.py:209`
|
||||
- Python: `main()` from `codebase_genome.py:231`
|
||||
- Python: `get_narrative_phase()` from `evennia/timmy_world/game.py:55`
|
||||
|
||||
- `index.html` served over HTTP
|
||||
- `boot.js` exports `bootPage()`; verified by `node --test tests/boot.test.js`
|
||||
- Data APIs are file-based inside the repo: `portals.json`, `vision.json`, `manifest.json`
|
||||
## Test Coverage Report
|
||||
|
||||
### Network/runtime surface
|
||||
- Source and script files inspected: 231
|
||||
- Test files inspected: 95
|
||||
- Coverage gaps:
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — no matching test reference detected
|
||||
- `timmy-local/cache/agent_cache.py` — no matching test reference detected
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py` — no matching test reference detected
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/godmode_race.py` — no matching test reference detected
|
||||
- `skills/productivity/google-workspace/scripts/google_api.py` — no matching test reference detected
|
||||
- `wizards/allegro/home/skills/productivity/google-workspace/scripts/google_api.py` — no matching test reference detected
|
||||
- `morrowind/pilot.py` — no matching test reference detected
|
||||
- `scripts/sovereignty_audit.py` — no matching test reference detected
|
||||
- `skills/research/domain-intel/scripts/domain_intel.py` — no matching test reference detected
|
||||
- `wizards/allegro/home/skills/research/domain-intel/scripts/domain_intel.py` — no matching test reference detected
|
||||
- `timmy-local/scripts/ingest.py` — no matching test reference detected
|
||||
- `uni-wizard/scripts/generate_scorecard.py` — no matching test reference detected
|
||||
|
||||
- `python3 server.py`
|
||||
- Starts the WebSocket bridge on port `8765`
|
||||
- `python3 l402_server.py`
|
||||
- Local HTTP microservice for cost-estimate style responses
|
||||
- `python3 multi_user_bridge.py`
|
||||
- Multi-user HTTP/chat bridge
|
||||
## Security Audit Findings
|
||||
|
||||
### Harness / operator CLI surfaces
|
||||
- [medium] `briefings/briefing_20260325.json:37` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"gitea_error": "Gitea 404: {\"errors\":null,\"message\":\"not found\",\"url\":\"http://143.198.27.163:3000/api/swagger\"}\n [http://143.198.27.163:3000/api/v1/repos/Timmy_Foundation/sovereign-orchestration/issues?state=open&type=issues&sort=created&direction=desc&limit=1&page=1]",`
|
||||
- [medium] `briefings/briefing_20260328.json:11` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"provider_base_url": "http://localhost:8081/v1",`
|
||||
- [medium] `briefings/briefing_20260329.json:11` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"provider_base_url": "http://localhost:8081/v1",`
|
||||
- [medium] `config.yaml:37` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `summary_base_url: http://localhost:11434/v1`
|
||||
- [medium] `config.yaml:47` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:52` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:57` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:62` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:67` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:77` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:82` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
|
||||
- [medium] `config.yaml:174` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: http://localhost:11434/v1`
|
||||
|
||||
- `python3 nexus/morrowind_harness.py`
|
||||
- `python3 nexus/bannerlord_harness.py`
|
||||
- `python3 mempalace/tunnel_sync.py --peer <url> [--dry-run] [--n N]`
|
||||
- `python3 mcp_servers/desktop_control_server.py`
|
||||
- `python3 mcp_servers/steam_info_server.py`
|
||||
## Dead Code Candidates
|
||||
|
||||
### Validation surface
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `timmy-local/cache/agent_cache.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `wizards/allegro/home/skills/red-teaming/godmode/scripts/godmode_race.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `skills/productivity/google-workspace/scripts/google_api.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `wizards/allegro/home/skills/productivity/google-workspace/scripts/google_api.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `morrowind/pilot.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `scripts/sovereignty_audit.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `skills/research/domain-intel/scripts/domain_intel.py` — not imported by indexed Python modules and not referenced by tests
|
||||
- `wizards/allegro/home/skills/research/domain-intel/scripts/domain_intel.py` — not imported by indexed Python modules and not referenced by tests
|
||||
|
||||
- `python3 -m pytest tests/test_portals_json.py tests/test_index_html_integrity.py tests/test_repo_truth.py -q`
|
||||
- `node --test tests/boot.test.js`
|
||||
- `python3 -m py_compile server.py nexus/morrowind_harness.py nexus/bannerlord_harness.py mempalace/tunnel_sync.py mcp_servers/desktop_control_server.py`
|
||||
- `tests/test_browser_smoke.py` defines the higher-cost Playwright smoke contract for the world shell
|
||||
## Performance Bottleneck Analysis
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
Strongly covered in this checkout:
|
||||
- `tests/test_portals_json.py` validates `portals.json`
|
||||
- `tests/test_index_html_integrity.py` checks merge-marker/DOM-integrity regressions in `index.html`
|
||||
- `tests/boot.test.js` verifies `boot.js` startup behavior
|
||||
- `tests/test_repo_truth.py` validates the repo-truth documents
|
||||
- Multiple `tests/test_mempalace_*.py` files cover the palace layer
|
||||
- `tests/test_bannerlord_harness.py` exists for the Bannerlord harness
|
||||
|
||||
Notable gaps or weak seams:
|
||||
- `nexus/morrowind_harness.py` is large and operationally critical, but the generated baseline still flags it as a gap relative to its size/complexity
|
||||
- `mcp_servers/desktop_control_server.py` exposes high-power automation but has no obvious dedicated test file in the root `tests/` suite
|
||||
- `app.js` is the dominant browser runtime file and mixes rendering, GOFAI, metrics, and integration logic in one place; browser smoke exists, but there is limited unit-level decomposition around those subsystems
|
||||
- `mempalace.js` appears minimally bridged and stale relative to the richer Python MemPalace layer
|
||||
- `multi_user_bridge.py` is a large integration surface and should be treated as high regression risk even though it is central to operator/chat flow
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- `server.py` binds `HOST = "0.0.0.0"`, exposing the broadcast bridge beyond localhost unless network controls limit it
|
||||
- The WebSocket bridge is a broadcast hub without visible authentication in `server.py`; connected clients are trusted to send messages into the bus
|
||||
- `mcp_servers/desktop_control_server.py` exposes mouse/keyboard/screenshot control through a stdio MCP server. In any non-local or poorly isolated runtime, this is a privileged automation surface
|
||||
- `app.js` contains hardcoded local/network endpoints such as `http://localhost:${L402_PORT}/api/cost-estimate` and `http://localhost:8082/metrics`; these are convenient for local development but create environment drift and deployment assumptions
|
||||
- `app.js` also embeds explicit endpoint/status references like `ws://143.198.27.163:8765`, which is operationally brittle and the kind of hardcoded location data that drifts across environments
|
||||
- `mempalace.js` shells out through `window.electronAPI.execPython(...)`; this is powerful and useful, but it is a clear trust boundary between UI and host execution
|
||||
- `INVESTIGATION_ISSUE_1145.md` documents an earlier integrity hazard: agents writing to `public/nexus/` instead of canonical root paths. That path confusion is both an operational and security concern because it makes provenance harder to reason about
|
||||
|
||||
## Runtime Truth and Docs Drift
|
||||
|
||||
The most important architecture finding in this repo is not a class or subsystem. It is a truth mismatch.
|
||||
|
||||
- README.md says current `main` does not ship a browser 3D world
|
||||
- CLAUDE.md declares root `app.js` and `index.html` as canonical frontend paths
|
||||
- tests and browser contract now assume the root frontend exists
|
||||
|
||||
All three statements are simultaneously present in this checkout.
|
||||
|
||||
Grounded evidence:
|
||||
- `README.md` still says the repo does not contain an active root frontend such as `index.html`, `app.js`, or `style.css`
|
||||
- the current checkout does contain `index.html`, `app.js`, `style.css`, `manifest.json`, and `gofai_worker.js`
|
||||
- `BROWSER_CONTRACT.md` explicitly treats those root files as required browser assets
|
||||
- `tests/test_browser_smoke.py` serves those exact files and validates DOM/WebGL contracts against them
|
||||
- `tests/test_index_html_integrity.py` assumes `index.html` is canonical and production-relevant
|
||||
- `CLAUDE.md` says frontend code lives at repo root and explicitly warns against `public/nexus/`
|
||||
- `INVESTIGATION_ISSUE_1145.md` explains why `public/nexus/` is a bad/corrupt duplicate path and confirms the real classical AI code lives in root `app.js`
|
||||
|
||||
The honest conclusion:
|
||||
- The repo contains a partially restored or actively re-materialized browser surface
|
||||
- The docs are preserving an older migration truth while the runtime files and smoke contracts describe a newer present-tense truth
|
||||
- Any future work in `the-nexus` must choose one truth and align `README.md`, `CLAUDE.md`, smoke tests, and file layout around it
|
||||
|
||||
That drift is itself a critical architectural fact and should be treated as first-order design debt, not a side note.
|
||||
- `angband/mcp_server.py` — large module (353 lines) likely hides multiple responsibilities
|
||||
- `evennia/timmy_world/game.py` — large module (1541 lines) likely hides multiple responsibilities
|
||||
- `evennia/timmy_world/world/game.py` — large module (1345 lines) likely hides multiple responsibilities
|
||||
- `morrowind/mcp_server.py` — large module (451 lines) likely hides multiple responsibilities
|
||||
- `morrowind/pilot.py` — large module (459 lines) likely hides multiple responsibilities
|
||||
- `pipelines/codebase_genome.py` — large module (557 lines) likely hides multiple responsibilities
|
||||
- `scripts/fleet_progression.py` — large module (361 lines) likely hides multiple responsibilities
|
||||
- `scripts/know_thy_father/crossref_audit.py` — large module (657 lines) likely hides multiple responsibilities
|
||||
- `scripts/know_thy_father/index_media.py` — large module (405 lines) likely hides multiple responsibilities
|
||||
- `scripts/know_thy_father/synthesize_kernels.py` — large module (416 lines) likely hides multiple responsibilities
|
||||
|
||||
14
codebase_genome_cron.yml
Normal file
14
codebase_genome_cron.yml
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
- name: Codebase Genome Nightly
|
||||
schedule: '30 2 * * *' # Daily at 02:30 local time
|
||||
tasks:
|
||||
- name: Ensure output and log directories exist
|
||||
shell: "mkdir -p ~/.timmy/codebase-genomes ~/.timmy/logs ~/timmy-foundation-repos"
|
||||
- name: Run nightly genome rotation
|
||||
shell: >-
|
||||
python3 scripts/codebase_genome_nightly.py
|
||||
--org Timmy_Foundation
|
||||
--workspace-root ~/timmy-foundation-repos
|
||||
--output-root ~/.timmy/codebase-genomes
|
||||
--state-path ~/.timmy/codebase_genome_state.json
|
||||
>> ~/.timmy/logs/codebase_genome_nightly.log 2>&1
|
||||
@@ -10,6 +10,8 @@ This pipeline gives Timmy a repeatable way to generate a deterministic `GENOME.m
|
||||
- `pipelines/codebase-genome.py` — thin CLI wrapper matching the expected pipeline-style entrypoint
|
||||
- `scripts/codebase_genome_nightly.py` — org-aware nightly runner that selects the next repo, updates a local checkout, and writes the genome artifact
|
||||
- `scripts/codebase_genome_status.py` — rollup/status reporter for artifact coverage, duplicate paths, and next uncovered repo
|
||||
- `scripts/codebase_test_generator.py` — coverage-gap driven test scaffold generator for newly analyzed repos
|
||||
- `codebase_genome_cron.yml` — checked-in nightly cron spec for the rotating genome pass
|
||||
- `GENOME.md` — generated analysis for `timmy-home` itself
|
||||
|
||||
## Genome output
|
||||
|
||||
@@ -1,271 +1,417 @@
|
||||
# GENOME.md — evennia-local-world
|
||||
|
||||
*Auto-generated by Codebase Genome Pipeline. 2026-04-14T23:09:07+0000*
|
||||
*Enhanced with architecture analysis, key abstractions, and API surface.*
|
||||
|
||||
## Quick Facts
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Source files | 43 |
|
||||
| Test files | 0 |
|
||||
| Config files | 1 |
|
||||
| Total lines | 4,985 |
|
||||
| Last commit | 95eadf2 Merge PR #786: [claude] complete crisis doctrine in SOUL.md + refresh horizon doc (#545) (2026-04-22 02:39:05 +0000) |
|
||||
| Branch | main |
|
||||
| Test coverage | 0% (35 untested modules) |
|
||||
*Generated: 2026-04-21 07:07:29 UTC | Refreshed for timmy-home #677*
|
||||
|
||||
## Project Overview
|
||||
|
||||
The academy codebase comprises **43 Python files** totaling **4,985** lines of source code. Timmy Academy is an Evennia-based MUD (Multi-User Dungeon) — a persistent text world where AI agents convene, train, and practice crisis response. It runs on Bezalel VPS (167.99.126.228) with telnet on port 4000 and web client on port 4001.
|
||||
`evennia/timmy_world` is a hybrid codebase with two layers living side by side:
|
||||
|
||||
The world has five wings: Central Hub, Dormitory, Commons, Workshop, and Gardens. Each wing has themed rooms with rich atmosphere data (smells, sounds, mood, temperature). Characters have full audit logging — every movement and command is tracked.
|
||||
1. A mostly stock Evennia 6.0 game directory:
|
||||
- `server/conf/*.py`
|
||||
- `typeclasses/*.py`
|
||||
- `commands/*.py`
|
||||
- `web/**/*.py`
|
||||
- `world/prototypes.py`
|
||||
- `world/help_entries.py`
|
||||
2. A custom standalone Tower simulation implemented in pure Python:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
- `evennia/timmy_world/play_200.py`
|
||||
|
||||
Grounded metrics from live inspection:
|
||||
- 68 tracked files under `evennia/timmy_world`
|
||||
- 43 Python files
|
||||
- 4,985 Python LOC
|
||||
- largest modules:
|
||||
- `evennia/timmy_world/game.py` — 1,541 lines
|
||||
- `evennia/timmy_world/world/game.py` — 1,345 lines
|
||||
- `evennia/timmy_world/play_200.py` — 275 lines
|
||||
- `evennia/timmy_world/typeclasses/objects.py` — 217 lines
|
||||
- `evennia/timmy_world/commands/command.py` — 187 lines
|
||||
|
||||
The repo is not just an Evennia shell. The distinctive product logic lives in the standalone Tower simulator. That simulator models five rooms, named agents, trust/energy systems, narrative phases, NPC decision-making, and JSON persistence. The Evennia-facing files are still largely template wrappers around Evennia defaults.
|
||||
|
||||
## Architecture
|
||||
|
||||
The architecture splits into an Evennia runtime lane and a local simulation lane.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Connections"
|
||||
TELNET[Telnet :4000]
|
||||
WEB[Web Client :4001]
|
||||
graph TD
|
||||
subgraph External Clients
|
||||
Telnet[Telnet client :4000]
|
||||
Browser[Browser / webclient :4001]
|
||||
Operator[Local operator]
|
||||
end
|
||||
|
||||
subgraph "Evennia Core"
|
||||
SERVER[Evennia Server]
|
||||
PORTAL[Evennia Portal]
|
||||
subgraph Evennia Runtime
|
||||
Settings[server/conf/settings.py]
|
||||
URLs[web/urls.py]
|
||||
Cmdsets[commands/default_cmdsets.py]
|
||||
Typeclasses[typeclasses/*.py]
|
||||
WorldDocs[world/prototypes.py + world/help_entries.py]
|
||||
WebHooks[server/conf/web_plugins.py]
|
||||
end
|
||||
|
||||
subgraph "Typeclasses"
|
||||
CHAR[Character]
|
||||
AUDIT[AuditedCharacter]
|
||||
ROOM[Room]
|
||||
EXIT[Exit]
|
||||
OBJ[Object]
|
||||
subgraph Standalone Tower Simulator
|
||||
Play200[play_200.py]
|
||||
RootGame[game.py]
|
||||
AltGame[world/game.py]
|
||||
Engine[GameEngine / PlayerInterface / NPCAI]
|
||||
State[game_state.json + timmy_log.md]
|
||||
end
|
||||
|
||||
subgraph "Commands"
|
||||
CMD_EXAM[CmdExamine]
|
||||
CMD_ROOMS[CmdRooms]
|
||||
CMD_STATUS[CmdStatus]
|
||||
CMD_MAP[CmdMap]
|
||||
CMD_ACADEMY[CmdAcademy]
|
||||
CMD_SMELL[CmdSmell]
|
||||
CMD_LISTEN[CmdListen]
|
||||
CMD_WHO[CmdWho]
|
||||
end
|
||||
Telnet --> Settings
|
||||
Browser --> URLs
|
||||
Settings --> Cmdsets
|
||||
Cmdsets --> Typeclasses
|
||||
URLs --> WebHooks
|
||||
Typeclasses --> WorldDocs
|
||||
|
||||
subgraph "World - Wings"
|
||||
HUB[Central Hub]
|
||||
DORM[Dormitory Wing]
|
||||
COMMONS[Commons Wing]
|
||||
WORKSHOP[Workshop Wing]
|
||||
GARDENS[Gardens Wing]
|
||||
end
|
||||
|
||||
subgraph "Hermes Bridge"
|
||||
HERMES_CFG[hermes-agent/config.yaml]
|
||||
BRIDGE[Agent Bridge]
|
||||
end
|
||||
|
||||
TELNET --> SERVER
|
||||
WEB --> PORTAL
|
||||
PORTAL --> SERVER
|
||||
SERVER --> CHAR
|
||||
SERVER --> AUDIT
|
||||
SERVER --> ROOM
|
||||
SERVER --> EXIT
|
||||
CHAR --> CMD_EXAM
|
||||
CHAR --> CMD_STATUS
|
||||
CHAR --> CMD_WHO
|
||||
ROOM --> HUB
|
||||
ROOM --> DORM
|
||||
ROOM --> COMMONS
|
||||
ROOM --> WORKSHOP
|
||||
ROOM --> GARDENS
|
||||
HERMES_CFG --> BRIDGE
|
||||
BRIDGE --> SERVER
|
||||
Operator --> Play200
|
||||
Play200 --> RootGame
|
||||
RootGame --> Engine
|
||||
AltGame --> Engine
|
||||
Engine --> State
|
||||
```
|
||||
|
||||
Core engine modules:
|
||||
- `evennia/timmy_world/game.py` — top-level GameEngine
|
||||
- `evennia/timmy_world/world/game.py` — world model (World, Room, Item, NPC)
|
||||
- `evennia/timmy_world/play_200.py` — demo training scenario
|
||||
What is actually wired today:
|
||||
- `server/conf/settings.py` only overrides `SERVERNAME = "timmy_world"` and optionally imports `server.conf.secret_settings`.
|
||||
- `web/urls.py` mounts `web.website.urls`, `web.webclient.urls`, `web.admin.urls`, then appends `evennia.web.urls`.
|
||||
- `commands/default_cmdsets.py` subclasses Evennia defaults but does not add custom commands yet.
|
||||
- `typeclasses/*.py` are thin wrappers around Evennia defaults.
|
||||
- `server/conf/web_plugins.py` returns the web roots unchanged.
|
||||
- `server/conf/at_initial_setup.py` is a no-op.
|
||||
- `world/batch_cmds.ev` is still template commentary rather than a real build script.
|
||||
|
||||
What is custom and stateful today:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
- `evennia/timmy_world/play_200.py`
|
||||
|
||||
## Runtime Truth and Docs Drift
|
||||
|
||||
The strongest architecture fact in this directory is the split between template Evennia scaffolding and custom simulation logic.
|
||||
|
||||
Drift discovered during inspection:
|
||||
- `evennia/timmy_world/README.md` is the stock Evennia welcome text.
|
||||
- `server/conf/at_initial_setup.py` is empty, so the Evennia world is not auto-populating custom Tower content at first boot.
|
||||
- `world/batch_cmds.ev` is also a template, not a concrete room/object bootstrap file.
|
||||
- The deepest custom logic is not in the typeclasses or server hooks. It is in `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
- `evennia/timmy_world/play_200.py` imports `from game import GameEngine, NARRATIVE_PHASES`, which proves the root `game.py` is an active entry point.
|
||||
- `evennia/timmy_world/world/game.py` is not dead weight either; it contains its own `World`, `ActionSystem`, `NPCAI`, `DialogueSystem`, `GameEngine`, and `PlayerInterface` stack.
|
||||
|
||||
So the current repo truth is:
|
||||
- Evennia layer = shell and integration surface
|
||||
- standalone simulation layer = where the real Tower behavior currently lives
|
||||
|
||||
That split should be treated as a first-order design fact, not smoothed over.
|
||||
|
||||
## Entry Points
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `server/conf/settings.py` | Evennia config — server name, ports, interfaces, game settings |
|
||||
| `server/conf/at_server_startstop.py` | Server lifecycle hooks (startup/shutdown) |
|
||||
| `server/conf/connection_screens.py` | Login/connection screen text |
|
||||
| `commands/default_cmdsets.py` | Registers all custom commands with Evennia |
|
||||
| `world/rebuild_world.py` | Rebuilds all rooms from source |
|
||||
| `world/build_academy.ev` | Evennia batch script for initial world setup |
|
||||
| `game.py` | Main game engine (GameEngine, PlayerInterface) |
|
||||
| `world/game.py` | World model (World, Room, NPC, ActionSystem) |
|
||||
| `play_200.py` | Training scenario and demo actions |
|
||||
### 1. Evennia server startup
|
||||
Primary operational entry point for the networked world:
|
||||
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
|
||||
Grounding:
|
||||
- `evennia/timmy_world/README.md`
|
||||
- `evennia/timmy_world/server/conf/settings.py`
|
||||
|
||||
### 2. Web routing
|
||||
`evennia/timmy_world/web/urls.py` is the browser-facing entry point. It includes:
|
||||
- `web.website.urls`
|
||||
- `web.webclient.urls`
|
||||
- `web.admin.urls`
|
||||
- `evennia.web.urls` appended after the local patterns
|
||||
|
||||
This means the effective surface inherits Evennia defaults rather than defining a custom Tower web application.
|
||||
|
||||
### 3. Standalone simulation module
|
||||
`evennia/timmy_world/game.py` is a pure-Python entry point with:
|
||||
- `NARRATIVE_PHASES`
|
||||
- `get_narrative_phase()`
|
||||
- `get_phase_transition_event()`
|
||||
- `World`
|
||||
- `ActionSystem`
|
||||
- `NPCAI`
|
||||
- `GameEngine`
|
||||
- `PlayerInterface`
|
||||
|
||||
This module can be imported and exercised without an Evennia runtime.
|
||||
|
||||
### 4. Alternate simulation module
|
||||
`evennia/timmy_world/world/game.py` mirrors much of the same gameplay stack, but is not the one used by `play_200.py`.
|
||||
|
||||
Important distinction:
|
||||
- root `game.py` is the active scripted demo target
|
||||
- `world/game.py` is a second engine implementation with overlapping responsibilities
|
||||
|
||||
### 5. Scripted narrative demo
|
||||
`evennia/timmy_world/play_200.py` runs 200 deterministic ticks and prints a story arc across four named phases:
|
||||
- Quietus
|
||||
- Fracture
|
||||
- Breaking
|
||||
- Mending
|
||||
|
||||
This file is the clearest executable artifact proving how the simulator is intended to be consumed outside Evennia.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
In a deployed environment, the unpacked code is typically found at `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
Player connects (telnet/web)
|
||||
-> Evennia Portal accepts connection
|
||||
-> Server authenticates (Account typeclass)
|
||||
-> Player puppets a Character
|
||||
-> Character enters world (Room typeclass)
|
||||
-> Commands processed through Command typeclass
|
||||
-> AuditedCharacter logs every action
|
||||
-> World responds with rich text + atmosphere data
|
||||
```
|
||||
### Networked Evennia path
|
||||
1. Client connects via telnet or browser.
|
||||
2. Evennia loads settings from `server/conf/settings.py`.
|
||||
3. Command set resolution flows through `commands/default_cmdsets.py`.
|
||||
4. Typeclass objects resolve through `typeclasses/accounts.py`, `typeclasses/characters.py`, `typeclasses/rooms.py`, `typeclasses/exits.py`, `typeclasses/objects.py`, and `typeclasses/scripts.py`.
|
||||
5. URL dispatch flows through `web/urls.py` into website, webclient, admin, and Evennia default URL patterns.
|
||||
6. Object/help/prototype metadata can be sourced from `world/prototypes.py` and `world/help_entries.py`.
|
||||
|
||||
### Standalone Tower simulation path
|
||||
1. Operator imports `evennia/timmy_world/game.py` directly or runs `evennia/timmy_world/play_200.py`.
|
||||
2. `GameEngine.start_new_game()` initializes the world state.
|
||||
3. `PlayerInterface.get_available_actions()` exposes current verbs from room topology and nearby characters.
|
||||
4. `GameEngine.run_tick()` / `play_turn()` advances time, movement, world events, NPC actions, and logs.
|
||||
5. `World` tracks rooms, characters, trust, weather, forge/garden/bridge/tower state, and narrative phase.
|
||||
6. Persistence writes to JSON/log files rooted at `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
|
||||
### Evidence of the persistence contract
|
||||
Both simulation modules hardcode the same portability-sensitive base path:
|
||||
- `evennia/timmy_world/game.py`
|
||||
- `evennia/timmy_world/world/game.py`
|
||||
|
||||
Each defines:
|
||||
- `WORLD_DIR = Path('/Users/apayne/.timmy/evennia/timmy_world')`
|
||||
- `STATE_FILE = WORLD_DIR / 'game_state.json'`
|
||||
- `TIMMY_LOG = WORLD_DIR / 'timmy_log.md'`
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### Typeclasses (the world model)
|
||||
### `World` — state container for the Tower
|
||||
Found in both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
|
||||
| Class | File | Purpose |
|
||||
|-------|------|---------|
|
||||
| `Character` | `typeclasses/characters.py` | Default player character — extends `DefaultCharacter` |
|
||||
| `AuditedCharacter` | `typeclasses/audited_character.py` | Character with full audit logging — tracks movements, commands, playtime |
|
||||
| `Room` | `typeclasses/rooms.py` | Default room container |
|
||||
| `Exit` | `typeclasses/exits.py` | Connections between rooms |
|
||||
| `Object` | `typeclasses/objects.py` | Base object with `ObjectParent` mixin |
|
||||
| `Account` | `typeclasses/accounts.py` | Player account (login identity) |
|
||||
| `Channel` | `typeclasses/channels.py` | In-game communication channels |
|
||||
| `Script` | `typeclasses/scripts.py` | Background/timed processes |
|
||||
Responsibilities:
|
||||
- defines the five-room map: Threshold, Tower, Forge, Garden, Bridge
|
||||
- stores per-room connections and dynamic state
|
||||
- stores per-character room, energy, trust, goals, memories, and inventory
|
||||
- tracks global pressure variables like `forge_fire_dying`, `garden_drought`, `bridge_flooding`, and `tower_power_low`
|
||||
- updates world time and environmental drift each tick
|
||||
|
||||
### AuditedCharacter — the flagship typeclass
|
||||
### `ActionSystem`
|
||||
Also present in both engine files.
|
||||
|
||||
The `AuditedCharacter` is the most important abstraction. It wraps every player action in logging:
|
||||
Responsibilities:
|
||||
- enumerates available verbs
|
||||
- computes contextual action menus from world state
|
||||
- ties actions to energy cost and room/character context
|
||||
|
||||
- `at_pre_move()` — logs departure from current room
|
||||
- `at_post_move()` — records arrival with timestamp and coordinates
|
||||
- `at_pre_cmd()` — increments command counter, logs command + args
|
||||
- `at_pre_puppet()` — starts session timer
|
||||
- `at_post_unpuppet()` — calculates session duration, updates total playtime
|
||||
- `get_audit_summary()` — returns JSON summary of all tracked metrics
|
||||
### `NPCAI`
|
||||
The non-player decision layer.
|
||||
|
||||
Audit trail keeps last 1000 movements in `db.location_history`. Sensitive commands (password) are excluded from logging.
|
||||
Responsibilities:
|
||||
- chooses actions based on each character's goals and situation
|
||||
- creates world motion without requiring live operator input
|
||||
- in `world/game.py`, works alongside `DialogueSystem`
|
||||
|
||||
### Commands (the player interface)
|
||||
### `GameEngine`
|
||||
The orchestration layer.
|
||||
|
||||
Command implementations are covered by integration tests (see `tests/test_evennia_local_world_game.py`) and auto-generated unit tests (`tests/test_genome_generated.py`).
|
||||
Responsibilities:
|
||||
- bootstraps a fresh run with `start_new_game()`
|
||||
- rehydrates from storage via `load_game()`
|
||||
- advances the simulation with `run_tick()` / `play_turn()`
|
||||
- records log entries and world events
|
||||
|
||||
| Command | Aliases | Purpose |
|
||||
|---------|---------|---------|
|
||||
| `examine` | `ex`, `exam` | Inspect room or object — shows description, atmosphere, objects, contents |
|
||||
| `rooms` | — | List all rooms with wing color coding |
|
||||
| `@status` | `status` | Show agent status: location, wing, mood, online players, uptime |
|
||||
| `@map` | `map` | ASCII map of current wing |
|
||||
| `@academy` | `academy` | Full academy overview with room counts |
|
||||
| `smell` | `sniff` | Perceive room through atmosphere scent data |
|
||||
| `listen` | `hear` | Perceive room through atmosphere sound data |
|
||||
| `@who` | `who` | Show connected players with locations and idle time |
|
||||
Grounded interface details from live import of `evennia/timmy_world/game.py`:
|
||||
- methods visible on the instance: `load_game`, `log`, `play_turn`, `run_tick`, `start_new_game`
|
||||
- `play_turn('look')` returns a dict with keys:
|
||||
- `tick`
|
||||
- `time`
|
||||
- `phase`
|
||||
- `phase_name`
|
||||
- `timmy_room`
|
||||
- `timmy_energy`
|
||||
- `room_desc`
|
||||
- `here`
|
||||
- `world_events`
|
||||
- `npc_actions`
|
||||
- `choices`
|
||||
- `log`
|
||||
|
||||
### World Structure (5 wings, 21+ rooms)
|
||||
### `PlayerInterface`
|
||||
A thin operator-facing adapter.
|
||||
|
||||
**Central Hub (LIMBO)** — Nexus connecting all wings. North=Dormitory, South=Workshop, East=Commons, West=Gardens.
|
||||
Grounded behavior:
|
||||
- when loaded from `evennia/timmy_world/game.py` after `start_new_game()`, `PlayerInterface(engine).get_available_actions()` exposes room navigation and social verbs like:
|
||||
- `move:north -> Tower`
|
||||
- `move:east -> Garden`
|
||||
- `move:west -> Forge`
|
||||
- `move:south -> Bridge`
|
||||
- `speak:Allegro`
|
||||
- `speak:Claude`
|
||||
- `rest`
|
||||
|
||||
**Dormitory Wing** — Master Suites, Corridor, Novice Hall, Residential Services, Dorm Entrance.
|
||||
### Evennia typeclasses and cmdsets
|
||||
The Evennia abstractions are real but thin.
|
||||
|
||||
**Commons Wing** — Grand Commons Hall (main gathering, 60ft ceilings, marble columns), Hearthside Dining, Entertainment Gallery, Scholar's Corner, Upper Balcony.
|
||||
Notable files:
|
||||
- `evennia/timmy_world/typeclasses/objects.py`
|
||||
- `evennia/timmy_world/typeclasses/characters.py`
|
||||
- `evennia/timmy_world/typeclasses/rooms.py`
|
||||
- `evennia/timmy_world/typeclasses/exits.py`
|
||||
- `evennia/timmy_world/typeclasses/accounts.py`
|
||||
- `evennia/timmy_world/typeclasses/scripts.py`
|
||||
- `evennia/timmy_world/commands/command.py`
|
||||
- `evennia/timmy_world/commands/default_cmdsets.py`
|
||||
|
||||
**Workshop Wing** — Great Smithy, Alchemy Labs, Woodworking Shop, Artificing Chamber, Workshop Entrance.
|
||||
|
||||
**Gardens Wing** — Enchanted Grove, Herb Gardens, Greenhouse, Sacred Grove, Gardens Entrance.
|
||||
|
||||
Each room has rich `db.atmosphere` data: mood, lighting, sounds, smells, temperature.
|
||||
Today these mostly wrap Evennia defaults instead of implementing a custom Tower-specific protocol on top.
|
||||
|
||||
## API Surface
|
||||
|
||||
### Web API
|
||||
### Network surfaces
|
||||
Grounded from `README.md`, `web/urls.py`, and `server/conf/mssp.py`:
|
||||
- Telnet on port `4000`
|
||||
- Browser / webclient on `http://localhost:4001`
|
||||
- admin surface under `/admin/`
|
||||
- Evennia default URLs appended via `evennia.web.urls`
|
||||
- Evennia REST/web surface inherits the default `/api/` patterns rather than defining custom project-specific endpoints here
|
||||
|
||||
- `web/api/__init__.py` — Evennia REST API (Django REST Framework)
|
||||
- `web/urls.py` — URL routing for web interface
|
||||
- `web/admin/` — Django admin interface
|
||||
- `web/website/` — Web frontend
|
||||
### Operator / script surfaces
|
||||
- `python3 evennia/timmy_world/play_200.py`
|
||||
- importable pure-Python engine in `evennia/timmy_world/game.py`
|
||||
- alternate engine in `evennia/timmy_world/world/game.py`
|
||||
|
||||
### Telnet
|
||||
|
||||
- Standard MUD protocol on port 4000
|
||||
- Supports MCCP (compression), MSDP (data), GMCP (protocol)
|
||||
|
||||
### Hermes Bridge
|
||||
|
||||
- `hermes-agent/config.yaml` — Configuration for AI agent connection
|
||||
- Allows Hermes agents to connect as characters and interact with the world
|
||||
|
||||
## Dependencies
|
||||
|
||||
No `requirements.txt` or `pyproject.toml` found. Dependencies come from Evennia:
|
||||
|
||||
- **evennia** — MUD framework (Django-based)
|
||||
- **django** — Web framework (via Evennia)
|
||||
- **twisted** — Async networking (via Evennia)
|
||||
### Content/model surfaces
|
||||
- object prototype definitions: `evennia/timmy_world/world/prototypes.py`
|
||||
- file-based help entries: `evennia/timmy_world/world/help_entries.py`
|
||||
|
||||
## Test Coverage Gaps
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Source modules | 35 |
|
||||
| Test modules | 1 |
|
||||
| Estimated coverage | 0% |
|
||||
| Untested modules | 35 |
|
||||
### Current verified state
|
||||
The original genome here was stale. The live repo now shows two different categories of test coverage:
|
||||
|
||||
The academy test suite includes:
|
||||
- `tests/test_evennia_local_world_game.py` — live game integration
|
||||
- `tests/test_genome_generated.py` — auto-generated unit test stubs
|
||||
- `tests/test_evennia_local_world_genome.py` — validates this GENOME document
|
||||
- `tests/test_bezalel_evennia_layout.py` — spatial layout verification
|
||||
- `tests/test_evennia_mind_palace.py` — memory palace integration
|
||||
- `tests/test_evennia_telemetry.py` — event logging
|
||||
- `tests/test_evennia_training.py` — training workflow validation
|
||||
- `tests/test_evennia_vps_repair.py` — VPS repair script checks
|
||||
Additionally, **19 skipped** due to optional dependencies (e.g., Evennia not installed in the test environment).
|
||||
1. Host-repo generated tests already exist in `tests/test_genome_generated.py`
|
||||
- they reference `evennia/timmy_world/game.py`
|
||||
- they reference `evennia/timmy_world/world/game.py`
|
||||
- they reference `server/conf/web_plugins.py`
|
||||
2. Those generated tests are not trustworthy as-is for this target
|
||||
- running `python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs`
|
||||
- result: `19 skipped, 31 deselected`
|
||||
- skip reason on every case: `Module not importable`
|
||||
|
||||
### Critical Untested Paths
|
||||
This matters because the codebase-genome pipeline reported zero local tests for the subproject, but the host repo does contain tests. The real issue is not “no tests exist.” The real issue is “the existing generated tests are disconnected from the actual import path and therefore do not execute the critical path.”
|
||||
|
||||
1. **AuditedCharacter** — audit logging is the primary value-add. No tests verify movement tracking, command counting, or playtime calculation.
|
||||
2. **Commands** — no tests for any of the 8 commands. The `@map` wing detection, `@who` session tracking, and atmosphere-based commands (`smell`, `listen`) are all untested.
|
||||
3. **World rebuild** — `rebuild_world.py` and `fix_world.py` can destroy and recreate the entire world. No tests ensure they produce valid output.
|
||||
4. **Typeclass hooks** — `at_pre_move`, `at_post_move`, `at_pre_cmd` etc. are never tested in isolation.
|
||||
### New critical-path tests added for #677
|
||||
This issue refresh adds a dedicated executable test file:
|
||||
- `tests/test_evennia_local_world_game.py`
|
||||
|
||||
Covered behaviors:
|
||||
- narrative phase boundaries across Quietus / Fracture / Breaking / Mending
|
||||
- player-facing action surface from the Threshold start state
|
||||
- deterministic `run_tick('move:north')` flow into the Tower with expected log and world-event output
|
||||
|
||||
### Genome artifact coverage added for #677
|
||||
This issue refresh also adds:
|
||||
- `tests/test_evennia_local_world_genome.py`
|
||||
|
||||
That test locks:
|
||||
- artifact path
|
||||
- required analysis sections
|
||||
- grounded snippets for real files and verification output
|
||||
|
||||
### Remaining gaps
|
||||
Still missing strong runtime coverage for:
|
||||
- Evennia typeclass behavior under a real Evennia test harness
|
||||
- URL routing under Django/Evennia integration
|
||||
- `world/game.py` parity versus root `game.py`
|
||||
- persistence portability around `/Users/apayne/.timmy/evennia/timmy_world`
|
||||
- `at_initial_setup.py` and `world/batch_cmds.ev` actually building a playable world in the Evennia path
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- ⚠️ Uses `eval()`/`exec()` — Evennia's inlinefuncs module uses eval for dynamic command evaluation. Risk level: inherent to MUD framework.
|
||||
- ⚠️ References secrets/passwords — `settings.py` references `secret_settings.py` for sensitive config. Ensure this file is not committed.
|
||||
- ⚠️ Telnet on 0.0.0.0 — server accepts connections from any IP. Consider firewall rules.
|
||||
- ⚠️ Web client on 0.0.0.0 — same exposure as telnet. Ensure authentication is enforced.
|
||||
- ⚠️ Agent bridge (`hermes-agent/config.yaml`) — verify credentials are not hardcoded.
|
||||
1. Plaintext telnet exposure
|
||||
- `server/conf/mssp.py` advertises port `4000`
|
||||
- telnet is unencrypted by default
|
||||
- acceptable for localhost/dev, risky for exposed deployment
|
||||
|
||||
2. Hardcoded absolute persistence path
|
||||
- both `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py` hardcode `/Users/apayne/.timmy/evennia/timmy_world`
|
||||
- this couples runtime writes to one operator machine and one home-directory layout
|
||||
- portability and accidental overwrite risk are both real
|
||||
- filed follow-up: `timmy-home #831` — `https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/831`
|
||||
|
||||
3. Admin/web surfaces inherit defaults
|
||||
- `web/urls.py` exposes admin and Evennia defaults
|
||||
- if the service is made remotely reachable, Django/Evennia auth and proxy boundaries matter immediately
|
||||
|
||||
4. Secret handling is externalized but optional
|
||||
- `server/conf/settings.py` silently falls back if `secret_settings.py` is missing
|
||||
- convenient for local development, but secrets discipline lives outside the repo contract
|
||||
|
||||
5. Template hooks can hide missing security posture
|
||||
- `server/conf/web_plugins.py` is pass-through
|
||||
- `server/conf/at_initial_setup.py` is pass-through
|
||||
- the absence of custom code here means there are no local hardening hooks yet for startup, proxying, or world bootstrap
|
||||
|
||||
## Dependencies
|
||||
|
||||
Directly evidenced imports and framework coupling:
|
||||
- Evennia 6.0 game-directory structure
|
||||
- Django via Evennia web/admin stack
|
||||
- Twisted via Evennia networking/web hooks
|
||||
- Python stdlib heavy use in standalone simulator:
|
||||
- `json`
|
||||
- `time`
|
||||
- `os`
|
||||
- `random`
|
||||
- `datetime`
|
||||
- `pathlib`
|
||||
- `sys`
|
||||
|
||||
Dependency caveat:
|
||||
- the standalone Tower simulator is largely pure Python and importable in isolation
|
||||
- the typeclass / cmdset / web files depend on Evennia and Django runtime wiring to do real work
|
||||
|
||||
## Deployment
|
||||
|
||||
Timmy Academy runs as an Evennia world on dedicated VPS and localhost.
|
||||
### Evennia path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
evennia migrate
|
||||
evennia start
|
||||
```
|
||||
|
||||
**Production (Bezalel VPS)** — telnet on port 4000, web client on 4001:
|
||||
- Telnet: `telnet 167.99.126.228 4000`
|
||||
- Web: `http://167.99.126.228:4001`
|
||||
Expected local surfaces from repo docs/config:
|
||||
- telnet: `localhost:4000`
|
||||
- browser/webclient: `http://localhost:4001`
|
||||
|
||||
**Local development** — clone and run `evennia start --name timmy_world` from `evennia/timmy_world/`. The default runtime path is `/Users/apayne/.timmy/evennia/timmy_world`.
|
||||
### Standalone simulation path
|
||||
```bash
|
||||
cd evennia/timmy_world
|
||||
python3 play_200.py
|
||||
```
|
||||
|
||||
**Hermes bridge** — AI agents connect via the `hermes-agent` bridge, configured in `hermes-agent/config.yaml` to point at the local Evennia socket.
|
||||
This does not require the full Evennia network stack. It exercises the root `game.py` engine directly.
|
||||
|
||||
## Configuration Files
|
||||
### Verification commands run for this genome refresh
|
||||
```bash
|
||||
python3 ~/.hermes/pipelines/codebase-genome.py --path /tmp/BURN-7-7/evennia/timmy_world --output /tmp/evennia-local-world-GENOME-base.md
|
||||
python3 -m pytest tests/test_genome_generated.py -k 'EvenniaTimmyWorld' -q -rs
|
||||
python3 -m pytest tests/test_evennia_local_world_genome.py tests/test_evennia_local_world_game.py -q
|
||||
python3 -m py_compile evennia/timmy_world/game.py evennia/timmy_world/world/game.py evennia/timmy_world/play_200.py evennia/timmy_world/server/conf/settings.py evennia/timmy_world/web/urls.py
|
||||
```
|
||||
|
||||
- `server/conf/settings.py` — Main Evennia settings (server name, ports, typeclass paths)
|
||||
- `hermes-agent/config.yaml` — Hermes agent bridge configuration
|
||||
- `world/build_academy.ev` — Evennia batch build script
|
||||
- `world/batch_cmds.ev` — Batch command definitions
|
||||
## Key Findings
|
||||
|
||||
## What's Missing
|
||||
|
||||
1. **Tests** — 0% coverage is a critical gap. Priority: AuditedCharacter hooks, command func() methods, world rebuild integrity.
|
||||
2. **CI/CD** — No automated testing pipeline. No GitHub Actions or Gitea workflows.
|
||||
3. **Documentation** — `world/BUILDER_GUIDE.md` exists but no developer onboarding docs.
|
||||
4. **Monitoring** — No health checks, no metrics export, no alerting on server crashes.
|
||||
5. **Backup** — No automated database backup for the Evennia SQLite/PostgreSQL database.
|
||||
1. The current custom product logic is the standalone Tower simulator, not the Evennia typeclass layer.
|
||||
2. The repo contains two parallel simulation engines: `evennia/timmy_world/game.py` and `evennia/timmy_world/world/game.py`.
|
||||
3. The stock Evennia scaffolding is still mostly template code (`README.md`, `at_initial_setup.py`, `world/batch_cmds.ev`, pass-through cmdsets/web hooks).
|
||||
4. The codebase-genome pipeline undercounted test reality because subproject-local tests are absent while host-repo tests exist one level up.
|
||||
5. The existing generated tests were present but functionally inert: `19 skipped` because their import path does not match the current host-repo layout.
|
||||
6. The most concrete portability hazard is the hardcoded `/Users/apayne/.timmy/evennia/timmy_world` state path in both simulation engines.
|
||||
|
||||
---
|
||||
|
||||
*Generated by Codebase Genome Pipeline. Review and update manually.*
|
||||
This refreshed genome supersedes the earlier auto-generated `evennia/timmy_world/GENOME.md` summary by grounding the analysis in live source inspection, live import of `evennia/timmy_world/game.py`, current file metrics, and executable host-repo verification.
|
||||
@@ -8,6 +8,7 @@ ROOT = Path(__file__).resolve().parents[1]
|
||||
PIPELINE_PATH = ROOT / "pipelines" / "codebase_genome.py"
|
||||
NIGHTLY_PATH = ROOT / "scripts" / "codebase_genome_nightly.py"
|
||||
GENOME_PATH = ROOT / "GENOME.md"
|
||||
CRON_PATH = ROOT / "codebase_genome_cron.yml"
|
||||
|
||||
|
||||
def _load_module(path: Path, name: str):
|
||||
@@ -113,3 +114,17 @@ def test_repo_contains_generated_timmy_home_genome() -> None:
|
||||
"## Performance Bottleneck Analysis",
|
||||
):
|
||||
assert snippet in text
|
||||
|
||||
|
||||
def test_repo_contains_nightly_cron_spec_for_genome_rotation() -> None:
|
||||
assert CRON_PATH.exists(), "missing codebase_genome_cron.yml"
|
||||
text = CRON_PATH.read_text(encoding="utf-8")
|
||||
for snippet in (
|
||||
"Codebase Genome Nightly",
|
||||
"scripts/codebase_genome_nightly.py",
|
||||
"--org Timmy_Foundation",
|
||||
"--workspace-root",
|
||||
"--output-root",
|
||||
"--state-path",
|
||||
):
|
||||
assert snippet in text
|
||||
|
||||
Reference in New Issue
Block a user