# Brama

## Czym jest brama?

Brama to serce Neotask -- pojedyncza długo działająca usługa, która zarządza wszystkimi sesjami agentów, kanałami komunikacyjnymi, wykonywaniem narzędzi i połączeniami urządzeń. Wszystko przepływa przez bramę.

To serwer WebSocket, który nasłuchuje połączeń od klientów (aplikacja desktopowa, aplikacje mobilne, panel internetowy) i zarządza całym cyklem życia asystenta AI.

## Architektura

### Komponenty

- **Serwer WebSocket** -- Akceptuje połączenia klientów (domyślny port 18789)
- **Serwer HTTP** -- Obsługuje interfejs sterowania, hosta kanwy i punkty końcowe stanu
- **Adaptery kanałów** -- Utrzymują połączenia z platformami komunikacyjnymi (WhatsApp, Telegram, Discord itp.)
- **Menedżer sesji** -- Utrzymuje i zarządza stanem rozmów agentów
- **Harmonogram Cron** -- Uruchamia zaplanowane zadania i przebudzenia heartbeat
- **Środowisko uruchomieniowe wtyczek** -- Ładuje i zarządza cyklem życia wtyczek
- **Usługa przeglądarki** -- Steruje instancjami Chromium do automatyzacji sieci

### Tryby powiązania

| Tryb | Opis |
|------|------|
| **Pętla zwrotna** | Domyślny. Dostępny tylko z localhost (127.0.0.1) |
| **LAN** | Dostępny w lokalnej sieci. Automatycznie wykrywalny przez Bonjour/mDNS |
| **Tailnet** | Dostępny przez VPN Tailscale z MagicDNS |
| **Niestandardowy** | Powiąż z określonym adresem |

### Uwierzytelnianie

| Metoda | Opis |
|--------|------|
| **Token** | Bearer token WebSocket (UUID lub niestandardowy ciąg) |
| **Hasło** | Uwierzytelnianie oparte na haśle (haszowane bcrypt) |
| **Zaufany proxy** | Dla odwrotnych proxy z wstępnie uwierzytelnionym nagłówkiem |
| **Lokalne zaufanie** | Połączenia z pętlą zwrotną automatycznie zatwierdzone |

## Konfiguracja

Brama jest konfigurowana przez `neotask.json` (format JSON5). Kluczowe sekcje:

| Sekcja | Kontroluje |
|--------|----------|
| `agents` | Lista agentów, wartości domyślne, przestrzenie robocze |
| `gateway` | Port, tryb powiązania, uwierzytelnianie, zachowanie przeładowania |
| `channels` | Konfiguracja per kanał i dane uwierzytelniające |
| `tools` | Uprawnienia narzędzi, profile, bezpieczeństwo |
| `plugins` | Ładowanie wtyczek, włączanie, konfiguracja per wtyczka |
| `models` | Uwierzytelnianie dostawcy, mechanizmy awaryjne, ustawienia dostawcy |
| `skills` | Katalogi umiejętności, konfiguracja per umiejętność |
| `browser` | Profile przeglądarki, porty, tryb bezgłowy |
| `cron` | Konfiguracja harmonogramu |
| `session` | Reguły resetowania, progi kompakcji |
| `messages` | Ustawienia TTS, zasady mediów |
| `memory` | Konfiguracja indeksowania pamięci |
| `security` | Sandboxing, tryb podwyższony, zatwierdzenia |

### Gorące przeładowanie

Zmiany konfiguracji można stosować bez ponownego uruchamiania:

| Tryb | Zachowanie |
|------|----------|
| **Hybrydowy** (domyślny) | Zastosuj bezpieczne zmiany na gorąco, uruchom ponownie dla pozostałych |
| **Gorący** | Zastosuj tylko zmiany bezpieczne na gorąco, ignoruj pozostałe |
| **Restart** | Uruchom ponownie przy każdej zmianie wymagającej przeładowania |
| **Wył.** | Brak automatycznego przeładowania |

## Zdalny dostęp

### Tailscale (zalecany)

Tailscale zapewnia bezpieczny, bezproblemowy zdalny dostęp:

- Powiąż bramę z Twoją siecią Tailnet
- Uzyskuj dostęp z dowolnego urządzenia w tej samej sieci Tailscale
- Automatyczny DNS przez MagicDNS
- Tailscale Serve może udostępniać panel sterowania z HTTPS

### Tunel SSH

Przekaż port bramy przez SSH:

- Prosty, bezpieczny, bez zmian konfiguracji
- Działa z dowolną maszyną z obsługą SSH
- Obsługuje pełny protokół WebSocket i interfejs sterowania

### Zasady bezpieczeństwa

- **Pętla zwrotna + SSH/Tailscale** to najbezpieczniejsza kombinacja
- Powiązanie inne niż pętla zwrotna wymaga konfiguracji tokenu uwierzytelniającego
- Dostępne przypinanie odcisku TLS dla dodatkowego bezpieczeństwa
- Sterowanie przeglądarką jest domyślnie wyłączone dla połączeń zdalnych

## Monitorowanie stanu

### Punkt końcowy stanu

Punkt końcowy HTTP `/health` zwraca:

- Status bramy
- Liveness RPC
- Stan kanału per (połączony, status uwierzytelniania, liczba kont)
- Gotowość przeglądarki
- Aktywni agenci i podłączone węzły
- Czas działania

### Sondy

- **Liveness RPC** -- Połączenie WebSocket + test echo
- **Stan kanału** -- Sprawdzenie uwierzytelniania + ping API per kanał
- **Gotowość przeglądarki** -- Sprawdzenie portu, sprawdzenie procesu
- **Łączność węzła** -- Znacznik czasu ostatniego heartbeat

## Odkrywanie

### Bonjour/mDNS

Gdy jest powiązana z LAN, brama reklamuje się przez wielodostępny DNS:

- Typ usługi: `_neotask-gw._tcp`
- Zawiera port, transport, status TLS i informacje DNS Tailscale
- Aplikacje towarzyszące automatycznie odkrywają bramę

### Odkrywanie w szerokim obszarze

Odkrywaj bramy w całej sieci z konfigurowalnymi limitami czasu. Obsługuje zarówno lokalne Bonjour, jak i odkrywanie DNS Tailscale.

## Wiele bram

Możesz uruchamiać wiele instancji bramy na tej samej maszynie używając profili:

- Każdy profil ma oddzielną konfigurację, przestrzeń roboczą, sesje i stan
- Różne porty dla każdej bramy
- Przydatne do izolacji (osobistej vs służbowej) lub testowania

## Diagnostyka

### Doctor

Wbudowane narzędzie diagnostyczne sprawdza:

- Poprawność konfiguracji
- Uprawnienia plików
- Łączność kanałów
- Status uwierzytelniania modelu
- Kompatybilność wersji Node.js
- Typowe błędne konfiguracje

Może automatycznie naprawić wiele problemów po udzieleniu pozwolenia.

### Logowanie

Logi bramy są zapisywane do dziennych plików JSONL:

- Śledzenie użycia tokenów per uzupełnienie
- Logi zdarzeń kanałów
- Logowanie błędów ze strukturyzowanym kontekstem
- Konfigurowalne poziomy logowania