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:

./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:

./stemctl agent attach codex --instance hazard3-sim-inf-bss-t4

Co powinien robić `stemctl`

Przy agent start narzędzie powinno:

rozwiązać serię, kartę i zadanie tak samo jak debug,
wybrać jeden z trzech profili i właściwy target,
nadać stabilną nazwę instancji, na przykład hazard3-sim-inf-bss-t4,
uruchomić kontener i sesję tmux,
włączyć tryb agentowy przez zmienne środowiskowe, na przykład:

STEM_AGENT=codex
STEM_MCP=1
STEM_INSTANCE=hazard3-sim-inf-bss-t4

rozwiązać bieżący container ID i sockety z katalogu instancji,
uruchomić bridge MCP dla tmux i nvim,
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:

$XDG_RUNTIME_DIR/stem/<thread-key>/<instance-key>/<cid12>/

W nim mogą znajdować się:

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

Domknąć trzy profile i komendy build, test, run, debug, deploy.
Ustabilizować labels instancji i katalogi socketów z container ID.
Zaimplementować resolver socketów dla tmux i nvim.
Dodać stemctl agent list.
Dodać stemctl agent start.
Dodać stemctl agent attach.
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.

4.8 KiB Raw Blame History