Phase 20: Federowana Architektura Botów

Arc OS — od „jednego biura" do „centrum dowodzenia dla wszystkich projektów" Autor: Rick (Lead Architect) | Data: 2026-04-02 Status: 20.1–20.5 UKOŃCZONE Zatwierdzone przez: CEO

Problem

CEO zarządza wieloma projektami (Arc OS, Msolution, RTS_001) z telefonu. Bieżąca architektura: jeden bot Telegram → jedna sesja Claude → jedno okno kontekstu. To się sypie przy 3+ projektach:

• Zanieczyszczenie okna kontekstu (200K tokenów współdzielonych między niepowiązanymi projektami)
• Brak izolacji projektów (kod msolution przecieka do promptów citadel)
• Brak możliwości multi-user (nie można zaprosić designera do czatu projektu)
• Zepsuty kontekst odpowiedzi (odpowiedź na wiadomość z złego projektu = chaos)

Rozwiązanie: Federacja

CEO ↔ @citadel_master_bot (Master)          ← tylko globalne komendy
       │
       ├── /status          → odpytuje wszystkie dzieci
       ├── /emergency-stop  → sygnał kill do wszystkich
       ├── /deploy all      → kaskadowy deploy
       │
       ├── @citadel_v2_bot (Child 1)         ← osobny czat, osobny kontekst
       │    └── sesja Claude #1, cwd=/opt/repos/citadel-v2
       │
       ├── @msolution_bot (Child 2)          ← można dodać designera do czatu
       │    └── sesja Claude #2, cwd=/opt/repos/msol
       │
       └── @rts_bot (Child 3)               ← można dodać agenta Morty
            └── sesja Claude #3, cwd=/opt/repos/rts-001

Analiza decyzji: Jeden bot vs Federacja

Opcja A: Jeden bot + przełącznik projektów

Werdykt: Działa dla samotnego CEO z 1–2 projektami. Sypie się przy 3+.

Opcja B: Federacja botów (Master + Dzieci) — WYBRANA

Werdykt: Właściwe rozwiązanie. Większa złożoność infrastruktury, ale rozwiązuje WSZYSTKIE problemy.

Dlaczego Federacja wygrywa

1. Izolacja kontekstu — czynnik decydujący. Jedna sesja Claude dla 3+ projektów = przepełnienie kontekstu w 30 minut aktywnej pracy. Federacja daje każdemu projektowi czyste 200K tokenów.
2. Gotowość na multi-user — to nie „przyszła funkcja", to fundament. Bez tego Arc OS nie może stać się produktem.
3. Odpowiedź = natywny RAG — Telegram już rozwiązał problem kontekstu. My tylko mapujemy odpowiedź → prompt GSD.

Architektura Emergency Stop

CEO naciska /emergency-stop w czacie Mastera
        │
        ▼
Master Bot (Node.js/Bun, lekki, NIE sesja Claude)
        │
        ├── 1. Odczytaj config/bot_registry.json
        │      { "children": [
        │          { "name": "citadel-v2", "tmux": "citadel", ... },
        │          { "name": "msolution", "tmux": "msolution", ... }
        │      ]}
        │
        ├── 2. Dla każdego dziecka (równolegle):
        │      a) tmux send-keys -t $SESSION "C-c" Enter      ← łagodne: Ctrl+C
        │      b) sleep 2
        │      c) tmux send-keys -t $SESSION "/exit" Enter     ← jawne wyjście
        │      d) sleep 2
        │      e) tmux kill-session -t $SESSION                 ← wymuś kill jeśli nadal żyje
        │
        ├── 3. Zaktualizuj office-state.json: wszystkie agenty → idle
        │
        └── 4. Odpowiedz w czacie Mastera:
               "EMERGENCY STOP wykonany.
                citadel-v2: ZATRZYMANY (był: working on hooks)
                msolution: ZATRZYMANY (był: idle)
                Wszystkie agenty zresetowane do idle."

Protokół Kill (3 poziomy)

Failsafe

Zadanie cron co 5 minut sprawdza /tmp/emergency-stop.flag. Jeśli plik istnieje i jest świeży (<10 min), wykonuje sekwencję kill. Zabezpiecza przypadek, gdy sam Master Bot się zawiesił.

Smart Context Recall

Problem

CEO odpowiada na wiadomość sprzed 3 dni i pisze „zrób to samo, ale dla innego modułu". Claude nie ma pojęcia o tej wiadomości.

Rozwiązanie: Odpowiedź → Transformacja promptu GSD

Telegram Bot API dostarcza obiekt reply_to_message z pełnym oryginalnym tekstem.

CEO odpowiada na: "Wdrożyłem hooki na VPS, wszystko działa"
CEO pisze: "zrób to samo dla msolution"
        │
        ▼
Child Bot odbiera:
{
  "message": {
    "text": "zrób to samo dla msolution",
    "reply_to_message": {
      "text": "Wdrożyłem hooki na VPS, wszystko działa",
      "date": 1743580800,
      "message_id": 847
    }
  }
}
        │
        ▼
Bot buduje prompt GSD dla Claude:
┌─────────────────────────────────────┐
│ CONTEXT (z odpowiedzi):             │
│ > [2026-04-02] "Wdrożyłem hooki    │
│ > na VPS, wszystko działa"          │
│                                     │
│ TASK (nowa wiadomość):              │
│ "zrób to samo dla msolution"        │
│                                     │
│ PROJECT: msolution (z zakresu bota) │
└─────────────────────────────────────┘

Deep Recall (starsze wiadomości)

Warstwa 1: Historia wątku (szybka)
  Bot przechowuje ostatnie 50 wiadomości w state/thread_history.json per czat.
  Odpowiedź → bot znajduje oryginał → wstrzykuje do bloku CONTEXT.

Warstwa 2: Recall z biblioteki (fallback)
  Jeśli wiadomość nie ma w historii wątku (>50 wiad.) →
  bot uruchamia /citadel-recall z tekstem odpowiedzi →
  pobiera kontekst z library-export/ → wstrzykuje do promptu.

Przepływ: reply_to_message → thread_history → library-export/ → prompt GSD

Kluczowa zasada

Claude NIGDY nie wie bezpośrednio o odpowiedziach Telegram. Middleware bota ZAWSZE przekształca odpowiedź w czysty blok CONTEXT + TASK przed wysłaniem do sesji Claude.

Specyfikacja Master Bota

Czym Master Bot JEST

• Lekka usługa Bun/Node.js (~300 linii)
• Telegram Bot API (long-polling)
• Odczytuje config/bot_registry.json po rejestr dzieci
• Endpoint zdrowia HTTP: /api/master/health
• Kontener Docker w współdzielonym compose

Czym Master Bot NIE JEST

• NIE sesją Claude (bez AI, bez wywołań LLM)
• NIE proxy wiadomości (nie przekazuje wiadomości do dzieci)
• NIE magazynem stanu (odczytuje stan z plików dzieci)

Protokół Child Bota

Każdy child bot musi:

1. Rejestrować się w config/bot_registry.json przy starcie
2. Wysyłać heartbeat (co 60s) do Mastera przez plik: state/heartbeat_<nazwa>.json
3. Obsługiwać reply_to_message → wstrzykiwanie CONTEXT do GSD
4. Przechowywać ostatnie 50 wiadomości w state/thread_history.json
5. Reagować na sygnał emergency-stop (łagodne Ctrl+C → /exit → kill)
6. Używać strukturowanego loggera (shared/logger.ts) — logi do /var/log/citadel/<nazwa>/
7. Akceptować zmienną env BOT_NAME dla dynamicznego nazewnictwa
8. Udostępniać /api/child/health dla kontroli watchdoga

Szacowanie zasobów

Sub-fazy Phase 20

20.1 — Fundament Master Bota

• Bot Telegram Bun + TypeScript (long-polling)
• config/bot_registry.json — rejestr dzieci
• Komendy: /status, /emergency-stop, /list, /health
• Kontener Docker w docker/docker-compose.yml
• Endpoint zdrowia: /api/master/health
• Bez AI, bez sesji Claude — czysty orkiestrator

20.2 — Protokół Child Bota (Pierwsze dziecko)

• Zdefiniuj protokół rejestracji child bota
• Middleware wiadomości: reply_to_message → wstrzykiwanie CONTEXT do GSD
• Historia wątku: ostatnie 50 wiadomości w state/thread_history.json
• Protokół łagodnego wyłączenia (reakcja na emergency-stop)
• Pilot: migracja @citadel_v2_bot z Claude Channel do własnego bota
• Heartbeat do Mastera (co 60s przez plik)

20.3 — Silnik Onboardingu (DONE)

• /new_project <nazwa> — 4-krokowy interaktywny wywiad
• Dopasowywanie skilli (rejestr + biblioteka), wykrywanie blueprintów
• Auto-provisioning: katalogi, CLAUDE.md, MANIFEST.md, .env, rejestr, tmux

20.4 — Biblioteka Skilli i Usuwanie Projektów (DONE)

• /remove_project <nazwa> — potrójne potwierdzenie + chronione nazwy
• Library skille dopasowywane automatycznie i kopiowane podczas onboardingu
• Hook przeładowania rejestru dla aktualizacji in-memory

20.5 — Infrastruktura gotowa na Phantom (DONE)

• shared/logger.ts — strukturalne logowanie JSONL, dzienne dzielenie plików
• shared/vault.ts — zaszyfrowane sekrety AES-256-GCM (tokeny w vault, nie .env)
• master-bot/watchdog.ts — samoleczący monitor z eksponencjalnym backoffem
• Komenda /watchdog dla statusu dzieci w czasie rzeczywistym
• Config logrotate + skrypt konfiguracji VPS
• Wszystkie console.log → strukturowany logger

Komendy Master Bota (Finalne)

Poza zakresem (Phase 21+)

• Multi-tenancy SaaS (JWT, rozliczenia Stripe)
• Alternatywny pulpit webowy zamiast Telegrama
• Komendy głosowe przez Telegram
• Edytor sprite'ów agentów i personalizacja biura
• Mechanizm rotacji kluczy vault
• Monitorowanie zdrowia równorzędnych wielu VPS

Architektura Phase 20 autorstwa Ricka (Lead Architect). Fazy 20.1–20.5 ukończone. Zatwierdzone przez CEO 2026-04-02.