mpabi
152 lines
4.8 KiB
Markdown
152 lines
4.8 KiB
Markdown
# Agenci w środowisku kontenerowym
|
|
|
|
Ten dokument zapisuje wnioski do integracji agentów, takich jak Codex, Claude,
|
|
Gemini i inne narzędzia asystujące. Docelowo integracja obejmuje trzy profile:
|
|
`native-amd64`, `hazard3-sim` i `rp2350`.
|
|
|
|
## 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 `.stem/instances/<instance>/`.
|
|
|
|
Dzięki temu agent widzi środowisko debugowania, a nie tylko statyczne pliki.
|
|
|
|
## Aktualny fundament
|
|
|
|
`rv32i-hazard3-student-env` dostarcza źródła wspólnego modelu:
|
|
|
|
- profile `native-amd64`, `hazard3-sim` i `rp2350` jako trzy usługi Compose;
|
|
- jeden wieloetapowy Dockerfile budowany lokalnie, bez dystrybucji obrazów;
|
|
- `tmux` jako warstwa sesji terminalowej,
|
|
- `nvim` uruchamiany ze stabilnym socketem,
|
|
- `gdb-multiarch` dla profilu `rv32i`,
|
|
- `gdb` i opcjonalnie `lldb` dla profilu `host`,
|
|
- katalog stanu `.stem/instances/<instance>/`, z fallbackiem `.rv`;
|
|
- skrypty MCP dla `tmux` i `nvim`:
|
|
- `scripts/mcp-tmux.sh`,
|
|
- `scripts/mcp-nvim.sh`,
|
|
- `scripts/nvim-in-container.sh`.
|
|
|
|
Serwery MCP są instalowane w kontenerze, a hostowe wrappery weryfikują label i
|
|
bieżący ID Podmana przed `podman exec`. `stemctl` oraz wspólny kontrakt trzech
|
|
profili są wdrożone; osobne komendy wyższego poziomu `agent start/attach`
|
|
pozostają rozszerzeniem późniejszym.
|
|
|
|
## Docelowy model komend
|
|
|
|
Docelowo `stemctl` powinien ukrywać szczegóły socketów, kontenerów i providerów.
|
|
Przykładowy kierunek:
|
|
|
|
```bash
|
|
./stemctl agent start codex native-amd64 inf bss 4
|
|
./stemctl agent start codex hazard3-sim inf bss 4
|
|
./stemctl agent start codex rp2350 inf bss 4 --target rp2350-rv
|
|
```
|
|
|
|
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
|
|
./stemctl agent attach codex --instance hazard3-sim-inf-bss-t4
|
|
```
|
|
|
|
## Co powinien robić `stemctl`
|
|
|
|
Przy `agent start` narzędzie powinno:
|
|
|
|
1. rozwiązać serię, kartę i zadanie tak samo jak `debug`,
|
|
2. wybrać jeden z trzech profili i właściwy target,
|
|
3. nadać stabilną nazwę instancji, na przykład
|
|
`hazard3-sim-inf-bss-t4`,
|
|
4. uruchomić kontener i sesję `tmux`,
|
|
5. włączyć tryb agentowy przez zmienne środowiskowe, na przykład:
|
|
|
|
```text
|
|
STEM_AGENT=codex
|
|
STEM_MCP=1
|
|
STEM_INSTANCE=hazard3-sim-inf-bss-t4
|
|
```
|
|
|
|
6. rozwiązać bieżący container ID i sockety z katalogu instancji,
|
|
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 używamy dwóch poziomów tożsamości:
|
|
|
|
```text
|
|
$XDG_RUNTIME_DIR/stem/<thread-key>/<instance-key>/<cid12>/
|
|
```
|
|
|
|
W nim mogą znajdować się:
|
|
|
|
```text
|
|
t.sock
|
|
n.sock
|
|
gdb-sync.json
|
|
container.json
|
|
```
|
|
|
|
Pełna nazwa instancji pozostaje w label i registry. Krótkie klucze oraz
|
|
12-znakowy prefiks container ID utrzymują ścieżkę AF_UNIX poniżej 100 bajtów.
|
|
Aktualny ID uniemożliwia użycie socketu pozostałego po odtworzeniu kontenera.
|
|
`stemctl` traktuje te pliki jako szczegóły implementacyjne. Użytkownik i agent
|
|
dostają komendy wyższego poziomu.
|
|
|
|
## Role profili
|
|
|
|
Profil `hazard3-sim`:
|
|
|
|
- debugowanie kodu dla RISC-V/Hazard3,
|
|
- `gdb-multiarch`,
|
|
- symulator,
|
|
- przykłady asemblerowe i mieszane C/ASM.
|
|
|
|
Profil `native-amd64`:
|
|
|
|
- natywne uruchomienie i debugowanie kodu C,
|
|
- szybkie testowanie algorytmów,
|
|
- `clang` albo `gcc`,
|
|
- `gdb`, opcjonalnie `lldb` i `valgrind`.
|
|
|
|
Profil `rp2350`:
|
|
|
|
- debugowanie fizycznego Pico 2/Pico 2 W;
|
|
- targety RISC-V Hazard3 i ARM Cortex-M33;
|
|
- OpenOCD, probe, flash, serial i FreeRTOS;
|
|
- dostęp tylko do jawnie wybranego urządzenia USB.
|
|
|
|
Taski czysto asemblerowe RISC-V pozostają w `hazard3-sim` albo `rp2350-rv`.
|
|
|
|
## Kolejność wdrożenia
|
|
|
|
1. Domknąć trzy profile i komendy `build`, `test`, `run`, `debug`, `deploy`.
|
|
2. Ustabilizować labels instancji i katalogi socketów z container ID.
|
|
3. Zaimplementować resolver socketów dla `tmux` i `nvim`.
|
|
4. Dodać `stemctl agent list`.
|
|
5. Dodać `stemctl agent start`.
|
|
6. Dodać `stemctl 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.
|