# Agenci w środowisku kontenerowym

Ten dokument zapisuje wnioski do przyszłej integracji agentów, takich jak
Codex, Gemini i inne narzędzia asystujące. Integrację robimy po domknięciu
kontenerów `rv32i` i `host`.

## Założenie

Agent nie powinien pracować wyłącznie przez komendy uruchamiane z hosta. Ma
mieć wgląd w tę samą sesję, w której pracuje uczeń:

- `tmux` - terminale, panele, `gdb`, wynik programu i logi uruchomienia,
- `nvim` - edycja plików i nawigacja po kodzie,
- `gdb` lub `gdb-multiarch` - stan debuggera,
- katalog karty pracy zamontowany w kontenerze,
- stan sesji zapisany pod `.rv/<instance>/`.

Dzięki temu agent widzi środowisko debugowania, a nie tylko statyczne pliki.

## Aktualny fundament

`rv32i-hazard3-student-env` ma już elementy potrzebne do takiego modelu:

- profil `rv32i` jako usługa `env` w `docker compose`,
- profil `host` jako osobna usługa `host`,
- `tmux` jako warstwa sesji terminalowej,
- `nvim` uruchamiany ze stabilnym socketem,
- `gdb-multiarch` dla profilu `rv32i`,
- `gdb` i opcjonalnie `lldb` dla profilu `host`,
- katalog stanu `.rv/<instance>/`,
- skrypty MCP dla `tmux` i `nvim`:
  - `scripts/mcp-tmux.sh`,
  - `scripts/mcp-nvim.sh`,
  - `scripts/nvim-in-container.sh`.

To oznacza, że kontenery są dobrym miejscem do podłączenia agentów. Brakuje
jeszcze spójnej warstwy komend w `rvctl`.

## Docelowy model komend

Docelowo `rvctl` powinien ukrywać szczegóły socketów, kontenerów i providerów.
Przykładowy kierunek:

```bash
./rvctl agent start codex rv32i inf bss 4
./rvctl agent start codex host inf bss 4
./rvctl agent start gemini rv32i inf bss 4
./rvctl agent start gemini host inf bss 4
```

Skróty mogą powstać później, ale podstawowy model powinien zostać jawny:
agent, profil środowiska, seria, karta i zadanie.

Możliwy wariant dla już uruchomionej sesji:

```bash
./rvctl agent attach codex --instance rv32i-inf-bss-t4-debug
./rvctl agent attach gemini --instance host-inf-bss-t4-debug
```

## Co powinien robić `rvctl`

Przy `agent start` narzędzie powinno:

1. rozwiązać serię, kartę i zadanie tak samo jak `debug`,
2. wybrać profil `rv32i` albo `host`,
3. nadać stabilną nazwę instancji, na przykład
   `rv32i-inf-bss-t4-debug`,
4. uruchomić kontener i sesję `tmux`,
5. włączyć tryb agentowy przez zmienne środowiskowe, na przykład:

```text
RV_AGENT=codex
RV_CODEX=1
RV_INSTANCE=rv32i-inf-bss-t4-debug
```

6. zapisać albo odczytać sockety z `.rv/<instance>/`,
7. uruchomić bridge MCP dla `tmux` i `nvim`,
8. przekazać agentowi minimalny kontekst:
   - ścieżka repo karty,
   - profil środowiska,
   - nazwa zadania,
   - komendy build/debug/run,
   - ścieżki socketów,
   - ograniczenia profilu.

## Sockety i stan sesji

Dla każdej instancji powinniśmy konsekwentnie używać katalogu:

```text
<card>/.rv/<instance>/
```

W nim mogą znajdować się:

```text
tmux.sock
nvim.sock
gdb-sync.json
vim-mcp.sock
vim-mcp-registry.json
```

`rvctl` powinien traktować te pliki jako szczegóły implementacyjne. Użytkownik
i agent powinni dostawać komendy wyższego poziomu.

## Role profili

Profil `rv32i`:

- debugowanie kodu dla RISC-V/Hazard3,
- `gdb-multiarch`,
- symulator,
- przykłady asemblerowe i mieszane C/ASM.

Profil `host`:

- natywne uruchomienie i debugowanie kodu C,
- szybkie testowanie algorytmów,
- `clang` albo `gcc`,
- `gdb`, opcjonalnie `lldb` i `valgrind`.

Taski czysto asemblerowe pozostają w profilu `rv32i`.

## Kolejność wdrożenia

1. Domknąć komendy kontenerowe `env`, `debug`, `run` i `shell`.
2. Ustabilizować nazwy instancji i katalog `.rv/<instance>/`.
3. Opisać kontrakt socketów dla `tmux` i `nvim`.
4. Dodać `rvctl agent list`.
5. Dodać `rvctl agent start`.
6. Dodać `rvctl agent attach`.
7. Dopiero potem podpinać konkretne providery: Codex, Gemini i kolejne.

## Zasada projektowa

Integracja agentów ma być dodatkiem do kontenerowego środowiska pracy, a nie
osobną ścieżką wykonywania zadań. Agent ma pomagać w tej samej sesji, w której
działa uczeń: z tym samym repo, tym samym `tmux`, tym samym `nvim` i tym samym
debuggerem.