SolOS v2 — Complete System Architecture

One-line thesis: OpenCode supplies the runtime core and the human-facing surface; a thin SolOS Python layer owns the fleet (multi-agent mesh, memory, cost, registry, vault); Hermes is decommissioned and kept only as a pattern reference. Zero Hermes runtime dependency.

0. The substrate weighting (locked)

1. Complete system diagram

                    ┌──────────────────────────────────────────────────┐
                    │   HUMAN SURFACES  (reliable via OpenCode)        │
                    │   Telegram bots  ·  OpenCode Web (sol.youngle.au)│
                    └──────────────────────┬───────────────────────────┘
                                           │  (auth: username/password gate)
                    ┌──────────────────────▼───────────────────────────┐
                    │  OPENCODE RUNTIME  — 60% (the borrowed core)     │
                    │  · server + OpenAPI SDK  · session store          │
                    │  · provider routing (multi-model + fallbacks)     │
                    │  · tool chrome  · plugin system  · web chat UI    │
                    └──────────────────────┬───────────────────────────┘
                                           │  (plugin API — thin seam)
                    ┌──────────────────────▼───────────────────────────┐
                    │  SOLOS FLEET LAYER  — 30% (our Python)           │
                    │  ┌─────────────┬──────────────┬───────────────┐  │
                    │  │ MCP/plugin  │  Memory      │  CostGov      │  │
                    │  │ adapters    │  Plane       │  (sampling    │  │
                    │  │ 9 agents    │  (cross-     │   estimator)  │  │
                    │  │ as tools    │   agent)     │               │  │
                    │  └─────────────┴──────────────┴───────────────┘  │
                    │  · Registry (single source of truth)             │
                    │  · Vault  (~/.solos/docs = world model)           │
                    └──────────────────────┬───────────────────────────┘
                                           │
                    ┌──────────────────────▼───────────────────────────┐
                    │  DATA / PERSISTENCE                              │
                    │  solos.db (WAL, single DDL home) · vault mirror   │
                    │  docs.youngle.au (render) · pulse.youngle.au      │
                    └──────────────────────────────────────────────────┘

Direction of data flow: Human → OpenCode (sessions/providers) → SolOS MCP adapters (one per agent) → agent loop → memory plane (write) + CostGov (meter) + vault (register).

2. Component inventory (mapped to KEEP / MERGE / BUILD-NEW)

BUILD-NEW (the v2 spine)

• settings.py — one pydantic get_settings(); os.environ confined here (CI-enforced).
• migrations.py — ordered _schema_migrations runner, <50 LOC, forward-only.
• tests/ — 5 pytest tests mapped 1:1 to known bugs + CI hygiene grep-tests.
• OpenCode plugin adapters — one per agent, replacing the 8 FastAPI A2A servers.
• CI — ruff + strict mypy + pytest + import-linter + hygiene gates (bare GitHub Actions).

KEEP (mostly verbatim)

• memory_plane.py (129 LOC — the style benchmark), dispatch_tracker.py, persona_loader.py, event_bus.py, action_log.py, model_health.py, registry_client.py, gateway body, llm_core body.

MERGE

• agent_app.py (499 LOC) + session_manager.py → one agent loop.
• agent.py + agent_loop.py → one.
• 15 copy-paste provider URL sets → provider_config.

DIE

• 6 run_* variants, self_learning.py (731 LOC, off serving path), all *.backup* sprawl, dead chat_messages table, gateway _report_cost(0.001) fiction, the canned "Done. Ask me anything" empty-reply line, gateway_loop.py (replaced by OpenCode frontend).

3. Agent roster + topology (11 citizens)

4. Cross-cutting invariants (the "stable & reliable" contract)

1. One protocol — A2A message/send everywhere; agents reachable on A2A even when TG/Web is down.
2. One registry — single source of truth for agent identity, health, tasks.
3. CostGov before inference — meter every turn; sampling-based estimate, never a fictional constant.
4. Memory injected every turn — no orphaned memory plane (TAM-MEM-01/02 regression-tested).
5. Vault is the world model — every study registers to ~/.solos/docs, SHA-verified, auto-renders to docs.youngle.au.

5. Acceptance gates (measure by these, not by vibes)

• pytest green on every PR; except Exception count < 15 (from >100), each logged.
• Single CREATE TABLE home (db.py + migrations); WAL on solos.db.
• os.environ confined to settings.py (grep-enforced); zero credential files in tree.
• Reply text round-trips (empty-body A2A parse gap fixed).
• TG/Web reachability restored for all agents (the current single point of failure).

6. Migration path (no big-bang)

v2 runs alongside v1 ~4 weeks: copy-DB sidecar, per-agent feature-flag cutover (echo first, sol last), rollback = flag flip + git revert. Target ≤12 processes (vs ~35 today). First pilot = OpenCode-as-TG-frontend (restores reachability of all agents).