agy-pi/docs/architecture.md

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:

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():

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 }).