# 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]]