# Architettura di agy-pi

Questo documento descrive la struttura interna e il ciclo di vita dell'estensione `agy-pi`, spiegando l'interazione tra l'agente host (`pi`), l'estensione Node.js/TypeScript e il subagent CLI (`agy`).

---

## Architettura dei Componenti

L'estensione `agy-pi` fa da ponte tra l'ambiente di esecuzione di `pi` e la CLI `agy` / API Google Gemini:

```mermaid
sequenceDiagram
    autonumber
    actor User as Utente / Tastiera (F12)
    participant PI as pi Agent Core
    participant EXT as agy-pi (extensions/index.ts)
    participant FFMPEG as ffmpeg & Audio Subsystem
    participant AGY as agy CLI (Antigravity)
    participant GEMINI as Google Gemini API

    rect rgb(30, 40, 60)
        note over User, EXT: Workflow Vocale F12
        User->>EXT: Pressione F12 (Start Record)
        EXT->>FFMPEG: Spawn ffmpeg (pulse -> wav 16kHz)
        EXT->>User: Audio sound "start" (aevalsrc)
        User->>EXT: Pressione F12 (Stop Record)
        EXT->>FFMPEG: SIGINT & optimizeAudio (silenceremove)
        EXT->>GEMINI: POST generateContent (Audio Opus/OGG + STT)
        GEMINI-->>EXT: Trascrizione testuale
        EXT->>EXT: Legge editorText & unisce contesto sessione
        EXT->>AGY: Interpretation prompt via executeAgy()
        AGY-->>EXT: Testo interpretato finale
        EXT->>PI: sendUserMessage(finalText)
    end

    rect rgb(40, 50, 30)
        note over PI, AGY: Tool Execution Workflow
        PI->>EXT: Execute Tool (es. agy_generate)
        EXT->>EXT: buildContextBlock() [Env + Memory + Web]
        EXT->>AGY: execFileAsync(agy -p prompt --output-format json)
        AGY-->>EXT: JSON Output & IMAGE_PATH
        EXT-->>PI: ToolResult { content, details }
    end
```

---

## Moduli Funzionali

### 1. Engine di Gestione dello Stato e Persistenza

L'estensione mantiene lo stato sia in memoria sia su disco attraverso diverse strutture dati:

- **Conversazione agy Multi-Turno**:
  - `~/.agy-chat/conversation_id`: File di testo contenente l'ID dell'ultima conversazione attiva.
  - `~/.gemini/antigravity-cli/conversations/`: Cartella gestita dalla CLI `agy` contenente i file SQLite `.db` con la cronologia dei turni.
- **Configurazione Persistente (`AgyConfig`)**:
  - `~/.config/agy-pi/config.json`: File protetto (permessi `0600`) che mantiene le preferenze di sistema (modello di default, backend STT/TTS, token budget, ecc.).
- **Memoria Durevole (`DurableMemory`)**:
  - `~/.config/agy-pi/memory.json`: Archivio dei fatti rilevanti (obiettivi, decisioni, convenzioni, questioni aperte) aggiornato in modo automatico.

### 2. Wrapper di Esecuzione `executeAgy()`

Tutte le interazioni con il binario `agy` passano attraverso la funzione asincrona `executeAgy()`:

```typescript
interface AgyExecOptions {
    prompt: string;
    mode?: "chat" | "image" | "analyze";
    model?: string;
    effort?: "low" | "medium" | "high";
    newConversation?: boolean;
    stateless?: boolean;
    addDirs?: string[];
    filePaths?: string[];
    yolo?: boolean;
    timeoutMs?: number;
    outputDir?: string;
    signal?: AbortSignal;
    contextBlock?: string;
}
```

#### Risoluzione Bug Output Format (`--output-format json`)
Quando `agy` viene eseguito in modalità non interattiva (piped/redirected), la CLI non scrive su `stdout` grezzo. Per superare questo limite, `executeAgy` aggiunge automaticamente il flag `--output-format json`, parsando la proprietà `.response` dell'oggetto ritornato.

---

## Ciclo di Vita di una Chiamata Tool

1. **Invocazione del Tool**: `pi` seleziona uno dei 13 tool registrati ed esegue il metodo `execute()`.
2. **Costruzione del Prompt**: Il tool trasforma i parametri strutturati in un prompt narrativo (es. aggiungendo `IMAGE_PATH` o clausole `Keep+Change+Add+Render`).
3. **Context Injection**: Se abilitato (`contextInject = true`), viene inserito il blocco `<CONTEXT_AGENTE>` preparato da `buildContextBlock()`.
4. **Esecuzione CLI / API**: Invocazione del binario `agy` con gestione dei timeout (3 min per chat/analisi, 5 min per immagini).
5. **Post-Processing Asset**: Se viene generata un'immagine, la funzione `extractImagePath()` rileva il percorso dall'output e `copyImage()` lo duplica eventualmente nella cartella di destinazione `outputDir`.
6. **Aggiornamento Stato**: Se la chiamata è stateful, l'ID della conversazione viene aggiornato in `~/.agy-chat/conversation_id`.
7. **Ritorno a pi**: Restituzione del risultato formattato secondo la specifica di `pi` (`{ content, details }`).