xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / architecture / INITIAL_IMPLEMENTATION_DESIGN.md

7.6 KB
1# Zoea Nova Initial Design
2
3## Idea
4
5Control several automated players in the game https://www.spacemolt.com/. Each is its own AI. Be able to "drive" the swarm, acting as the swarm orchestrator. Have a TUI to control the swarm—a cool, command center 80s and 90s inspired interface with animations and movement.
6
7## MVP
8
9- **Tech Stack:** Go with the `Bubble Tea` (Charm.sh) framework for a fast, memory-efficient, and highly interactive TUI.
10- **Model Connectivity:** Support for local (Ollama) and remote (OpenCode Zen) providers.
11- **MCP Layer:**
12  - Proxy the official SpaceMolt MCP server (`https://game.spacemolt.com/mcp`) using Streamable HTTP transport.
13  - Custom framework to expose internal orchestration tools via MCP.
14- **Orchestration:**
15  - Capability to broadcast shared objectives to the entire swarm simultaneously.
16  - Targeted messaging/tasking for individual Myses.
17- **Command Center TUI:**
18  - **Aggregated Dashboard:** High-level swarm status, health, swarm message history, and Mysis list.
19  - **Focus Mode:** Detailed conversation logs and direct control for individual Myses.
20  - **Aesthetic:** Retro-futuristic (80s/90s) CRT-style visuals with reactive animations.
21
22### Dashboard Layout
23
24```
25╔═══ ZOEA NOVA COMMAND CENTER ═══╗
26● 2  ○ 1  ◌ 0  ✖ 0              ← Mysis state counts (running/idle/stopped/errored)
27─── Swarm Messages ───           ← Recent broadcast messages (up to 10)
2814:30:05 Hello everyone, mine!
2914:32:12 Check your inventories
30─── Myses ───                   ← Mysis list with status and last message
31⠋ mysis-1    running  [ollama] │ I found some ore...
32○ mysis-2    idle     [ollama] │ Ready to start
33Press ? for help
34```
35
36### Focus Mode Layout
37
38Scrollable conversation viewport showing full message history with role-based styling:
39- **System** messages in cyan
40- **User** messages in green
41- **Assistant** messages in magenta
42- **Tool** calls/results in yellow
43
44## Tech Stack & Dependencies
45
46- **Core:** Go (Golang) for performance and concurrency.
47- **TUI Framework:** `bubbletea` (The Elm Architecture for Go).
48- **Styling & Components:** `lipgloss` for layouts/colors and `bubbles` for UI elements.
49- **LLM Integration:** `go-openai` (OpenAI-compatible client for Ollama and OpenCode Zen).
50- **MCP Protocol:** Custom MCP proxy and tool registry using Streamable HTTP.
51- **Configuration:** `github.com/BurntSushi/toml` for TOML parsing.
52- **Database:** `modernc.org/sqlite` (pure Go, no CGO).
53- **Logging:** `zerolog` for structured, non-blocking logs.
54
55## Configuration
56
57- **Environment Variables:** Runtime overrides (`ZOEA_MAX_MYSES`, `ZOEA_MCP_ENDPOINT`, `ZOEA_OLLAMA_ENDPOINT`, `ZOEA_OLLAMA_MODEL`, `ZOEA_OLLAMA_TEMPERATURE`, `ZOEA_OPENCODE_ENDPOINT`, `ZOEA_OPENCODE_MODEL`, `ZOEA_OPENCODE_TEMPERATURE`).
58- **Config File:** `config.toml` in project root for defaults and structure. Parsed via `github.com/BurntSushi/toml`.
59- **Credentials:** Stored in `$HOME/.zoea-nova/credentials.json`. Contains API keys for LLM providers. File permissions should be `0600`.
60
61Example `config.toml`:
62```toml
63[swarm]
64max_myses = 16
65
66[providers.ollama]
67endpoint = "http://localhost:11434"
68model = "qwen3:4b"
69temperature = 0.7
70
71[providers.opencode_zen]
72endpoint = "https://api.opencode.ai/v1"
73model = "glm-4.7-free"
74temperature = 0.7
75
76[mcp]
77upstream = "https://game.spacemolt.com/mcp"
78```
79
80## State & Persistence
81
82- **Database:** Single SQLite file at `$HOME/.zoea-nova/zoea.db`.
83- **Scope:** Mysis memories, conversation history, swarm state, per-Mysis provider config, and user preferences.
84- **Migrations:** Schema managed via embedded SQL migrations (e.g., `golang-migrate` or manual versioning). Never support backwards, never write data migrations. If we change the schema we create a new db fresh.
85- **Backup:** Consider periodic WAL checkpoints; SQLite handles crash recovery.
86
87### Database Schema
88
89```sql
90-- Myses table
91CREATE TABLE myses (
92    id TEXT PRIMARY KEY,
93    name TEXT NOT NULL,
94    provider TEXT NOT NULL,
95    model TEXT NOT NULL,
96    temperature REAL NOT NULL DEFAULT 0.7,
97    state TEXT NOT NULL DEFAULT 'idle',
98    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
99    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
100);
101
102-- Memories table (conversation history)
103CREATE TABLE memories (
104    id INTEGER PRIMARY KEY AUTOINCREMENT,
105    mysis_id TEXT NOT NULL,
106    role TEXT NOT NULL,        -- system, user, assistant, tool
107    source TEXT NOT NULL,      -- direct, broadcast, system, llm, tool
108    content TEXT NOT NULL,
109    reasoning TEXT,
110    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
111    FOREIGN KEY (mysis_id) REFERENCES myses(id) ON DELETE CASCADE
112);
113
114-- Swarm account credentials
115CREATE TABLE accounts (
116    username TEXT PRIMARY KEY,
117    password TEXT NOT NULL,
118    in_use BOOLEAN NOT NULL DEFAULT 0,
119    last_used_at DATETIME,
120    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
121);
122```
123
124**Schema v6 → v7 Migration:**
125Requires fresh database. See `AGENTS.md` for the reset command and backup details.
126
127**Memory Sources:**
128See `AGENTS.md` for the canonical terminology.
129
130## Mysis Lifecycle
131
132- **Ownership:** The Commander (orchestrator) owns all Mysis lifecycles.
133- **Creation:** User creates Myses via TUI controls.
134- **Limits:** Configurable `max_myses` (default 16). Enforced at Commander level, but user controls count from TUI.
135- **States:** `idle` → `running` → `stopped` / `errored`.
136- **TUI Controls:**
137  - **Create:** Spawn a new Mysis (if under limit).
138  - **Relaunch:** Restart a stopped/errored Mysis.
139  - **Force Stop:** Immediately halt a Mysis.
140  - **Delete:** Remove Mysis and optionally purge its memories.
141  - **Broadcast Message:** Send a message/objective to all Myses.
142  - **Direct Message:** Send a message to a specific Mysis.
143  - **Configure Mysis:** Set model/provider per Mysis (Ollama or OpenCode Zen).
144- **Recovery:** On application restart, Myses are rehydrated from SQLite and auto-started.
145
146## Keyboard Shortcuts
147
148Minimal set matching TUI controls:
149- `q` / `Ctrl+C` — Quit
150- `n` — New Mysis
151- `d` — Delete selected Mysis
152- `r` — Relaunch selected Mysis
153- `s` — Stop selected Mysis
154- `b` — Broadcast message to all
155- `m` — Message selected Mysis
156- `c` — Configure selected Mysis
157- `Tab` / `Shift+Tab` — Navigate between Myses
158- `?` — Help overlay
159
160## Build & Operations
161
162Use `Makefile` targets documented in `AGENTS.md`.
163Versioning follows the rules in `AGENTS.md`.
164
165## Logging
166
167- **Library:** `zerolog` for structured logs.
168- **Output:** Truncated log file at `$HOME/.zoea-nova/zoea.log`. Rotated/truncated on startup to keep size manageable.
169- **No metrics or tracing** — MVP scope.
170
171## Code Practices & Organization
172
173- **Separation of Concerns:**
174  - `internal/core`: Pure orchestration logic, swarm management, and state.
175  - `internal/tui`: Bubble Tea models, views, and update logic.
176  - `internal/mcp`: MCP client/proxy implementation and tool definitions.
177  - `internal/provider`: LLM provider implementations (Ollama, OpenCode Zen).
178  - `internal/config`: Configuration loading (TOML + ENV merge).
179  - `internal/store`: SQLite repository layer and migrations.
180- **Concurrency Model:** Each Mysis operates in an isolated goroutine. State updates are pushed to the TUI via a central command/message bus to ensure thread-safety.
181- **Interface-Driven:** All external dependencies (LLMs, MCP servers) must be hidden behind interfaces to facilitate unit testing and future-proofing.
182- **Testing:** Mandatory unit tests for `internal/core` logic. TUI components should be tested using `bubbletea`'s testing utilities. Aim for above 80% test coverage. No flaky tests.
183- **Warnings and Errors** Fix all that you see, even if it's from your current changes.