# 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.