# pi-hitl-programming

Estensione per **pi coding agent** che introduce un **Human-in-the-Loop (HITL)** focalizzato sulla programmazione.

Ogni volta che l'agente tenta di **scrivere** (`write`) o **modificare** (`edit`) un file di programmazione, l'estensione:

1. Mostra il percorso del file.
2. Genera una **spiegazione brevissima** (massimo 5-6 righe) del codice proposto.
3. Mostra il **codice proposto** in una finestra scrollabile.
4. Chiede all'utente cosa fare:
   - ✅ **Accetta e applica**
   - ✏️ **Modifica prima di applicare**
   - 💬 **Discuti / chiedi**
   - ❌ **Rifiuta**

Se l'utente sceglie di modificare, può editare il contenuto direttamente nell'editor di pi. Se sceglie di discutere, può scrivere una nota che viene riportata all'agente come motivo di blocco.

## Controlli nella schermata HITL

- **↑ / ↓**: scrolla il testo riga per riga.
- **Ctrl+U / Ctrl+D**: scrolla di una pagina.
- **Home / End**: va all'inizio / fine del testo.
- **Tab**: sposta il focus tra il pannello di testo e il menu azioni.
- **Enter**: seleziona l'azione evidenziata (quando il menu ha il focus).
- **Esc**: rifiuta la modifica.

## Attivare / disattivare HITL al volo

L'estensione può essere accesa o spenta senza uscire da pi:

- Tasto **F10**.
- Comando slash **`/hitl`**, `/hitl on`, `/hitl off`.

Una notifica in TUI conferma lo stato attuale.

## File intercettati

L'HITL si attiva solo su file con estensione di programmazione/configurazione (es. `.py`, `.js`, `.ts`, `.java`, `.c`, `.cpp`, `.go`, `.rs`, `.sh`, `.html`, `.css`, `.json`, `.yaml`, `.toml`, `.md`, …). I file generici (es. `.txt`) vengono lasciati passare.

## Installazione

L'estensione e auto-scoperta da pi quando si trova in un percorso riconosciuto.

### Project-local (consigliato per questo progetto)

Il repository contiene gia una copia in `.pi/extensions/hitl-programming.ts`. Devi solo **fidarti del progetto** e ricaricare:

```bash
cd /home/enne2/Development/pi-hitl
pi
# dentro pi, quando richiesto, seleziona "Trust"
/reload
```

### Globale

```bash
cp /home/enne2/Development/pi-hitl/src/index.ts ~/.pi/agent/extensions/hitl-programming.ts
# riavvia pi o esegui /reload
```

## Esempi di Tetris inclusi

Il repository include due implementazioni minimali di Tetris:

- `tetris.py`: versione con `curses` (terminale classico).
- `tetris_textual.py`: versione moderna con [Textual](https://textual.textualize.io/).

Per eseguire la versione Textual:

```bash
pip install -r requirements.txt
python3 tetris_textual.py
```

## Test rapido

Dopo il caricamento, dentro pi chiedi:

```
scrivi un file hello.py con contenuto print("ciao")
```

Dovrebbe apparire una schermata HITL con:

- spiegazione breve del codice proposto;
- anteprima del codice scrollabile;
- menu per accettare, modificare, discutere o rifiutare.

## Modalita non interattiva

In modalita `--mode print` o `--mode json` l'estensione **blocca** scritture e modifiche perche non puo mostrare la UI. Usala solo in modalita TUI interattiva.

## Note

- L'estensione aggiunge un'istruzione al system prompt per scoraggiare l'agente dall'usare `bash` con redirezioni (`>`, `>>`) per aggirare la conferma.
- La spiegazione e generata a partire dal codice completo proposto (fino a 60.000 caratteri), non dalla sola anteprima TUI.
- Quando HITL e disattivato, le operazioni `write`/`edit` su file di programmazione procedono normalmente.