initial commit

02-Architektura/Przepływ danych i IPC.md

@@ -0,0 +1,126 @@
+# Przepływ danych i IPC
+
+#sympozium #architektura #ipc
+
+## Mechanizm IPC
+
+Sympozium używa **filesystem-based IPC** - agenty komunikują się z control plane przez pliki JSON w woluminie `/ipc/`:
+
+```
+Agent tool pisze JSON → /ipc/<dir>/*.json → fsnotify watcher → NATS publish → Controller
+```
+
+### Katalogi IPC
+
+| Katalog | Cel | Przykład |
+|---------|-----|---------|
+| `/ipc/tools/` | Wykonanie komend w sidecarze | `execute_command` |
+| `/ipc/messages/` | Wysyłanie wiadomości na kanały | `send_channel_message` |
+| `/ipc/schedules/` | Zarządzanie schedulami | `schedule_task` |
+
+## Dlaczego filesystem IPC?
+
+### Zalety
+1. **Language-agnostic** - agent mógłby być w Pythonie, Rust, czymkolwiek
+2. **Zero zależności** - agent nie potrzebuje klienta NATS ani żadnego SDK
+3. **Inspekcja** - pliki JSON w woluminie można łatwo debugować
+4. **Prostota** - zapis pliku to najprostsza operacja I/O
+5. **Bezpieczeństwo** - agent nie ma dostępu sieciowego, tylko do woluminu
+
+### Jak to działa
+
+```
+1. Agent zapisuje /ipc/tools/cmd-12345.json:
+   {
+     "command": "kubectl get pods",
+     "runId": "my-run-123"
+   }
+
+2. IPC Bridge (sidecar) wykrywa plik via fsnotify
+
+3. Bridge publikuje na NATS:
+   Topic: tool.exec.request
+   Payload: {command, runId, instanceName}
+
+4. Skill sidecar (lub controller) odbiera i wykonuje
+
+5. Wynik wraca: NATS → IPC Bridge → /ipc/tools/result-12345.json
+
+6. Agent czyta wynik z pliku
+```
+
+## NATS Topics
+
+Kluczowe tematy zdefiniowane w `internal/eventbus/types.go`:
+
+### Lifecycle agenta
+- `agent.run.requested` - żądanie nowego runu
+- `agent.run.started` - run rozpoczęty
+- `agent.run.completed` - run zakończony sukcesem
+- `agent.run.failed` - run zakończony błędem
+
+### Wiadomości kanałów
+- `channel.message.received` - wiadomość od użytkownika
+- `channel.message.send` - wiadomość do użytkownika
+
+### Narzędzia
+- `tool.exec.request` - żądanie wykonania komendy w sidecarze
+- `tool.exec.result` - wynik wykonania
+
+### Scheduling
+- `schedule.upsert` - agent sam tworzy/aktualizuje swój schedule
+
+## Wbudowane narzędzia agenta
+
+Agent-runner ma **7 wbudowanych narzędzi** (`cmd/agent-runner/tools.go`):
+
+| Narzędzie | Kategoria | Opis |
+|-----------|-----------|------|
+| `execute_command` | IPC (sidecar) | Uruchamia komendy shell w skill sidecarze |
+| `read_file` | Native | Czyta zawartość pliku |
+| `write_file` | Native | Tworzy/zapisuje pliki |
+| `list_directory` | Native | Listuje zawartość katalogu |
+| `send_channel_message` | IPC (bridge) | Wysyła wiadomości na kanały |
+| `fetch_url` | Native | HTTP GET i zwraca body |
+| `schedule_task` | IPC (bridge) | CRUD na SympoziumSchedule CRDs |
+
+### Natywne vs IPC
+
+- **Native** - narzędzia wykonywane bezpośrednio w kontenerze agenta
+- **IPC (sidecar)** - narzędzia delegowane do skill sidecara przez IPC bridge
+- **IPC (bridge)** - narzędzia delegowane do controllera przez NATS
+
+## Przepływ end-to-end
+
+```
+Użytkownik → Telegram
+    ↓
+Channel Pod (Telegram) → NATS: channel.message.received
+    ↓
+Channel Router → Tworzy AgentRun CR
+    ↓
+AgentRun Reconciler → Tworzy Job z kontenerami
+    ↓
+Agent Container:
+  1. Czyta task z /workspace/input/
+  2. Czyta skills z /skills/
+  3. Czyta memory z /memory/ lub memory API
+  4. Wywołuje LLM (OpenAI/Anthropic/etc.)
+  5. LLM decyduje o użyciu narzędzia
+  6. Agent pisze do /ipc/tools/
+  7. IPC Bridge → NATS → Skill Sidecar wykonuje
+  8. Wynik wraca → Agent kontynuuje dialog z LLM
+  9. Agent pisze wynik do stdout
+    ↓
+Controller zbiera logi poda
+    ↓
+Controller → NATS: agent.run.completed
+    ↓
+Channel Router → NATS: channel.message.send
+    ↓
+Channel Pod (Telegram) → Użytkownik
+```
+
+---
+
+Powiązane: [[NATS JetStream - Event Bus]] | [[Cykl życia Agent Pod]] | [[Skill Sidecars i auto-RBAC]]