Arc OS — Przegląd Architektury

Ogólny opis

Arc OS zastępuje 11 321 linii niestandardowej infrastruktury Python/JS natywnymi narzędziami Claude Code. Agent AI staje się backendem.

Architektura systemu (Phase 52.1)

graph TB
    User[👤 Przeglądarka :18888]
    TG[📱 Telegram]
    Local[💻 Lokalne IDE]

    subgraph "Edge"
      Nginx[Nginx :18888<br/>basic-auth + deny-list]
      FE[React CRM + Phaser<br/>kontener frontend]
    end

    subgraph "Master Bot Bun :19210 — tylko 127.0.0.1"
      ApiSrv[api-server.ts<br/>196 LOC]
      Routes[master-bot/routes/<br/>auth · internal · cli · websocket]
      Router[shared/routes/router.ts<br/>dispatcher 373 LOC]

      subgraph "19 modułów domenowych — Phase 48"
        D1[auth · projects · workers]
        D2[skills · sage · chat]
        D3[wiki · files · onboarding]
        D4[billing · invites · analytics]
        D5[+ 7 kolejnych]
      end
    end

    subgraph "Federacja botów"
      Master[Master Bot<br/>orkiestrator]
      Child[Child Boty<br/>per-projekt]
      Claude[claude -p CLI]
    end

    subgraph "Warstwa inteligencji"
      Eval[Binary Evals]
      Ctx[Context Router top-5]
      Learn[Wstrzykiwanie Learnings]
      Karp[Pętla Karpathy'ego – nocna]
    end

    NB[NotebookLM Bridge<br/>FastAPI :19213 localhost]
    Google[(Google NotebookLM)]

    DB[(SQLite WAL<br/>21+ tabel<br/>migracje 001-021)]
    Vault[(Vault AES-256-GCM<br/>config/vault.json)]
    Bridge[Local Bridge CLI<br/>przekaźnik WebSocket]

    User -->|HTTPS| Nginx
    Nginx --> FE
    Nginx -->|/api/crm/*| ApiSrv
    Nginx -->|/api/sse/*| ApiSrv
    Nginx -->|/ws/terminal| ApiSrv
    ApiSrv --> Routes
    Routes --> Router
    Router --> D1 & D2 & D3 & D4 & D5

    TG --> Master
    TG --> Child
    Master -.uruchamia przez tmux.-> Child
    Child --> Claude
    Claude --> Eval & Ctx & Learn

    Router -.zapytania.-> NB
    Child -.auto-sync.-> NB
    NB --> Google

    Router --> DB
    Router --> Vault
    Child --> Vault

    Local --> Bridge
    Bridge -.ws relay.-> ApiSrv
    Karp -.nocna.-> DB

Kluczowe fakty:

• 70+ endpointów REST (Phase 52.1) w 19 modułach domenowych w shared/routes/
• Bind do 127.0.0.1 — Bun nigdy nie wystawia się zewnętrznie; nginx proksuje przez loopback
• Bramka multi-tenancy — canAccessProject(registry, chatId, project) na każdej chronionej trasie
• Zero-Knowledge E2EE (Phase 45) — WebCrypto PBKDF2 + klucz główny AES-256-GCM w sessionStorage

LEGACY (v1):
Użytkownik → Bot Telegram (Python 111KB) → HybridEngine → command_queue.json
       → bridge_processor.sh → Claude → command_responses.json
       → FastAPI EventBus → WebSocket → Phaser UI

V2 (NATYWNY):
Użytkownik → Oficjalny kanał Telegram → sesja Claude Code
       ↓                                ↓
       reply/edit_message          Zespoły agentów (TaskCreate/SendMessage)
                                        ↓
                                   Zapisz stan → pliki JSON
                                        ↓
                                   Arc OS Bridge MCP → HTTP/SSE → Phaser UI

Redukcja: 11 321 linii → ~3 700 linii (67% mniej kodu)

Komponenty

1. Sesja Claude Code (Mózg systemu)

Sesja Claude Code zastępuje:

• Backend FastAPI (15 usług)
• HybridEngine (39 KB)
• bridge_processor.sh (19,6 KB)
• response_watcher.py (14 KB)
• event_bus.py
• supply_chain.py (13 KB)

Cała orkiestracja odbywa się natywnie przez Zespoły Agentów.

2. Arc OS Bridge MCP Server (Adapter stanu)

Serwer MCP w TypeScript (Bun) — most między stanem Claude Code a frontendem.

Narzędzia MCP (strona Claude Code):

HTTP API (strona frontendu):

3. Frontend Phaser (Warstwa wizualna)

Phaser 3.80 + Vite. Łączy się z serwerem MCP przez HTTP/SSE.

Kluczowa różnica od v1: brak WebSocket — zastąpiony SSE z serwera MCP. Brak interfejsu do wpisywania poleceń — Telegram pełni rolę interfejsu sterowania.

4. Interfejs poleceń Telegram (Taktyczna warstwa UI — Phase 21.0)

Telegram to główny panel sterowania całego Arc OS. Dwa poziomy botów:

Master Bot (@citadel_ceo_bot):

• Trwała klawiatura odpowiedzi: Moje Projekty / Nowy Projekt / Watchdog / Web UI
• Karty projektów inline per child bot: Restart, Usuń, MANIFEST, Aktywne skille
• Przyciski URL do CRM: Projekt, Zadania, Pliki, Ustawienia (linki do frontendu)
• Router callback query dla wszystkich akcji inline
• Przepływ potwierdzenia usunięcia: klawiatura inline → TAK/ANULUJ → edycja wiadomości
• Rejestracja setMyCommands przy uruchomieniu

Child Boty (@cv2_pt_bot itp.):

• Każda odpowiedź Claude otrzymuje przyciski inline na ostatnim fragmencie:
  • STOP (SIGKILL) / PAUSE (SIGSTOP) / RESUME (SIGCONT) — kontrola podprocesu
  • BTW — kolejkuje dodatkowy kontekst do następnego wywołania Claude
  • Fix It — automatycznie generuje prompt naprawczy z ostatniej odpowiedzi bota
• Przycisk etykiety skilli pokazujący załadowane kompetencje projektu
• Router callback query dla wszystkich akcji signal/context

Integracja CRM (development):

CRM_BASE_URL = http://62.171.128.248:18888  (dev)
               https://crm.citadel.v2       (przyszły prod)

Wszystkie układy klawiatur zdefiniowane w shared/ui_templates.ts — jedno źródło prawdy dla zmian UI.

Protokół danych callback: akcja:cel (maks. 64 bajty)

• Master: restart:pt, delete:pt, confirm_del:pt, cancel_del:pt, manifest:pt, skills:pt
• Child: stop, pause, resume, btw, fixit, skills_info

Przepływ danych

1. Użytkownik wysyła "/status" przez Telegram
2. Sesja Claude Code odbiera przez kanał Telegram
3. Rick odczytuje state/office-state.json + TaskList()
4. Rick odpowiada przez Telegram (edit_message dla aktualizacji na żywo)
5. Rick wywołuje update_agent_state() przez MCP
6. Serwer MCP zapisuje do state/office-state.json
7. File watcher wykrywa zmianę → wysyła zdarzenie SSE
8. Frontend odbiera SSE → aktualizuje sprite'y agentów

Zarządzanie stanem

Cały stan przechowywany jest w plikach JSON w katalogu state/:

Zadania Zespołów Agentów zarządzane natywnie przez Claude Code pod ~/.claude/tasks/citadel-v2/.

Agenci (6)

Łańcuch dostaw

CEO → Rick (dekompozycja) → Zespół Agentów (wykonanie)
                          → Wzajemny przegląd (Summer waliduje)
                          → Rick (synteza)
                          → CEO (wynik końcowy)

Wymuszone przez:

• Blueprints: Konfiguracje działów definiujące role agentów
• Skille: Dynamicznie ładowane kompetencje
• Protokół HANDOFF: Ustrukturyzowane przekazywanie kontekstu między agentami

Stos technologiczny

Hooki cyklu życia

Hooki Claude Code (~/.claude/settings.json) automatycznie synchronizują stan agenta:

Zdarzenie SubagentStop → subagent-stop.sh → office-state.json (agent=idle)
                                              ↓
                                   StateManager (fs.watch) → SSE → Phaser UI

Zdarzenie Stop → session-end.sh → latest_wrapup.txt + wszystkie agenty=idle

Skrypty: scripts/citadel-hooks/subagent-stop.sh, scripts/citadel-hooks/session-end.sh

Kluczowe pola: subagentName (SubagentStop), stopReason (Stop), cwd (oba).

NotebookLM Bridge (Phase 36.3)

Prawdziwe wyszukiwanie semantyczne przez Google NotebookLM, zastępujące ręczne przesyłanie plików:

Cloud PM Chat → Bun Master Bot (:19210)
                    │
         executeAskNotebooklm()
                    │
         HTTP → FastAPI Bridge (:19213, tylko localhost)
                    │
              notebooklm-py async client
                    │
              Google NotebookLM (darmowe wyszukiwanie semantyczne)

         Fallback: lokalne wyszukiwanie słów kluczowych (istniejący kod)

• Jeden notatnik per projekt — mapowanie w notebook_mapping.json
• Auto-sync — zamknięcie/otwarcie zgłoszenia + aktualizacja wiki → fire-and-forget POST do /sync
• SyncWorker — asyncio.Queue(200), opóźnienie 2s, eksponencjalny backoff (3 próby)
• Cache zapytań — LRU, TTL 5 min, maks. 100 wpisów
• systemd — citadel-notebooklm-bridge.service, auto-restart, tylko localhost
• Auth — cookies Google w /root/.notebooklm/storage_state.json

Eksport oparty na plikach (/citadel-wrapup, /citadel-recall) nadal działa jako fallback.

Polityka routingu danych i zadań

System trzywarstwowy. Każda warstwa ma ściśle określone przeznaczenie. Mieszanie warstw = chaos.

┌─────────────────────────────────────────────────────────────────┐
│  WARSTWA 1: Pamięć robocza (gorąca)                             │
│  office-state.json + state/tasks/                               │
│  CLI: /citadel-task, /citadel-status                            │
│                                                                 │
│  Codzienne zadania agentów. Żyje w trakcie sesji. Ginie po.    │
│  Ukończone zadanie → /citadel-wrapup → Warstwa 3.              │
├─────────────────────────────────────────────────────────────────┤
│  WARSTWA 2: Strategiczny backlog (ciepły)                       │
│  GitHub Issues (repozytoria Claude-CEO + citadel-v2)            │
│                                                                 │
│  Tylko epiki: Phase 20, Phase 21, globalne błędy.              │
│  Bez zadań codziennych. Bez zgłoszeń "popraw literówkę".       │
│  Jedno zgłoszenie = jedna wielotygodniowa inicjatywa lub bug.  │
├─────────────────────────────────────────────────────────────────┤
│  WARSTWA 3: Pamięć długoterminowa (zimna)                       │
│  docs/library-export/ → Google Drive → NotebookLM              │
│  CLI: /citadel-wrapup, /citadel-recall                          │
│                                                                 │
│  Encyklopedia. Wyniki sesji, decyzje arch., RAG.               │
│  Archiwum tylko do odczytu. Brak aktywnych zadań.              │
└─────────────────────────────────────────────────────────────────┘

Zasady routingu

Cykl życia

CEO daje zadanie → Warstwa 1 (agent pracuje)
                       ↓ ukończone
                   /citadel-wrapup → Warstwa 3 (zarchiwizowane)
                       ↓ jeśli strategiczne
                   gh issue create → Warstwa 2 (śledzenie długoterminowe)

Antywzorce (NIE RÓB)

• NIE twórz GitHub Issues dla codziennych zadań („popraw literówkę", „zaktualizuj config")
• NIE przechowuj statusu aktywnych zadań w plikach library-export/
• NIE używaj office-state.json do długoterminowych decyzji ani notatek architektonicznych
• NIE duplikuj: jedno zadanie żyje dokładnie w jednej warstwie naraz

Infrastruktura (Phase 20.5)

Logowanie strukturalne (shared/logger.ts)

Format JSONL, podwójny output (plik + konsola), dzienne dzielenie plików według kategorii.

/var/log/citadel/
├── master/
│   ├── system-2026-04-02.log   ← cykl życia, config, zdrowie
│   ├── dialog-2026-04-02.log   ← (nie używany przez mastera)
│   └── error-2026-04-02.log    ← błędy (też w system)
├── citadel-v2/
│   ├── system-2026-04-02.log
│   ├── dialog-2026-04-02.log   ← wiadomości użytkownik ↔ Claude
│   └── error-2026-04-02.log
└── <nazwa-projektu>/           ← per onboardowany projekt

Rotacja logów: config/logrotate-citadel.conf → /etc/logrotate.d/citadel (codziennie, retencja 7 dni).

Vault sekretów (shared/vault.ts)

Zaszyfrowane AES-256-GCM przechowywanie tokenów botów.

Źródło klucza: env SECRET_ENCRYPTION_KEY → plik config/vault-key → auto-generowany
Przechowywanie: config/vault.json (atomiczne zapisy: tmp + mv)
Cache:          In-memory po initVault() — brak I/O dysku per getSecret()
Fallback:       getSecret("FOO") → cache vault → process.env.FOO
Nazewnictwo:    child:<nazwa-projektu>:token

Własny token mastera pozostaje w .env (vault ładuje się wewnątrz procesu mastera).

Samoleczący Watchdog (master-bot/watchdog.ts)

Monitor działający w tle dla child botów. Działa wewnątrz procesu master bota.

Co 30s: kontrola zdrowia HTTP → /api/child/health (timeout 5s)
  Zdrowy → reset licznika błędów
  Niezdrowy → inkrementuj błędy
  3+ błędy + upłynął backoff → auto-restart (kill tmux → start nowy z tokenem z vault)
  Backoff: 30s → 1 min → 5 min → 15 min → 60 min (max)
  10 kolejnych błędów → trwałe wyłączenie + powiadomienie CEO

Stan przechowywany w config/watchdog-state.json (przeżywa restart mastera). Powiadomienia CEO przez Telegram: pierwszy restart, błąd restartu, trwałe wyłączenie. Komenda /watchdog: status w czasie rzeczywistym dla wszystkich dzieci.

Protokół usuwania projektu (Phase 20.4 + 21.0)

/remove_project <nazwa> → potrójna konfirmacja → pełne czyszczenie:

1. Zabij sesję tmux: child-<nazwa>
2. Masowe usuwanie duchów: ps aux | grep child-<nazwa> → kill -9 wszystkich PID
3. Sprawdzenie portu: ss -tlnp | grep :<port> → wymuś zwolnienie jeśli zajęty
4. Usuń z bot_registry.json + przeładuj in-memory
5. Usuń /opt/repos/<nazwa>/ (bezpieczeństwo: ścieżka musi być pod /opt/repos/, min 3 segmenty)
6. Usuń /var/log/citadel/<nazwa>/

Chronione nazwy: citadel-v2, citadel, claude-ceo, claude-CEO — usuwanie zablokowane.

Problem procesów-duchów (lekcja): po zabiciu tmux, osierocone procesy bun mogą trzymać porty. Masowe zabijanie + sprawdzenie portu zapobiega „phantom botom", które odpowiadają na kontrole zdrowia, ale ignorują Telegram.

Zarządzanie skillami (Phase 21.0)

Child boty ładują skille z dwóch źródeł przy starcie, deduplikowane przez Set:

Źródło 1: MANIFEST.md (JSON)
  → manifest.skills[]          (dopasowane podczas onboardingu)
  → manifest.library_skills[]  (dopasowane pliki .md z biblioteki)

Źródło 2: katalog skills/
  → pliki *.md → nazwa pliku bez rozszerzenia

Scalanie: Set<string>(manifest.skills + manifest.library_skills + skills/*.md)

Przykład (projekt PT): 5 z manifestu + 7 z skills/ = 12 unikalnych skilli.

Skille wyświetlane jako:

• Etykieta przycisku inline na odpowiedziach child bota: 🏷️ odoo-expert, docker-ops, ...
• Callback skills_info: toast z pełną listą
• Komenda /skills w masterze: lista zawartości katalogu skills

Bezpieczeństwo (Phase 42 — audyt Sentinel 2026-04-23, 4 przebiegi, 13 łatek)

Pełny przegląd: SECURITY.md. Raport z audytu: security/audit-2026-04-23.md.

Sekrety i przechowywanie:

• Brak danych uwierzytelniających w repozytorium; pliki stanu nie zawierają sekretów
• Tokeny botów w zaszyfrowanym vault (config/vault.json, AES-256-GCM). Fallback getSecret() do process.env
• Klucz szyfrowania auto-generowany do config/vault-key (chmod 600). vault.json, vault-key, watchdog-state.json, data/citadel.db* w gitignore

Auth:

• JWT HMAC-SHA256, TTL 24h, porównanie sygnatury crypto.timingSafeEqual
• OAuth Google + GitHub z tokenem CSRF (10 min, jednorazowy)
• Email/hasło z wymaganą weryfikacją przed logowaniem (TTL 24h), reset hasła (TTL 30 min), dostarczane przez Resend
• Ekstrakcja tokenu — extractChatId() odczytuje nagłówek Bearer LUB query ?token= (dla przeglądarki EventSource), zgodnie z crmAuthMiddleware

Multi-tenancy (Phase 42):

• Bramka canAccessProject(registry, chatId, project) na każdej chronionej trasie
• CEO (ceo_chat_id) i DB user.role === 'admin' widzą wszystko; pozostali ograniczeni przez dopasowanie owner_id (DB jako SSOT)
• Trasy SSE, terminal WebSocket, /api/cli/*, /api/mcp/*, /api/crm/projects/:name/* — wszystkie zabezpieczone
• /ws/terminal/:name?mode=interactive wymaga CEO lub admina

Perymetr sieci:

• Bun binduje wyłącznie 127.0.0.1:19210 — nginx proksuje przez loopback
• /api/internal/* odrzuca każde żądanie zawierające nagłówki proxy (X-Forwarded-For, X-Real-IP, Forwarded) jako sygnał błędnej konfiguracji nginx
• Allowlist SSRF w handleScoutAnalyze — HTTPS + dokładne dopasowanie hostname + redirect:"manual" (blokuje obejście przez łańcuch przekierowań)
• UFW blokuje :19210, :19213, :19200 zewnętrznie

Bezpieczeństwo wejścia / ścieżek:

• Regex isValidProjectName() na każdym punkcie wejścia (w tym endpointy wewnętrzne)
• safePath() na wszystkich ścieżkach plików kontrolowanych przez użytkownika — handleSaveSkill znalezione + załatane Phase 42.6
• Lista blokad nginx: /.*, /(state|scripts|config|data|knowledge-base|issues|skills|blueprints|mcp-server)/
• Whitelist CORS (CRM_ALLOWED_ORIGINS), nagłówki również na błędach
• Atomiczne zapisy dla mutacji rejestru (tmp.${pid} + mv)
• Deszyfrowanie tokenu vault dla startu child bota: użyj bun -e z node:crypto (NIE Python)

Pokrycie regresji: scripts/vps-sync.sh uruchamia 7+ testów dymnych po każdym deployu (bind loopback, path traversal, walidacja chat/save, kanarka proxy, SSE ?token=, walidacja fail-closed, blokada SSRF jeśli ustawione CEO_TOKEN).

Moduły Master Bota (Phase 25 — Rozwiązanie DEBT-1)

Master bot zorganizowany jest w skoncentrowane moduły:

master-bot/
├── bot.ts               ← Bootstrap: vault, rejestr, kontekst, okablowanie (106 linii)
├── context.ts           ← Typ MasterContext + interfejsy domenowe
├── api-server.ts        ← Bun.serve() — HTTP, WebSocket, SSE, trasy CRM
├── tg-api.ts            ← Wrapper Telegram Bot API (sendMessage, getUpdates itp.)
├── child-state.ts       ← Stan child bota, zdrowie, heartbeat, tmux, bridge
├── telegram-commands.ts ← Wszystkie handlery /komend, router callback query, router wiadomości
├── telegram.ts          ← Uproszczona pętla pollingu + re-eksporty dla wstecznej kompatybilności
├── watchdog.ts          ← Samoleczący monitor child botów
└── onboarding.ts        ← Interaktywny wizard tworzenia projektu

bot.ts importuje tylko z telegram.ts i api-server.ts. Wszystkie pozostałe moduły to szczegóły implementacji.

Bridge CLI (Phase 25 — Lokalna Brama)

bridge/
├── bin/citadel-bridge.ts    ← Wejście CLI (commander.js): connect, pull, push, status, disconnect
├── src/
│   ├── auth.ts              ← Walidacja JWT względem CRM
│   ├── config.ts            ← Trwałość ~/.citadel/bridge.json
│   ├── inject.ts            ← Markery <!-- CITADEL:START/END --> w CLAUDE.md
│   ├── sync.ts              ← Pull skills-bundle + learnings, push lokalnych learnings
│   └── heartbeat.ts         ← Reporter aktywności sesji
├── package.json
└── tsconfig.json

Endpointy CRM API (50+ łącznie)

Podstawowe CRM (Phase 22)

Pulpit i wiki (Phase 32)

Multi-tenancy (Phase 33)

MCP i CLI (Phase 34)

Terminal na żywo (Phase 35)

Cloud PM i wiedza (Phase 36)

Auth i OAuth (Phase 37)

Przypięte notatki (Phase 41.8)

Backend: migracja 009 (tabela pinned_notes), pinnedNoteQueries w shared/db.ts. Frontend: ContextRail.jsx pobiera przy montowaniu, nasłuchuje zdarzenia CustomEvent crm-pin-created, optymistyczne DELETE.

Warstwa ochrony danych (Phase 45)

Hybrydowe szyfrowanie at-rest — fundament kryptografii po stronie klienta + szyfrowanie po stronie serwera.

Po stronie klienta (Przeglądarka)

• frontend/src/crm/crypto/e2ee.ts — wrapper WebCrypto (214 linii)
• PBKDF2 (100k iteracji, SHA-256) → klucz główny AES-256-GCM
• Cykl życia klucza: initMasterKey(password) przy logowaniu → sessionStorage → clearMasterKey() przy wylogowaniu/401
• Odzyskiwanie: generateRecoveryKey() → format 1Password (XXXX-XXXX-XXXX-XXXX-XXXX)

Po stronie serwera (Bun + SQLite)

• shared/vault.ts — encryptField()/decryptField() używa AES-256-GCM klucza vault (format prefiksu v1:)
• Klucze API: szyfruj przy zapisie, deszyfruj przy odczycie (transparentnie dla frontendu) — routes/system.ts
• Wiadomości czatu: auto-szyfrowanie INSERT, auto-deszyfrowanie SELECT — db.ts + migracja 015
• Klucze odzyskiwania: tabela recovery_keys (migracja 016), 4 endpointy API

Nagłówki bezpieczeństwa

• CSP: default-src 'self'; script-src 'self' na wszystkich odpowiedziach CRM
• X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin

Sanityzacja PII

• shared/pii-sanitizer.ts — redaguje emaile, klucze API (sk-ant-*, sk-*), JWT, numery kart
• Stosowana przy ingescie logów JSONL terminala (routes/chat.ts)

Endpointy klucza odzyskiwania

Pełne szczegóły bezpieczeństwa: docs/SECURITY.md, docs/architecture/PHASE_45_E2EE.md.