From afc96f7a8ac8194ca083c1548939522c13c1a6ce Mon Sep 17 00:00:00 2001 From: mpabi Date: Fri, 1 May 2026 22:31:01 +0200 Subject: [PATCH] Document future agent integration --- README.md | 1 + doc/agents.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 doc/agents.md diff --git a/README.md b/README.md index 6fec7b8..cb213f2 100644 --- a/README.md +++ b/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 diff --git a/doc/agents.md b/doc/agents.md new file mode 100644 index 0000000..5f7b41f --- /dev/null +++ b/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//`. + +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//`, +- 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//`, +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 +/.rv// +``` + +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//`. +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.