# Context Injection Engine (Fase 2)

L'estensione `agy-pi` include un motore avanzato di **Context Injection** che costruisce in tempo reale un blocco strutturato di contesto prima di ogni prompt inviato ad `agy`.

---

## Architettura del Blocco di Contesto

Il blocco di contesto rispetta le best practice di **Context Engineering** per i modelli di grandi dimensioni (LLM):
- Utilizzo di tag XML semantici.
- Posizionamento della richiesta utente **sempre alla fine** del prompt per contrastare l'effetto *"Lost in the Middle"* (Liu et al., TACL 2024).
- Gestione rigida del token budget (default 1500 token).

```xml
[CONTEXT_AGENTE] Contesto ambiente e stato corrente per la risposta. Usa solo se pertinente; la richiesta dell'utente è sotto.

<environment_snapshot>
cwd: /home/utente/progetto
os: linux x64
time: 2026-08-10T17:15:00.000Z
git_branch: main (dirty)
modified: src/index.ts | package.json
</environment_snapshot>

<session_state>
Utente: Analizza la struttura di questo componente...
Assistente: Ho controllato i file...
</session_state>

<durable_memory>
goal: Implementare il nuovo modulo di autenticazione
decisions: Usare token JWT con scadenza 1h | Database Postgres
conventions: TypeScript strict mode
</durable_memory>

<web_context>
[Risultati ricerca web Gemini grounding su topic pertinente]
</web_context>

--------------------------------
[ RICHIESTA UTENTE ]
```

---

## I 4 Moduli di Contesto

### 1. `<environment_snapshot>`
Estrae le informazioni dell'ambiente di lavoro corrente:
- Directory di lavoro attiva (`cwd`).
- Sistema operativo e architettura.
- Data e ora correnti (ISO 8601).
- Stato Git: branch corrente, indicatore `dirty` e lista fino agli ultimi 8 file modificati.

### 2. `<session_state>`
Recupera gli ultimi 3 messaggi dell'utente dalla sessione di `pi`. Il testo viene compresso e sanitizzato per evitare il bloat di token senza perdere il filo della conversazione.

### 3. `<durable_memory>` (Memoria Persistente Automatica)
Gestita tramite il file `~/.config/agy-pi/memory.json`:
- Registra l'obiettivo primario del progetto (`goal`), le decisioni prese (`decisions`), le convenzioni di codice (`conventions`) e le questioni aperte (`openQuestions`).
- **Auto-Update**: Quando la conversazione in `pi` supera i 24 turni, l'estensione estrae automaticamente i punti chiave e aggiorna `memory.json` per mantenere il contesto senza dover riinviare l'intero transcript.

### 4. `<web_context>` (Strada A: Ricerca Web Integrata)
Quando `webSearch` è impostato su `"auto"` o `"on"`, l'estensione valuta il prompt con la funzione euristica `needsWebSearch()`:

#### Filtri Negativi (Non effettuano ricerca web):
- Generazione ed editing di immagini (`agy_generate`, `agy_edit`, ecc.).
- Task di codice locale o refactoring.
- Comandi di gestione della conversazione o sintesi locale.

#### Trigger Positivi (Attivano la ricerca web):
- Riferimenti alla data/ora corrente (*"oggi"*, *"ultime notizie"*, *"2026"*).
- Domande su versioni di pacchetti, dipendenze o release note.
- Confronti tra tecnologie (*"differenza tra X e Y"*, *"migliore alternativa"*).
- Notizie o fatti di attualità.

La ricerca viene effettuata via API Gemini sfruttando la funzionalità di **Google Search Grounding**, ed i risultati vengono inseriti nel tag `<web_context>`.
Un sistema di cache temporale evita ricerche identiche ripetute entro 60 secondi.

---

## Gestione del Token Budget (Token Cap)

Il budget predefinito è di **1500 token**, suddiviso tra i diversi moduli:

- `environment_snapshot`: max ~300 token.
- `session_state`: max ~500 token.
- `durable_memory`: max ~400 token.
- `web_context`: max ~300 token.