refactor: remove direct Gemini API integrations

Route F12 and audio transcription exclusively through Antigravity OAuth, and preserve cross-model history without reusing incompatible signatures.\n\nRemove direct Gemini API keys, web grounding, internal TTS, verified image generation, obsolete commands and configuration. Update documentation and restore the local voice workflow helpers required at runtime.
2026-09-03 12:52:13 +02:00
parent cde5aaa9b7
commit 4a88084b2b
13 changed files with 198 additions and 2197 deletions
@@ -1,276 +1,41 @@
 # agy-pi

-<p align="center">
-  <img src="assets/agy-pi-logo.jpg" alt="agy-pi logo" width="200"/>
-</p>
-
-Estensione per **pi** che integra **Google Antigravity CLI (`agy`)** come subagent multimodale.
-
-Anche se il modello di pi è text-only, questa estensione permette a pi di delegare a agy
-(che usa **Gemini multimodale**) task che richiedono immagini, audio e video, oltre a
-conversazioni di ragionamento multi-turno.
+Estensione per [pi](https://github.com/badlogic/pi-mono) che integra il client OAuth **Google Antigravity** (`agy`) come subagent multimodale. Non usa né gestisce chiavi Google AI Studio/Gemini API.

 ## Capacità

-| Capacità | Tool | Esempio |
-|---|---|---|
-| Conversazione multi-turno | `agy` | `agy(prompt="Analizza questo problema...")` |
-| Generazione immagini (strutturata) | `agy_generate` | `agy_generate(subject="un gatto", style="fotorealistico")` |
-| Editing controllato (Keep+Change+Add+Render) | `agy_edit` | `agy_edit(baseImage=..., change="...", keep="...")` |
-| Editing zona specifica (inpainting) | `agy_inpaint` | `agy_inpaint(baseImage=..., target="il divano", replacement="blu navy")` |
-| Style transfer | `agy_style_transfer` | `agy_style_transfer(baseImage=..., style="Van Gogh")` |
-| Composizione multi-immagine | `agy_compose` | `agy_compose(images=[...], instruction="...")` |
-| Consistenza personaggio | `agy_character` | `agy_character(referenceImage=..., name="Maya", task="...")` |
-| **Generazione verificata iterativa** | **`agy_create_verified`** | `agy_create_verified(requirements=..., maxIterations=3, useOpenCV=true)` |
-| Analisi file (imm/audio/video) | `agy_analyze` | `agy_analyze(filePath=..., question="...")` |
-| Trascrizione audio | `agy_transcribe` | `agy_transcribe(filePath="voce.wav", language="italiano")` |
-| Analisi video | `agy_video` | `agy_video(filePath="clip.mp4", question="...")` |
-| Elenco modelli | `agy_models` | `agy_models()` |
-| Gestione stato conversazione | `agy_conversation` | `agy_conversation(action="id" \| "list" \| "reset")` |
+- chat e ragionamento multi-turno;
+- generazione, editing, composizione e analisi immagini;
+- analisi video;
+- trascrizione audio e input vocale F12 tramite Antigravity;
+- catalogo modelli e stato conversazione Antigravity.

-L'agente (pi) decide autonomamente quale strumento usare in base al task richiesto.
+Strumenti principali: `agy`, `agy_generate`, `agy_edit`, `agy_inpaint`, `agy_style_transfer`, `agy_compose`, `agy_character`, `agy_analyze`, `agy_transcribe`, `agy_video`, `agy_models`, `agy_conversation`, `antigravity_chat`.

-### Generazione verificata (`agy_create_verified`)
+Non include TTS interno né generazione immagini verificata iterativa.

-Quando l'orchestratore di pi **non ha visione** e serve un'immagine conforme a
-specifiche precise, `agy_create_verified` esegue un loop self-contained:
+## Audio e F12

-```
-genera immagine (agy) → analizza con visione (PASS/FAIL vs requisiti)
-  → verifica OpenCV (dimensioni, colori, luminosità, bordi)
-  → rigenera con prompt di correzione se FAIL → ripete fino a maxIterations
+Premi **F12** per avviare/fermare la registrazione. L'audio viene ottimizzato, convertito in Opus/OGG e inviato al modello `voiceModel` tramite il gateway Antigravity OAuth. Il workflow genera trascrizione e prompt pulito; con `vocalPlanningMode=true` richiede una conferma nell'overlay prima dell'invio a pi.
+
+`agy_transcribe` usa la stessa pipeline Antigravity. Non esistono fallback a servizi con chiave API esterna. I suoni di start/stop/done sono effetti locali, non sintesi vocale.
+
+## Configurazione
+
+```text
+/agy:config
+/agy:config set voiceModel gemini-3.7-flash-medium
+/agy:status
 ```

-Restituisce l'immagine candidata finale + report di verifica (verdetto visione,
-metriche OpenCV ed eventuale edit programmatico per ogni iterazione). Parametri:
-`requirements`, `outputDir`, `maxIterations` (default 3), `useOpenCV` (default true),
-`editInstructions`, `editScript`, `model`.
-
-Con `editInstructions` il tool genera una trasformazione deterministica da applicare
-prima della verifica a ogni iterazione. In alternativa `editScript` accetta uno script
-Python esplicito con contratto `sys.argv[1]` input e `sys.argv[2]` output. Gli script
-sono eseguiti con timeout, directory di lavoro temporanea e allowlist di `cv2`,
-`numpy`, `PIL`, `json`, `sys` e `math`; import, rete, subprocess e accesso arbitrario
-al filesystem vengono rifiutati. Un edit fallito rende automaticamente non conforme
-l'iterazione.
-
-## Configurazione persistente (`/agy:config`)
-
-Tutte le impostazioni dell'estensione si gestiscono con il comando `/agy:config`
-(salvate in `~/.config/agy-pi/config.json`, permessi 600):
-
-```
-/agy:config                    # elenca tutte le impostazioni
-/agy:config get <chiave>       # mostra una chiave
-/agy:config set <chiave> <valore>  # imposta una chiave
-/agy:config reset              # ripristina i default
-```
-
-### Dialog TUI per la chiave Gemini (`/agy:key`)
-
-Per inserire/modificare la **chiave API Gemini** con un'interfaccia grafica in
-sovrimpressione (dialog TUI, campo mascherato) usa il comando `/agy:key`:
-
-```
-/agy:key
-```
-
-Apre un overlay centrato nel terminale:
-
- mostra la chiave attuale mascherata (`AIza...yfDY`)
- campo di input **mascherato** (digiti la chiave, vedi `•`)
- `Enter` conferma (salva in config + `~/.agy-chat/gemini-key`)
- `Esc` annulla
-
-È il modo interattivo e sicuro per impostare `geminiApiKey` senza digitarla in
-chiaro nella cronologia del terminale.
-
-### Diagnostica (`/agy:status`)
-
-Il comando `/agy:status` apre un overlay TUI con lo stato dell'estensione:
-
- binario agy (trovato/non trovato) e versione
- chiave Gemini valida/mancante (mascherata) e stato
- modello attivo, backend STT, notifiche TTS
- ultimo errore significativo dai log di agy
-
-Chiudi con `Enter` o `Esc`.
-
-### Context Injection (Fase 2) — `pi → agy`
-
-Quando il tool `agy` (o altri con l'opzione `injectContext`) invia un prompt a
-Gemini, l'estensione **inietta automaticamente** un blocco di contesto prima
-della richiesta utente, seguendo le best practice di context engineering:
-
-```
-<environment_snapshot>   ← cwd, OS, data/ora, git branch + file modificati
-<session_state>          ← ultimi messaggi utente pi (compatti, non il transcript)
-<durable_memory>         ← archivio fatti chiave (memory.json, auto-aggiornato)
-<web_context>            ← risultati ricerca web (Strada A, se pertinente)
--------------------------------
-[ RICHIESTA UTENTE ]      ← sempre per ultima (anti lost-in-the-middle)
-```
-
- **Tag XML** e richiesta per ultima (evidenze “Lost in the Middle”, TACL 2024)
- **Token cap** default ~1500 (chiave `contextTokens`)
- **Memoria durevole** automatica: oltre una soglia di turni, i punti chiave
-  vengono condensati in `~/.config/agy-pi/memory.json` invece di rigirare tutto
- **Ricerca web** (Strada A): con `webSearch=auto|on` l'estensione cerca con
-  l'API Gemini (`googleSearch` grounding) e inietta i risultati nel `<web_context>`
-
-| Chiave | Default | Descrizione |
-|---|---|---|
-| `geminiApiKey` | — | Chiave API Google Gemini (STT/TTS) |
-| `enne2ApiKey` | — | Token per il server proxy ai.enne2.net (opzionale) |
-| `sttBackend` | `gemini` | Backend trascrizione: `gemini` \| `enne2` |
-| `sttUrl` | `https://ai.enne2.net` | URL base backend enne2 |
-| `sttModel` | `gemma4:E4B` | Modello STT backend enne2 |
-| `sttMaxDuration` | `120` | Durata max registrazione (secondi) |
-| `ttsBackend` | `gemini` | Backend TTS: `gemini` \| `enne2` |
-| `ttsNotify` | `true` | Notifiche vocali automatiche |
-| `ttsModel` | `gemini-2.5-flash-preview-tts` | Modello TTS Gemini |
-| `agyBin` | `agy` | Path del binario agy |
-| `agyDefaultModel` | — | Modello predefinito per le chiamate agy |
-| `agyTimeoutMs` | `180000` | Timeout esecuzione agy (ms) |
-| `contextInject` | `true` | Iniezione contesto nel prompt agy |
-| `contextTokens` | `1500` | Token cap per il contesto iniettato |
-| `webSearch` | `auto` | Ricerca web Strada A: `auto` \| `on` \| `off` |
-| `vocalPlanningMode` | `true` | Piano + conferma in overlay dopo il vocale |
-| `sttDirectGemini` | `true` | Interpretazione multimodale diretta Gemini (anche con DeepSeek/Claude) |
-| `voiceModel` | `gemini-3.7-flash-medium` | Modello Gemini per l'audio |
-
-Le variabili d'ambiente (`GEMINI_API_KEY`, `AGY_STT_BACKEND`, ecc.) hanno
-priorità sul file di config quando impostate.
-
-## Registrazione microfono (F12)
-
-Premi **F12** per avviare/fermare la registrazione dal microfono (max 2 min).
-Il flusso: registra → taglia il silenzio → **trascrive con la Gemini API diretta**
-(`gemini-3.5-flash`, veloce e affidabile — agy CLI non supporta file audio) →
-interpreta con Gemini usando il contesto della conversazione → inserisce il
-risultato come prompt su pi.
-
-Con `vocalPlanningMode=true` (default) il flusso è **a 2 fasi con overlay TUI**:
-dopo la trascrizione, l'estensione genera un **piano** e mostra un popup di
-conferma con la trascrizione e il piano proposto:
-
-```
-🎙️ Conferma vocale
-   Trascrizione: "Aggiorna i docs..."
-   📋 Piano proposto: ...
-   Enter esegui • Esc annulla • E modifica • Spazio testo letterale • F12 registra di nuovo
-```
-
- **Enter** → esegue il piano (invia il risultato a pi)
- **Esc** → annulla, nessuna azione
- **E** → modifica il testo del piano manualmente
- **Spazio** → chiude il popup e inserisce nell'editor la **trascrizione letterale** di quanto dettato, senza inviare il piano proposto
- **F12** → registra di nuovo
-
-Questa modalità evita che l'interpretazione vocale avvii autonomamente loop
-agentici o modifiche a sorpresa: la direttiva di Gemini è "produci solo il piano,
-non eseguire nulla", e l'esecuzione parte solo dopo la tua conferma. Per tornare
-all'esecuzione diretta, imposta `vocalPlanningMode=false` con
-`/agy:config set vocalPlanningMode false`.
-
-Il testo scritto nel campo editor prima di avviare la registrazione viene letto
-(`getEditorText`) e **combinato con la trascrizione audio** nel piano, poi
-l'editor viene svuotato per evitare reinvii duplicati.
-
-**Requisito**: la key Gemini API in `~/.agy-chat/gemini-key` (chmod 600) o nella
-variabile d'ambiente `GEMINI_API_KEY`.
-
-```bash
-# una volta sola
-echo "LA_TUA_KEY" > ~/.agy-chat/gemini-key && chmod 600 ~/.agy-chat/gemini-key
-```
-
-**Backend di trascrizione** (variabile `AGY_STT_BACKEND`):
-
-| Backend | Descrizione | Configurazione |
-|---|---|---|
-| `gemini` (default) | Gemini API (`gemini-3.5-flash`), veloce e affidabile | key in `~/.agy-chat/gemini-key` |
-| `enne2` | Server locale `ai.enne2.net` con `gemma4:E4B` (supporta audio), ~2-3s | `AGY_STT_URL` (default `https://ai.enne2.net`), `AGY_STT_MODEL` (default `gemma4:E4B`) |
-
-```bash
-# usa il server locale
-export AGY_STT_BACKEND="enne2"
-```
-
-Comandi: `/agy:record` (toggle), `/agy:record:stop` (ferma).
+Le impostazioni sono in `~/.config/agy-pi/config.json`. Serve solo completare il login OAuth del client `agy`.

 ## Installazione

-Requisito: `agy` installato e autenticato (una volta: `agy`, poi login OAuth nel browser).
-
-```bash
-# da un repo git
-pi install git:github.com/<tuo-utente>/agy-pi
-
-# oppure da una cartella locale
-pi install /percorso/a/agy-pi
-```
-
-Per provare senza installare:
-
 ```bash
+pi install git:git.enne2.net/enne2/agy-pi
+# oppure
 pi -e /percorso/a/agy-pi
 ```

-## Uso
-
-### Come tool (chiamato automaticamente dal modello)
-
-Quando chiedi a pi di generare un'immagine, analizzare un file, o ragionare insieme a un
-secondo agente, pi può chiamare il tool `agy`. Esempi di prompt:
-
-```
-Genera un'immagine di un paesaggio marziano al tramonto.
-Analizza l'immagine /home/utente/foto.jpg e descrivila.
-Trascrivi il file audio /home/utente/voce.wav.
-Chiedi a agy di ragionare su questo problema e poi confronta la sua risposta con la tua.
-```
-
-### Come comando interattivo
-
-```
-/agy <prompt>        # invia un prompt a agy
-/agy:new             # forza una nuova conversazione
-/agy:list            # mostra la conversazione corrente
-/agy:reset           # azzera lo stato conversazione
-```
-
-## Parametri del tool `agy`
-
-| Parametro | Tipo | Descrizione |
-|---|---|---|
-| `prompt` | string (obbligatorio) | Il task/prompt per agy |
-| `mode` | `chat` \| `image` \| `analyze` | Tipo di operazione (default `chat`) |
-| `model` | string | Modello agy (es. `Gemini 3.1 Pro (High)`, `Claude Opus 4.6 (Thinking)`) |
-| `effort` | `low` \| `medium` \| `high` | Livello di ragionamento |
-| `newConversation` | boolean | Forza una nuova conversazione |
-| `addDir` | string | Cartella da aggiungere al workspace agy |
-| `filePath` | string | File (immagine/audio/video) da analizzare |
-| `yolo` | boolean | `--dangerously-skip-permissions` (necessario per audio/video) |
-
-## Multi-turno
-
-L'estensione mantiene l'ID della conversazione agy in `~/.agy-chat/conversation_id`.
-Ogni chiamata a `agy` continua la conversazione precedente, così agy ricorda i turni
-precedenti (ragionamento multi-shot). Usa `newConversation: true` per ripartire da zero.
-
-## Note di sicurezza
-
- `yolo: true` auto-approva tutti gli strumenti di agy. Usalo solo in ambienti fidati.
- Le estensioni pi girano con i permessi completi del sistema. Rivedi il codice prima di
-  installare pacchetti di terze parti.
-
-## Struttura
-
-```
-agy-pi/
-├── package.json          # manifest pi
-├── extensions/index.ts   # estensione (tool + comandi)
-├── bin/agy-chat.sh       # wrapper bash standalone (opzionale)
-└── README.md
-```
+Consulta `docs/configuration.md`, `docs/tools.md` e `docs/vocal-workflow.md` per i dettagli.
@@ -1,97 +1,17 @@
 # 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`).
+`agy-pi` collega pi al gateway OAuth Antigravity e alla 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
+```text
+pi → extension index.ts → Antigravity OAuth / agy CLI → modelli disponibili
 ```

---
+## Componenti

-## Moduli Funzionali
+- **CLI wrapper**: esegue `agy` per chat, immagini e video.
+- **Client Antigravity diretto**: usa OAuth e gli endpoint cloudcode-pa per provider, modelli, audio F12 e `antigravity_chat`.
+- **Pipeline audio**: `ffmpeg` registra/ottimizza, poi invia `inlineData` audio ad Antigravity.
+- **Context injection**: aggiunge ambiente, stato sessione e memoria locale.
+- **Persistenza**: configurazione in `~/.config/agy-pi/config.json`; conversazioni e token sono gestiti dal client Antigravity.

-### 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 }`).
+L'estensione non invia richieste a Google AI Studio/Gemini API tramite API key e non conserva tali chiavi.
@@ -1,70 +1,11 @@
-# Wrapper Script CLI (`bin/agy-chat.sh`)
+# Wrapper CLI `agy`

-Oltre all'estensione TypeScript per `pi`, il repository include lo script di utilità Bash standalone **`bin/agy-chat.sh`**.
+L'estensione usa il binario `agy` per chat, immagini e video. Il binario deve essere installato e autenticato tramite OAuth Antigravity.

---
+Configurazione utile:

-## Scopo dello Script
+- `agyBin`: percorso al binario;
+- `agyDefaultModel`: modello predefinito;
+- `agyTimeoutMs`: timeout chiamate.

-Lo script permette di eseguire conversazioni multi-turno con `agy` direttamente dal terminale shell, mantenendo la persistenza dell'ID conversazione in `~/.agy-chat/conversation_id` esattamente come fa l'estensione Node.js.
-
---
-
-## Sintassi & Parametri
-
-```bash
-./bin/agy-chat.sh [OPZIONI] "PROMPT"
-```
-
-### Tabella dei Parametri
-
-| Opzione | Descrizione |
-|---|---|
-| `"prompt"` | Il prompt o task da inviare ad `agy` |
-| `--new` | Forza l'avvio di una nuova conversazione (ignora l'ID salvato) |
-| `--reset` | Elimina il file di stato `conversation_id` ed esce |
-| `--id` | Stampa l'ID della conversazione attualmente attiva ed esce |
-| `--list` | Elenca le conversazioni recenti salvate nel database SQLite di `agy` |
-| `--resume <id>` | Riprende una conversazione specifica indicando il suo ID |
-| `--model <nome>` | Specifica il modello LLM (es. `--model "Gemini 3.1 Pro (High)"`) |
-| `--effort <livello>` | Livello di reasoning: `low` \| `medium` \| `high` |
-| `--add-dir <path>` | Aggiunge una directory al contesto di lavoro di `agy` |
-| `--yolo` | Passa il flag `--dangerously-skip-permissions` ad `agy` |
-
---
-
-## Esempi d'Uso
-
-### 1. Avviare o Continuare una Conversazione
-```bash
-./bin/agy-chat.sh "Spiegami la differenza tra REST e GraphQL"
-```
-
-### 2. Continuare la Conversazione (Multi-Turno)
-```bash
-./bin/agy-chat.sh "Puoi fare un esempio in TypeScript per la risposta precedente?"
-```
-
-### 3. Forzare una Nuova Conversazione con Modello Specifico
-```bash
-./bin/agy-chat.sh --new --model "Gemini 3.1 Pro (High)" --effort high "Disegna l'architettura di un sistema a microservizi"
-```
-
-### 4. Gestione dello Stato
-```bash
-# Mostra l'ID attivo
-./bin/agy-chat.sh --id
-
-# Elenca tutte le conversazioni salvate
-./bin/agy-chat.sh --list
-
-# Ripristina lo stato
-./bin/agy-chat.sh --reset
-```
-
---
-
-## Variabili d'Ambiente Supportate
-
- **`AGY_CHAT_STATE`**: Directory del file di stato (default: `~/.agy-chat`).
- **`AGY_BIN`**: Percorso dell'eseguibile `agy` (default: `agy` presente nel `PATH`).
+L'audio non passa dal wrapper CLI: F12 e `agy_transcribe` usano il client Antigravity diretto con `inlineData`.
@@ -1,89 +1,18 @@
-# Comandi Slash & Scorciatoie da Tastiera
+# Comandi e scorciatoie

-`agy-pi` mette a disposizione un ricco set di comandi slash interattivi e scorciatoie globali per interagire con l'estensione direttamente dal terminale di `pi`.
+## Comandi

---
+- `/agy <prompt>`: invia un task al subagent Antigravity.
+- `/agy:config [get|set|reset]`: gestisce la configurazione locale.
+- `/agy:status`: mostra stato di agy, modello e pipeline audio.
+- `/agy:record`: avvia/ferma la registrazione vocale.
+- `/agy:record:stop`: ferma una registrazione in corso.
+- `/agy:record:cancel`: annulla una registrazione in corso.
+- `/agy:refresh-models`: aggiorna il catalogo Antigravity.

-## Comandi Slash (Slash Commands)
+Non esistono comandi per inserire chiavi Gemini API, per TTS interno o per generazione immagini verificata.

-### Gestione Conversazione agy
+## Scorciatoie

-| Comando | Descrizione | Sintassi / Esempio |
-|---|---|---|
-| `/agy` | Invia un prompt diretto al subagent `agy` | `/agy Spiega la teoria della relatività` |
-| `/agy:new` | Forza la creazione di una nuova conversazione pulita | `/agy:new` |
-| `/agy:list` | Mostra l'ID della conversazione agy attiva | `/agy:list` |
-| `/agy:reset` | Azzera l'ID conversazione salvato in locale | `/agy:reset` |
-
---
-
-### Configurazione & Diagnostica TUI
-
-#### `/agy:config`
-Gestisce le opzioni di configurazione salvate in `~/.config/agy-pi/config.json`.
-
- `/agy:config`: Mostra l'elenco completo di tutte le opzioni con i valori attuali e le descrizioni.
- `/agy:config get <chiave>`: Stampa il valore di una singola chiave.
- `/agy:config set <chiave> <valore>`: Modifica il valore di una chiave e salva su disco.
- `/agy:config reset`: Ripristina le impostazioni predefinite di fabbrica.
-
-#### `/agy:key` (Dialog TUI Overlay)
-Apre una finestra di dialogo grafica in sovrimpressione nel terminale (`pi-tui` overlay) per inserire o modificare la chiave API Gemini:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ 🔑 Chiave API Gemini                                   │
-│ Attuale: AIza...yfDY                                   │
-│                                                        │
-│ Nuova chiave: •••••••••••••••••••••••••••••••••••••    │
-│                                                        │
-│ Digita la chiave • Enter conferma • Esc annulla        │
-└────────────────────────────────────────────────────────┘
-```
- Input mascherato per prevenire il leak della chiave sul terminale o nella cronologia.
- Salva contemporaneamente la chiave in `~/.config/agy-pi/config.json` e in `~/.agy-chat/gemini-key` (permessi `0600`).
-
-#### `/agy:status` (Diagnostica TUI Overlay)
-Mostra una dashboard grafica centrata con lo stato di salute dell'estensione:
-
-```
-┌────────────────────────────────────────────────────────┐
-│ 📊 Stato agy-pi                                        │
-│                                                        │
-│ Binario agy: trovato /home/enne2/.local/bin/agy        │
-│ Versione: agy version 1.4.2                            │
-│ Chiave Gemini: ✅ valida                               │
-│ Chiave (mask): AIza...yfDY                             │
-│ Modello attivo: Gemini 3.1 Pro (High)                  │
-│ Backend STT: gemini                                    │
-│ Notifiche TTS: true                                    │
-│                                                        │
-│ Ultimo errore: (nessuno)                               │
-│                                                        │
-│ Enter o Esc per chiudere                               │
-└────────────────────────────────────────────────────────┘
-```
-
---
-
-### Registrazione Vocale & TTS
-
-| Comando | Descrizione |
-|---|---|
-| `/agy:record` | Avvia o ferma la registrazione vocale (equivalente al tasto **F12**). |
-| `/agy:record:stop` | Ferma la registrazione attiva ed elabora l'audio. |
-| `/agy:record:cancel` | Annulla la registrazione corrente senza inviare prompt. |
-| `/agy:speak <testo>` | Sintetizza ed esegue l'audio del testo specificato via Gemini TTS. |
-| `/agy:vocal [on\|off\|status]` | Attiva (`on`), disattiva (`off`) o mostra lo stato (`status`) del feedback vocale automatico TTS. |
-
---
-
-## Scorciatoie da Tastiera (Keybindings)
-
-### Tasto `F12` — Registrazione Vocale Toggle
- **Primo tocco (`F12`)**: Avvia la registrazione audio tramite `ffmpeg`, riproduce il suono sci-fi *Power Up* e mostra la barra di stato live `🔴 REGISTRAZIONE... MM:SS / MM:SS`.
- **Secondo tocco (`F12`)**: Interrompe la registrazione, riproduce il suono *Deactivate*, ottimizza l'audio (soppressione silenzio), invia la traccia a Gemini per la trascrizione e trasmette il prompt risultante a `pi`.
-
-### Tasto `Ctrl+Esc` — Annullamento Registrazione
- Durante una registrazione audio attiva, premere `Ctrl+Esc` abortisce immediatamente il processo `ffmpeg`, rimuove il file temporaneo, riproduce il tono acustico di cancellazione e cancella l'indicatore di stato.
- `Esc` da solo è riservato alla combinazione built-in di pi (`app.interrupt`), quindi l'estensione usa `Ctrl+Esc` per evitare il conflitto.
+- `F12`: avvia/ferma la registrazione vocale Antigravity.
+- `Ctrl+Esc`: annulla la registrazione attiva.
@@ -1,87 +1,29 @@
-# Sistema di Configurazione
+# Configurazione

-L'estensione `agy-pi` implementa un sistema di configurazione gerarchico e persistente, progettato per garantire massima sicurezza ed elasticità sia in ambienti locali che server.
+`agy-pi` salva la configurazione in `~/.config/agy-pi/config.json` (permessi `0600`). Non richiede né legge chiavi Google AI Studio: chat, audio e multimodalità usano l'account OAuth Antigravity di `agy`.

---
+## Opzioni

-## File di Configurazione (`config.json`)
+| Chiave | Default | Descrizione |
+|---|---:|---|
+| `sttMaxDuration` | `120` | Durata massima della registrazione F12, in secondi. |
+| `voiceModel` | `gemini-3.7-flash-medium` | Modello Antigravity multimodale usato per audio e trascrizione. |
+| `agyBin` | `agy` | Percorso del binario `agy`. |
+| `agyDefaultModel` | — | Modello predefinito delle chiamate CLI. |
+| `agyTimeoutMs` | `180000` | Timeout delle chiamate CLI, in millisecondi. |
+| `contextInject` | `true` | Inietta ambiente, stato sessione e memoria locale. |
+| `contextTokens` | `1500` | Budget del contesto iniettato. |
+| `vocalPlanningMode` | `true` | Mostra il piano vocale prima dell'invio a pi. |

-Le impostazioni vengono memorizzate nel file JSON:
-`~/.config/agy-pi/config.json`
+Gestione interattiva:

-!!! security "Sicurezza e Permessi"
-    Il file `config.json` viene creato con permessi restrittivi `0600` (leggibile e modificabile unicamente dall'utente proprietario del processo) per prevenire l'accesso non autorizzato alle chiavi API memorizzate.
-
---
-
-## Gerarchia delle Risoluzione Chiavi
-
-Quando un modulo o un tool dell'estensione richiede un valore di configurazione (es. `geminiApiKey`), l'estensione segue questa priorità:
-
-```mermaid
-graph TD
-    ENV[1. Variabili d'Ambiente System/Shell] -->|Se assente| CONFIG[2. File ~/.config/agy-pi/config.json]
-    CONFIG -->|Se assente| SECRET[3. File ~/.agy-chat/gemini-key]
-    SECRET -->|Se assente| DEFAULT[4. Valore Default di Fabbrica CONFIG_DEFAULTS]
+```text
+/agy:config
+/agy:config get voiceModel
+/agy:config set voiceModel gemini-3.7-flash-medium
+/agy:config reset
 ```

---
+## Requisito di autenticazione

-## Tabella delle Opzioni di Configurazione
-
-| Chiave | Tipo | Default | Descrizione |
-|---|---|---|---|
-| `geminiApiKey` | `string` | `undefined` | Chiave API Google Gemini (usata per STT, TTS e Web Search grounding). |
-| `enne2ApiKey` | `string` | `undefined` | Bearer token opzionale per l'autenticazione verso il proxy `ai.enne2.net`. |
-| `sttBackend` | `string` | `"gemini"` | Backend per la trascrizione vocale: `"gemini"` \| `"enne2"`. |
-| `sttUrl` | `string` | `"https://ai.enne2.net"` | URL endpoint base per il backend STT enne2. |
-| `sttModel` | `string` | `"gemma4:E4B"` | Identificativo modello per il backend STT enne2. |
-| `sttMaxDuration` | `number` | `120` | Durata massima della registrazione audio in secondi. |
-| `ttsBackend` | `string` | `"gemini"` | Backend per la sintesi vocale: `"gemini"` \| `"enne2"`. |
-| `ttsNotify` | `boolean` | `true` | Abilita o disabilita le notifiche acustiche/vocali automatiche a fine trascrizione. |
-| `ttsModel` | `string` | `"gemini-2.5-flash-preview-tts"` | Modello Gemini dedicato al Text-To-Speech. |
-| `agyBin` | `string` | `"agy"` | Percorso assoluto o nome del binario eseguibile `agy`. |
-| `agyDefaultModel` | `string` | `undefined` | Modello predefinito per le chiamate ad `agy` (es. `Gemini 3.1 Pro (High)`). |
-| `agyTimeoutMs` | `number` | `180000` | Timeout generale in millisecondi per l'esecuzione di `agy` (3 minuti). |
-| `contextInject` | `boolean` | `true` | Iniezione automatica del contesto dell'agente nel prompt `agy`. |
-| `contextTokens` | `number` | `1500` | Budget massimo di token allocato per il blocco di contesto iniettato. |
-| `webSearch` | `string` | `"auto"` | Modalità ricerca web (Strada A): `"auto"` \| `"on"` \| `"off"`. |
-| `vocalPlanningMode` | `boolean` | `true` | Workflow vocale a 2 fasi: piano + conferma in overlay prima di eseguire. |
-
---
-
-## Esempio di File `config.json`
-
-```json
-{
-  "sttBackend": "gemini",
-  "sttUrl": "https://ai.enne2.net",
-  "sttModel": "gemma4:E4B",
-  "sttMaxDuration": 120,
-  "ttsBackend": "gemini",
-  "ttsNotify": true,
-  "ttsModel": "gemini-2.5-flash-preview-tts",
-  "agyTimeoutMs": 180000,
-  "contextInject": true,
-  "contextTokens": 1500,
-  "webSearch": "auto",
-  "vocalPlanningMode": true,
-  "geminiApiKey": "AIzaSyD-EXAMPLE_KEY_STRING_HERE"
-}
-```
-
---
-
-## Variabili d'Ambiente Mappate
-
-Le seguenti variabili di ambiente sovrascrivono la configurazione quando presenti:
-
-```bash
-export GEMINI_API_KEY="AIzaSy..."
-export ENNE2_API_KEY="sk-..."
-export AGY_STT_BACKEND="enne2"    # oppure "gemini"
-export AGY_STT_URL="https://ai.enne2.net"
-export AGY_STT_MODEL="gemma4:E4B"
-export AGY_BIN="/home/utente/.local/bin/agy"
-export AGY_TTS_NOTIFY="0"         # disabilita notifiche TTS
-```
+Accedi una volta tramite `agy`; il token OAuth Antigravity è gestito dal client. `/agy:status` mostra binario, versione, modello e stato della pipeline audio.
@@ -1,89 +1,13 @@
-# Context Injection Engine (Fase 2)
+# Context injection

-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.
+Quando `injectContext` è attivo, agy-pi aggiunge al prompt del subagent Antigravity un blocco compatto:

+```text
 <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 ]
 ```

---
+Il budget è configurabile con `contextTokens` (default 1500). Il testo dell'utente viene mantenuto dopo il blocco di contesto.

-## 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.
+L'estensione non esegue ricerche web autonome. Per dati correnti, notizie o documentazione aggiornata il modello principale deve usare gli strumenti web disponibili in pi.
@@ -1,77 +1,10 @@
 # Panoramica di agy-pi

-<p align="center">
-  <img src="../assets/agy-pi-logo.jpg" alt="agy-pi logo" width="220"/>
-</p>
+`agy-pi` integra Antigravity in pi per delega testuale e multimodale. Il client usa il login OAuth di `agy` e mette a disposizione Gemini, Claude e gli altri modelli presenti nel catalogo Antigravity.

-**`agy-pi`** è un'estensione avanzata per **pi** (`@earendil-works/pi-coding-agent`) che integra **Google Antigravity CLI (`agy`)** e le API di **Gemini multimodale** come subagent autonomo e assistente multimodale dentro l'ambiente di pi.
+Funzioni: chat, immagini, video, analisi immagini, trascrizione audio e workflow vocale F12. Le operazioni audio passano esclusivamente da Antigravity; l'estensione non richiede una chiave Gemini API separata.

---
-
-## Il Problema & La Soluzione
-
-| Sfida | Soluzione offertata da `agy-pi` |
-|---|---|
-| **Limitazione Text-Only di pi** | `agy-pi` agisce da ponte multimodale: pi delega ad `agy` l'elaborazione di immagini, audio, video e compiti di ragionamento profondo. |
-| **Generazione & Editing Immagini** | Implementa formule narrative strutturate ([Soggetto]+[Azione]+[Stile], Keep+Change+Add+Render, Inpainting, Style Transfer, Composizione Multi-Immagine, Character Consistency). |
-| **Input Vocale Senza Mani** | Scorciatoia **F12** con registrazione microfono, indicatore TUI live, soppressione silenzio, feedback sonori sci-fi e trascrizione nativa via Gemini/enne2. |
-| **Multimodalità Ibrida (Voce + Tastiera)** | Integra automaticamente il testo presente nel campo editor di pi con il messaggio vocale registrato. |
-| **Context Lost in the Middle** | Sistema di Context Injection in 4 fasi (`<environment_snapshot>`, `<session_state>`, `<durable_memory>`, `<web_context>`) con token cap ed euristiche anti-ridondanza. |
-
---
-
-## Caratteristiche Principali
-
-```mermaid
-graph TD
-    PI[pi Coding Agent] -->|Tool Call / Slash Command| EXT[agy-pi Extension]
-    
-    subgraph Core Features
-        EXT --> TOOLS[14 Specialized Tools]
-        EXT --> VOCAL[Workflow Vocale F12]
-        EXT --> CTX[Context Injection Engine]
-        EXT --> TUI[TUI Overlays /agy:key & /agy:status]
-    end
-    
-    TOOLS --> AGY_CLI[Google Antigravity CLI agy]
-    VOCAL --> GEMINI_STT[Gemini STT / enne2 STT]
-    VOCAL --> GEMINI_TTS[Gemini TTS / Feedbacks Sonori]
-    CTX --> MEMORY[Memory JSON & Web Search Grounding]
-```
-
-1. **Subagent Multimodale Avanzato**: Espone 14 strumenti specializzati riconosciuti dall'LLM di pi per generare, modificare ed analizzare asset multimediali, inclusa la **generazione verificata iterativa** (`agy_create_verified`) con verifica visione + OpenCV dinamico.
-2. **Sistema di Configurazione Persistente**: Configurazione via `/agy:config` salvata con permessi restrittivi `0600` in `~/.config/agy-pi/config.json`.
-3. **Interfaccia Grafica TUI**: Dialoghi interattivi in sovrimpressione (`/agy:key` per mascherare e gestire la chiave API Gemini e `/agy:status` per la diagnostica di sistema).
-4. **Modulo Vocale Sci-Fi Integrato**: Registrazione ad alte prestazioni via `ffmpeg`, rilevamento automatico del parlato (`volumedetect`), compressione `libopus`/`libmp3lame` e feedback acustici sintetizzati proceduralmente.
-
---
-
-## Requisiti e Dipendenze
-
- **Node.js**: >= 18.x / v22.x
- **pi-coding-agent**: `@earendil-works/pi-coding-agent`
- **Google Antigravity CLI (`agy`)**: Installato e autenticato in locale (es. `~/.local/bin/agy`).
- **ffmpeg**: Necessario per il recording del microfono, la rimozione del silenzio e i feedback sonori procedurali.
- **Utilità Audio System**: `paplay` (PulseAudio), `aplay` (ALSA) o `ffplay`.
-
---
-
-## Installazione Rapida
-
-```bash
-# Installazione da repository locale
-pi install /percorso/a/agy-pi
-
-# Oppure test dinamico senza installazione permanente
-pi -e /percorso/a/agy-pi
-```
-
-Configura la chiave API Gemini per la trascrizione vocale e la ricerca web:
-
-```bash
-# Tramite overlay grafico dentro pi:
-/agy:key
-
-# Oppure via linea di comando:
-/agy:config set geminiApiKey AIzaSy...
-```
+- Configurazione: [configuration.md](configuration.md)
+- Tools: [tools.md](tools.md)
+- Workflow vocale: [vocal-workflow.md](vocal-workflow.md)
+- Comandi: [commands-keybindings.md](commands-keybindings.md)
@@ -1,196 +1,25 @@
-# Strumenti Registrati (Tools)
+# Strumenti registrati

-L'estensione `agy-pi` espone **14 strumenti (tools)** all'agente principale `pi`. Ciascun tool è definito tramite schemi strict `TypeBox` e fornisce istruzioni dettagliate al modello su come e quando utilizzarlo.
+| Tool | Scopo |
+|---|---|
+| `agy` | Subagent Antigravity per chat e ragionamento multi-turno. |
+| `agy_generate` | Generazione immagini. |
+| `agy_edit` | Editing controllato di un'immagine. |
+| `agy_inpaint` | Modifica localizzata. |
+| `agy_style_transfer` | Trasferimento di stile. |
+| `agy_compose` | Composizione di più immagini. |
+| `agy_character` | Consistenza di personaggio/oggetto. |
+| `agy_analyze` | Analisi immagine. |
+| `agy_transcribe` | Trascrizione audio tramite Antigravity OAuth. |
+| `agy_video` | Analisi di video. |
+| `agy_models` | Elenco modelli Antigravity disponibili. |
+| `agy_conversation` | Stato della conversazione agy. |
+| `antigravity_chat` | Richiesta diretta al gateway Antigravity. |

---
+## `agy_transcribe`

-## Tabella Riassuntiva
+Accetta `filePath` e, opzionalmente, `language`. Converte WAV in Opus/OGG quando utile e invia l'audio al modello configurato in `voiceModel` tramite Antigravity. Non usa chiavi API esterne né fallback a provider diversi.

-| Tool | Scopo Principale | Modalità | Timeout Default |
-|---|---|---|---|
-| [`agy`](#1-agy) | Subagent generico multi-turno (chat, image, analyze) | Dynamic | 180s |
-| [`agy_generate`](#2-agy_generate) | Generazione immagini strutturata | Image | 300s |
-| [`agy_edit`](#3-agy_edit) | Editing immagini controllato (Keep+Change+Add) | Image | 300s |
-| [`agy_inpaint`](#4-agy_inpaint) | Inpainting / In-place editing di zone specifiche | Image | 300s |
-| [`agy_style_transfer`](#5-agy_style_transfer) | Trasferimento di stile artistico | Image | 300s |
-| [`agy_compose`](#6-agy_compose) | Fusione / Composizione di più immagini | Image | 300s |
-| [`agy_character`](#7-agy_character) | Consistenza del personaggio tra generazioni | Image | 300s |
-| [`agy_analyze`](#8-agy_analyze) | Analisi file multimediali (immagini, audio, video) | Analyze | 180s |
-| [`agy_transcribe`](#9-agy_transcribe) | Trascrizione audio nativa via Gemini/enne2 API | API | 120s |
-| [`agy_video`](#10-agy_video) | Analisi e ispezione scene/codec file video | Analyze | 180s |
-| [`agy_tts`](#11-agy_tts) | Sintesi vocale Text-To-Speech nativa Gemini | API | 60s |
-| [`agy_models`](#12-agy_models) | Lista modelli disponibili su agy CLI | CLI | 30s |
-| [`agy_conversation`](#13-agy_conversation) | Ispezione e gestione stato conversazione | System | Instant |
-| [`agy_create_verified`](#14-agy_create_verified) | Generazione immagine iterativa con verifica | Image | 300s |
+## Contesto

---
-
-## Dettaglio degli Strumenti
-
-### 1. `agy`
-Tool generico per delegare un task ad `agy`. Mantiene lo stato della conversazione (multi-shot reasoning).
-
- **Parametri**:
-  - `prompt` (`string`, obbligatorio): Il task da inviare ad agy.
-  - `mode` (`"chat" | "image" | "analyze"`, opzionale): Tipo di operazione (default `"chat"`).
-  - `model` (`string`, opzionale): Modello agy (es. `Gemini 3.1 Pro (High)`).
-  - `effort` (`"low" | "medium" | "high"`, opzionale): Livello di reasoning.
-  - `newConversation` (`boolean`, opzionale): Se `true`, azzera lo stato e parte da zero.
-  - `addDir` (`string`, opzionale): Cartella da aggiungere al contesto di workspace agy.
-  - `filePath` (`string`, opzionale): File da allegare.
-  - `yolo` (`boolean`, opzionale): Abilita `--dangerously-skip-permissions`.
-  - `injectContext` (`boolean`, opzionale): Abilita la context injection (default `true`).
-  - `webSearch` (`boolean`, opzionale): Override ricerca web per questo prompt.
-
---
-
-### 2. `agy_generate`
-Generazione da zero di immagini basata su formule narrative trasparenti per il modello Gemini Image Generation.
-
- **Formula costruita**: `[Soggetto] + [Azione] + [Luogo] + [Composizione] + [Stile] + [Illuminazione] + [Aspect Ratio]`
- **Parametri principali**:
-  - `subject` (`string`, obbligatorio): Descrizione del soggetto primario.
-  - `action`, `location`, `composition`, `style`, `lighting`, `aspectRatio` (`string`, opzionali).
-  - `text` (`string`, opzionale): Testo grafico da incorporare.
-  - `negative` (`string`, opzionale): Elementi da evitare.
-  - `outputDir` (`string`, opzionale): Directory in cui salvare l'immagine generata.
-
---
-
-### 3. `agy_edit`
-Modifica controllata di un'immagine esistente basata sulla regola **Keep + Change + Add + Render**.
-
- **Best Practice Gemini**: Viene apportata una sola modifica per turno per evitare degrado dell'immagine base.
- **Parametri principali**:
-  - `baseImage` (`string`, obbligatorio): Percorso dell'immagine sorgente.
-  - `keep` (`string`, obbligatorio): Elementi da mantenere inalterati (posa, luci, volto, ecc.).
-  - `change` (`string`, obbligatorio): La modifica principale richiesta.
-  - `add` (`string`, opzionale): Nuovi elementi da aggiungere.
-  - `render` (`string`, opzionale): Target estetico di output (es. *"fotorealismo editoriale"*).
-  - `preserveAspectRatio` (`boolean`, opzionale): Preserva la proporzione originale.
-
---
-
-### 4. `agy_inpaint`
-Inpainting / Semantic Masking: modifica un elemento ben circoscritto senza alterare il contesto circostante.
-
- **Parametri**:
-  - `baseImage` (`string`, obbligatorio): Percorso immagine di partenza.
-  - `target` (`string`, obbligatorio): Oggetto/area specifica da cambiare (es. *"la giacca del soggetto"*).
-  - `replacement` (`string`, obbligatorio): Nuova descrizione dell'oggetto (es. *"un giubbotto in pelle nera"*).
-  - `keepRest` (`string`, opzionale): Dettagli da preservare (default: *"tutto il resto"*).
-
---
-
-### 5. `agy_style_transfer`
-Trasferimento di stile artistico preservando la composizione e i volumi dell'immagine base.
-
- **Parametri**:
-  - `baseImage` (`string`, obbligatorio): Immagine sorgente.
-  - `style` (`string`, obbligatorio): Stile di destinazione (es. *"Acquerello Impressionista"*, *"Cyberpunk Neon"*, *"Disegno Tecnico"*).
-  - `preserve` (`string`, opzionale): Cosa mantenere (default: *"la composizione originale"*).
-
---
-
-### 6. `agy_compose`
-Combina da 2 a 14 immagini in un unico scatto armonioso.
-
- **Parametri**:
-  - `images` (`string[]`, obbligatorio): Elenco dei percorsi immagine.
-  - `instruction` (`string`, obbligatorio): Istruzioni su quali elementi prendere da ciascuna immagine e come fonderli.
-
---
-
-### 7. `agy_character`
-Garantisce la consistenza visiva di un personaggio o oggetto attraverso più scatti.
-
- **Parametri**:
-  - `referenceImage` (`string`, obbligatorio): Immagine di riferimento con la fisionomia del personaggio.
-  - `name` (`string`, obbligatorio): Nome/Token identificativo (es. *"Avatar-Elena"*).
-  - `features` (`string`, obbligatorio): Tratti somatici/caratteristici immutabili.
-  - `task` (`string`, obbligatorio): Nuova azione o contesto in cui inserire il personaggio.
-
---
-
-### 8. `agy_analyze`
-Analizza in dettaglio qualsiasi file multimediale supportato (immagini, tracce audio o video).
-
- **Parametri**:
-  - `filePath` (`string`, obbligatorio): Percorso del file.
-  - `question` (`string`, opzionale): Domanda di analisi specifica.
-  - `yolo` (`boolean`, opzionale): Auto-approvazione permessi CLI (obbligatorio per audio/video).
-
---
-
-### 9. `agy_transcribe`
-Esegue la trascrizione audio ad alta velocità direttamente tramite le API Gemini (`gemini-3.5-flash`) o il server proxy `enne2`.
-
- **Parametri**:
-  - `filePath` (`string`, obbligatorio): File audio (WAV, MP3, OGG, M4A).
-  - `language` (`string`, opzionale): Lingua parlata (es. `"italiano"`).
-
---
-
-### 10. `agy_video`
-Ispezione approfondita di clip video: descrizione delle scene, analisi del movimento, verifica traccia audio, codec e risoluzione.
-
- **Parametri**:
-  - `filePath` (`string`, obbligatorio): Percorso del file video MP4/MOV/MKV.
-  - `question` (`string`, opzionale): Quesito specifico sulla clip.
-
---
-
-### 11. `agy_tts`
-Converte un testo in parlato e lo riproduce in locale tramite l'API Gemini TTS (`gemini-2.5-flash-preview-tts`).
-
- **Parametri**:
-  - `text` (`string`, obbligatorio): Testo da sintetizzare.
-  - `play` (`boolean`, opzionale): Riproduci subito l'audio (default `true`).
-  - `outputDir` (`string`, opzionale): Cartella di salvataggio del file WAV risultante.
-
---
-
-### 12. `agy_models`
-Elenca i modelli LLM e Vision attualmente disponibili nell'installazione di `agy`.
-
---
-
-### 13. `agy_conversation`
-Strumento di utilità di sistema per ispezionare o azzerare lo stato della conversazione.
-
- **Parametri**:
-  - `action` (`"id" | "list" | "reset"`, obbligatorio): Action richiesta.
-
---
-
-### 14. `agy_create_verified`
-Genera un'immagine **conforme a requisiti specifici** tramite un loop iterativo
-self-contained: genera → analizza con visione → verifica con OpenCV dinamico →
-rigenera se necessario. Ideale quando l'orchestratore di `pi` **non ha visione**.
-
-Il loop (fino a `maxIterations`):
-
-```
-1. Genera immagine con agy (mode image) dai requisiti
-2. Analizza con visione testuale → giudice PASS/FAIL vs requisiti
-3. Verifica con OpenCV DINAMICO → script generato dall'LLM ad hoc
-4. Se FAIL → rigenera con prompt di correzione (ri-attacca immagine base)
-```
-
-La **verifica OpenCV è dinamica**: l'LLM genera a runtime uno script
-Python/OpenCV specifico per i requisiti dell'immagine (non metriche hardcodate),
-che restituisce un JSON standard:
-
-```json
-{"pass": true/false, "score": 0..1, "findings": [...], "errors": [...]}
-```
-
-La decisione di conformità combina visione PASS + OpenCV PASS; le `findings`
-OpenCV vengono iniettate nelle issue per guidare la rigenerazione.
-
- **Parametri**:
-  - `requirements` (`string`, obbligatorio): Requisiti precisi che l'immagine deve soddisfare.
-  - `outputDir` (`string`, opzionale): Cartella di salvataggio dell'immagine finale.
-  - `maxIterations` (`number`, opzionale): Limite iterazioni (default 3, max 5).
-  - `useOpenCV` (`boolean`, opzionale): Esegue la verifica OpenCV dinamica (default `true`).
-  - `model` (`string`, opzionale): Modello agy.
+`agy` può ricevere un blocco con ambiente, stato della sessione e memoria locale tramite `injectContext`. La ricerca web non è svolta dall'estensione: per informazioni aggiornate usa gli strumenti web dell'agente principale.
@@ -1,67 +1,23 @@
-# Troubleshooting & Diagnostica
+# Troubleshooting

-Guida alla risoluzione dei problemi comuni durante l'utilizzo dell'estensione `agy-pi`.
+## `/agy:status`

---
+Usa `/agy:status` per verificare il binario `agy`, la versione, il modello configurato, la pipeline audio Antigravity e l'ultimo errore dai log.

-## 1. Strumento Diagnostico Integrato (`/agy:status`)
+## Problemi comuni

-Prima di procedere con la ricerca manuale dei guasti, esegui il comando slash dentro `pi`:
+### `agy` non trovato

-```
-/agy:status
-```
+Installa il client e completa il login OAuth, oppure imposta `agyBin` con `/agy:config set agyBin <percorso>`.

-L'overlay TUI diagnostico verificherà automaticamente:
- Esistenza e versione dell'eseguibile `agy`.
- Presenza e validità della chiave API Gemini.
- Backend STT e stato notifiche TTS attivi.
- Ultimo messaggio di errore registrato nei log di `agy`.
+### F12 non trascrive

---
+Verifica microfono/PulseAudio e `ffmpeg`. Se viene rilevato silenzio, registra di nuovo con volume più alto. Se Antigravity fallisce, controlla autenticazione e quota dell'account con `/agy:status`.

-## 2. Problemi Frequenti e Soluzioni
+### Immagine non trovata

-### A. Binario `agy` non trovato (`bash: agy: command not found`)
- **Causa**: Il binario `agy` non si trova nel `PATH` di sistema o nell'ubicazione standard `~/.local/bin/agy`.
- **Soluzione**: Imposta il percorso esplicito dell'eseguibile:
-  ```
-  /agy:config set agyBin /percorso/assoluto/a/agy
-  ```
+Controlla l'output del tool agy e che la directory di destinazione sia scrivibile.

-### B. Registrazione vocale F12 fallita o senza audio
- **Causa 1**: `ffmpeg` non è installato nel sistema.
-  - **Soluzione**: Installa `ffmpeg` tramite il package manager della tua distribuzione (es. `sudo apt install ffmpeg`).
- **Causa 2**: Nessun parlato rilevato (`audioHasSpeech` ritorna errore).
-  - **Soluzione**: Verifica il microfono e alza il livello di guadagno di PulseAudio/ALSA.
- **Causa 3**: Mancanza dell'utility di riproduzione audio PulseAudio (`paplay`).
-  - **Soluzione**: Installa `pulseaudio-utils` oppure lascia che il sistema usi il fallback automatico `aplay` / `ffplay`.
+## Log

-### C. Errore API Gemini o Key Mancante (`HTTP 401` / `HTTP 403`)
- **Causa**: La chiave API Gemini non è stata inserita o è scaduta.
- **Soluzione**: Apri l'overlay grafico per configurare la chiave in modo sicuro:
-  ```
-  /agy:key
-  ```
-
-### D. Immagine generata non trovata (`IMAGE_PATH` assente)
- **Causa**: `agy` ha completato l'operazione ma non ha restituito il pattern `IMAGE_PATH` o il modello non ha generato un file su disco.
- **Soluzione**: Aumenta il timeout di generazione portando `agyTimeoutMs` a 300000 (5 minuti) o imposta `stateless: true`.
-
-### E. Errore HTTP 413 (`Payload Too Large`) durante la trascrizione audio
- **Causa**: File audio di grandi dimensioni inviato in formato WAV grezzo.
- **Soluzione**: L'estensione converte automaticamente i WAV in formato **Opus/OGG** (`libopus` a 16kbps). Assicurati che `ffmpeg` sia compilato con supporto a `libopus` o `libmp3lame`.
-
---
-
-## 3. Ispezione dei Log
-
-I log dettagliati delle interazioni della CLI `agy` sono memorizzati in:
-
-`~/.gemini/antigravity-cli/log/`
-
-Per visualizzare l'ultimo errore di sistema:
-
-```bash
-ls -t ~/.gemini/antigravity-cli/log/* | head -1 | xargs tail -n 50
-```
+I log del client Antigravity sono sotto `~/.gemini/antigravity-cli/log`.
@@ -1,123 +1,20 @@
-# Workflow Vocale (Registrazione F12)
+# Workflow vocale F12

-L'estensione `agy-pi` trasforma `pi` in un assistente multimodale completo grazie all'integrazione di un workflow di input vocale nativo attivabile con il tasto **F12** o tramite il comando `/agy:record`.
+F12 avvia/ferma una registrazione. La pipeline usa esclusivamente il gateway OAuth Antigravity, anche quando il modello attivo nella sessione pi è DeepSeek, Claude o locale.

---
-
-## Diagramma di Flusso della Registrazione Vocale
-
-```mermaid
-flowchart TD
-    A[Pressione F12] --> B{Recording in corso?}
-    B -- No --> C[startRecording: Spawn ffmpeg]
-    C --> D[Play Sound: Start PowerUp]
-    C --> E[Avvia Timer TUI Status]
-    
-    B -- Yes --> F[stopRecording: Send SIGINT]
-    F --> G[Play Sound: Stop Deactivate]
-    F --> H[optimizeAudio: silenceremove ffmpeg]
-    H --> I[audioHasSpeech: volumedetect check]
-    I -- Parlato Assente --> J[Errore: Silenzio o volume basso]
-    I -- Parlato Presente --> K[transcribeAudio: API Gemini / enne2]
-    K --> L[Legge editorText da TUI]
-    L --> M[Unisce Voce + Testo Editor + Contesto]
-    M --> N[executeAgy: plan-first, genera PIANO]
-    N --> N1{vocalPlanningMode?}
-    N1 -- true --> N2[Overlay TUI: trascrizione + piano]
-    N2 --> N3[Enter=Esegui | Esc=Annulla | E=Modifica | F12=Registra]
-    N3 -- Enter --> O[Svuota editorText TUI]
-    N3 -- Esc --> X[Annulla: playSound cancel]
-    N1 -- false --> O
-    O --> P[sendUserMessage prompt a pi]
-    P --> Q[Play Sound: Done Chime & TTS Notify]
+```text
+F12 → ffmpeg registra → rimozione silenzio/Opus → Antigravity multimodale
+    → briefing JSON → piano opzionale → prompt inviato a pi
 ```

---
+1. `ffmpeg` registra e normalizza l'audio a 16 kHz mono.
+2. `audioHasSpeech()` evita richieste su silenzio.
+3. L'audio è compresso Opus/OGG e inviato come `inlineData` a `voiceModel` tramite Antigravity.
+4. Il modello restituisce trascrizione, prompt pulito e indicazioni di ricerca.
+5. Con `vocalPlanningMode=true`, un overlay richiede conferma prima dell'invio.

-## Fasi del Workflow Vocale
+Se l'interpretazione multimodale fallisce, la pipeline tenta una trascrizione più semplice, sempre tramite Antigravity. Non esistono fallback a servizi con chiave API esterna.

-### 1. Avvio & Cattura dell'Audio (`startRecording`)
-Alla pressione del tasto **F12**:
- Viene avviato un sottoprocesso `ffmpeg` che cattura dal dispositivo PulseAudio predefinito (`-f pulse -i default`).
- L'audio viene campionato a 16.000 Hz in mono (`-ac 1 -ar 16000`).
- Viene attivato un timer TUI che aggiorna dinamicamente lo stato di `pi`:
-  `🔴 REGISTRAZIONE... 00:14 / 02:00 (Ctrl+Esc per annullare)`
+I suoni procedurali `start`, `stop`, `cancel`, `timeout` e `done` restano feedback locali; non eseguono sintesi vocale.

-### 2. Feedback Acustici Sci-Fi Procedurali (`playSound`)
-Per non dipendere da file audio esterni, i suoni di feedback vengono generati proceduralmente usando il filtro `aevalsrc` di `ffmpeg` e riprodotti tramite `paplay` (fallback su `aplay` o `ffplay`):
-
- **`start`**: Sweep di frequenza ascendente ($440 \text{ Hz} \to 1760 \text{ Hz}$).
- **`stop`**: Sweep di frequenza discendente ($1200 \text{ Hz} \to 300 \text{ Hz}$).
- **`cancel`**: Suono modulato a bassa frequenza ($350 \text{ Hz} \to 200 \text{ Hz}$).
- **`timeout`**: Pulsazione bi-tono di avviso radar.
- **`done`**: Arpeggio scintillante acuto ($C_5 - E_5 - G_5$).
-
-### 3. Ottimizzazione & Rilevamento del Parlato
-Prima della trascrizione:
- **`optimizeAudio()`**: Utilizza il filtro `silenceremove` di `ffmpeg` per eliminare il silenzio iniziale e finale con soglia a `-50dB`.
- **`audioHasSpeech()`**: Esegue una passata `volumedetect`. Se `max_volume` è inferiore a `-35dB` o `mean_volume` è sotto a `-45dB`, la registrazione viene classificata come silenzio, evitando di effettuare chiamate API inutili ed evitando allucinazioni da parte del modello STT.
-
-### 4. Compressione & Inizio Trascrizione
- L'audio ottimizzato WAV viene convertito al volo in formato **Opus/OGG** (`libopus` a 16kbps). Questo riduce il payload di oltre il 60%, evitando errori `HTTP 413 Payload Too Large`.
- Invio della richiesta alle API Gemini (`gemini-3.5-flash`) o al server `enne2`.
-
-### 5. Multimodalità Ibrida (Voce + Testo Editor)
-Una funzionalità distintiva di `agy-pi` è la capacità di fondere il testo digitato dall'utente prima di premere F12 con l'audio registrato:
-
-```typescript
-const editorText = (ctx.ui.getEditorText?.() ?? "").trim();
-```
-
-Se l'utente ha scritto una nota o del codice nell'editor di `pi` e poi preme **F12** per aggiungere un commento vocale, l'estensione unisce i due input in un unico prompt interpretativo per Gemini:
-
-$$\text{Prompt Finale} = \text{Trascrizione Vocale} + \text{Testo Editor} + \text{Contesto Conversazione}$$
-
-Dopo l'invio riuscito, l'editor dell'interfaccia TUI viene svuotato automaticamente (`setEditorText("")`) per evitare duplicazioni.
-
-### 6. Invio del Prompt all'Agente `pi`
-Se `pi` è in stato di attesa (`isIdle()`), l'input viene inviato immediatamente tramite `sendUserMessage(finalText)`. Se `pi` sta eseguendo un altro task, viene accodato come `followUp`.
-
-### 7. Workflow a 2 Fasi con Piano + Conferma (`vocalPlanningMode`)
-Con `vocalPlanningMode=true` (default) il flusso di interpretazione vocale è
-**plan-first**: Gemini produce **solo** la trascrizione corretta e un **piano
-d'azione sintetico** (nessuna esecuzione). Questo evita che l'interpretazione
-avvii autonomamente loop agentici o modifiche a sorpresa a causa di errori di STT.
-
-L'interpretazione usa un **framing inter-agent**: Gemini agisce come **analista
-tecnico/middleware** che scrive un briefing per l'orchestratore (NON risponde
-all'utente), in **JSON strutturato**:
-
-```json
-{
-  "trascrizione_corretta": "...",
-  "intent_analisi": "...",
-  "note_per_agent": "...",
-  "azioni_raccomandate": ["..."],
-  "prompt_utente_pulito": "...",
-  "ricerca_necessaria": true/false,
-  "suggerimenti_ricerca": ["..."]
-}
-```
-
-Il campo `prompt_utente_pulito` diventa il prompt finale per l'orchestratore. Se
-`ricerca_necessaria=true`, al prompt finale viene aggiunta una **nota che
-indica all'agente successivo di usare la ricerca web (Perplexity)** per
-verificare best practices, versioni o documentazione aggiornate.
-
-Poi un **overlay TUI** mostra trascrizione + piano e attende la conferma:
-
-```
-🎙️ Conferma vocale
-   Trascrizione: "Aggiorna i docs..."
-   📋 Piano proposto: ...
-   Enter esegui • Esc annulla • E modifica • Spazio testo letterale • F12 registra di nuovo
-```
-
- **Enter** → esegue (invia il risultato a pi)
- **Esc** → annulla, nessuna azione
- **E** → modifica il testo del piano manualmente
- **Spazio** → chiude l'overlay e inserisce nell'editor la **trascrizione letterale** di quanto dettato, senza inviare il piano proposto
- **F12** → registra di nuovo
-
-Per tornare all'esecuzione diretta (autonomia piena):
-`/agy:config set vocalPlanningMode false`.
+Comandi: `/agy:record`, `/agy:record:stop`, `/agy:record:cancel`. `Ctrl+Esc` annulla la registrazione.
@@ -1,39 +0,0 @@
---
-name: agy-create-verified
-description: "Operational guide for iterative image generation with visual and deterministic programmatic verification and edits."
---
-
-# Verified image workflow
-
-Use `agy_create_verified` only when a generated image must be checked and possibly corrected across iterations. Use `agy_generate` for one-shot or purely aesthetic work.
-
-## Prepare the request
-
-Separate requirements into:
-
- **Semantic:** subject, pose, style, mood, scene.
- **Layout:** aspect ratio, placement, count, alignment, spacing.
- **Measurable:** dimensions, dominant colors, geometry, contrast, text regions.
-
-Write acceptance criteria as explicit pass/fail statements. OpenCV can verify measurable criteria; Gemini judges semantic criteria. Do not claim a subjective requirement is objectively verified.
-
-## Deterministic edits
-
-Use `editInstructions` for a repeatable transformation such as resize, crop, color correction, thresholding, masking, watermark placement, or geometric cleanup. Use `editScript` only for an explicit trusted script.
-
-The edit script contract is:
-
- read input from `sys.argv[1]`;
- write only the output image to `sys.argv[2]`;
- use only `cv2`, `numpy`, `PIL`, `json`, `sys`, and `math`;
- do not use network, subprocesses, dynamic imports, or arbitrary filesystem access.
-
-The programmatic edit runs before visual/OpenCV verification, so its output—not the raw generated image—is the candidate for the next iteration.
-
-## Budget and interpretation
-
- Use `maxIterations=2` for simple corrections, 3 normally, and 4–5 only when justified.
- Keep `useOpenCV=true` when at least one criterion is measurable; otherwise it adds cost without reliable evidence.
- A `PASS` is valid only for the final candidate and available checks.
- A `FAIL` result is the latest candidate, not a compliant image. Report unmet criteria explicitly.
- Inspect the per-iteration report for edit errors, unchanged progress, regressions, and failed OpenCV output before presenting the result as verified.
@@ -1,37 +0,0 @@
-# Istruzioni globali per pi agent
-
-## Feedback vocale a ogni step (TTS)
-
-Dopo **ogni step** del flusso agentico (ogni tool eseguito, ogni fase completata, ogni errore incontrato), produci un **mini-riassunto vocale** e riproducilo subito con il tool `agy_tts`.
-
-### Formato del riassunto di step
-
-Il riassunto deve essere **breve (1-2 frasi)** e indicare:
-
-1. **Cosa stai facendo** — l'azione corrente o appena completata
-2. **Obiettivi raggiunti** — cosa è stato completato con successo
-3. **Problemi incontrati** — eventuali blocchi, errori o ostacoli
-
-### Come riprodurlo
-
-Usa il tool `agy_tts` con il testo del riassunto:
-
-```
-agy_tts(text="Step completato: ho analizzato il file e trovato l'errore. Obiettivo raggiunto. Nessun problema.")
-```
-
-### Regole
-
- **Sempre**: riassunto vocale dopo ogni step significativo (non per micro-azioni banali come letture singole)
- **Breve**: massimo 2 frasi, tono naturale e conciso
- **Errori**: se uno step fallisce, annuncia il problema e cosa intendi fare
- **Non ripetere**: se il riassunto è identico al precedente, omettilo
- **Rispetta la config**: se `ttsNotify` è `false` nella config di agy-pi, salta il feedback vocale
- **Toggle rapido**: l'utente può attivare/disattivare il feedback vocale con `/agy:vocal` (on|off|status)
- **Non interrompere**: il feedback vocale non deve bloccare il flusso di lavoro (fire-and-forget)
-
-### Esempi
-
- ✅ "Analisi completata: trovati 3 errori nel file main.ts. Procedo con la correzione."
- ✅ "Correzione applicata con successo. Obiettivo raggiunto."
- ⚠️ "Attenzione: la build è fallita per un errore di sintassi. Riprovo dopo la correzione."