Document future agent integration

README.md

@@ -407,6 +407,7 @@ u1T4a
   synchronizacja remote <-> store
 - `doc/series.md` - docelowy model komend dla serii i kart pracy
 - `doc/containers.md` - docelowy model komend dla środowisk kontenerowych
+- `doc/agents.md` - wnioski i plan późniejszej integracji agentów z kontenerami
 - `doc/workspace.md` - krótki opis konfiguracji workspace
 
 README jest tylko mapą projektu. Szczegóły operacyjne trzymamy w `doc/`, żeby

doc/agents.md

@@ -0,0 +1,142 @@
+# 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.