# AOVerview

Dashboard locale del lavoro degli agent, alimentata tramite MCP. Mostra obiettivi, attività a blocchi, risultati, problemi, prossimi passi provvisori e contributi dei subagent, senza ricostruire la conversazione con ulteriori chiamate al modello.

Ogni agent principale avvia una sessione indipendente. La dashboard mostra più sessioni insieme e permette di esplorare i subagent di ciascuna. Lo stato è dichiarato dagli agent: il silenzio non viene interpretato come completamento o fallimento.

## Avvio

Richiede **Node.js 24+** e npm.

```bash
npm ci
npm run dev
```

Apri **http://localhost:3000**. Il comando compila il core, esegue le migrazioni e avvia i tre servizi con aggiornamento automatico del codice. Alla chiusura termina anche i processi figli.

| Servizio | Indirizzo predefinito |
| --- | --- |
| Dashboard React | `http://localhost:3000` |
| MCP HTTP | `http://localhost:3001/mcp` |
| API dashboard | `http://localhost:3002/api/v1` |
| Disponibilità API | `http://localhost:3002/health` |

Il precedente `hello-world` è sostituito dai quattro tool di reporting. L'endpoint MCP passa dalla porta 3000 alla **3001**.

Per la versione compilata:

```bash
npm run build
npm start
```

La dashboard compilata viene servita dal proprio processo Node, con lo stesso inoltro `/api` usato da Vite in sviluppo.

La UI usa **shadcn/ui New York**, Radix, Tailwind CSS 4 e Lucide, con tema scuro e sidebar inset. I componenti sono in `apps/dashboard/src/components/ui`; la configurazione per aggiungerne altri è in `apps/dashboard/components.json`.

Le attività sono visualizzate su un canvas React Flow a schermo intero, accanto alla sidebar. Le frecce sono tratteggiate e si animano sui collegamenti verso lavoro in corso; proposte, attività bloccate e contributi conclusi restano fermi. I subagent si diramano dal blocco che li ha delegati; una freccia verde indica l’integrazione registrata. I punti di collegamento compaiono solo sui rami dei subagent. Le card mostrano titolo, icona di stato e tempo dalla creazione. Al clic si apre un pannello minimale con esito, passaggi azione/esito/riferimento e contributi delegati; Esc lo chiude.

La todo list fluttua sul canvas e può essere nascosta; su mobile si apre dal pulsante Obiettivi. Gli aggiornamenti live conservano il punto di vista scelto. I controlli in basso a destra permettono di centrare l’attività recente, mostrare tutti i blocchi caricati e regolare lo zoom. Trascina lo sfondo o scorri con il trackpad per spostarti; usa i pulsanti, il gesto pinch o Cmd/Ctrl con la rotella per lo zoom. Le animazioni rispettano la preferenza di movimento ridotto.

La home mostra agent al lavoro, obiettivi aperti e attività bloccate nelle sessioni caricate. Gli agent con sole attività bloccate non sono conteggiati come al lavoro; gli obiettivi annullati non sono aperti. Le card delle sessioni mostrano attività corrente o problema da risolvere, agent, subagent, avanzamento e ultimo aggiornamento, con un solo clic per aprire la canvas.

Il comando **Archivia**, disponibile sulle card, nella sidebar e nel dettaglio, nasconde una sessione dall’elenco e dai conteggi della dashboard. L’archiviazione è persistente e conserva obiettivi, attività e aggiornamenti degli agent. **Annulla** ripristina l’ultima sessione archiviata; anche un collegamento diretto alla sessione permette di ripristinarla. Le altre finestre aperte si aggiornano in diretta.

## Collegare un agent

Nei client MCP con configurazione HTTP tramite `url`:

```json
{
  "mcpServers": {
    "aoverview": { "url": "http://localhost:3001/mcp" }
  }
}
```

Fornisci all'agent la [skill AOVerview](skills/aoverview/SKILL.md). Il file è distribuibile e non viene installato automaticamente nel catalogo globale. Puoi farlo leggere all'agent o installarlo nel sistema di skill che usi; per il catalogo centrale usa SkillGesture.

| Tool | Utilizzo |
| --- | --- |
| `overview_open` | Apre una sessione con titolo, nome dell'agent e pochi obiettivi. Il `requestId` di apertura deve essere globalmente unico. |
| `overview_update` | Comunica solo le modifiche significative, raggruppando operazioni correlate. |
| `overview_register_subagent` | Riserva l'identità di un figlio prima dello spawn. |
| `overview_resume` | Recupera contesto compatto e revisione dopo perdita del contesto o conflitti. |

Conserva handle e revisione restituiti anche nei riepiloghi di compattazione/ripresa. Le risposte di scrittura non ripetono i testi inviati; il risultato è in `structuredContent`. Gli errori sono risposte MCP `isError` con codice e indicazione breve.

La ripresa restituisce gli ultimi tre dettagli del blocco attivo, fino a cinque blocchi bloccati/proposti e venti figli, dando priorità alle deleghe ancora aperte. La dashboard e l'API conservano la cronologia completa.

Esempio di apertura:

```json
{
  "requestId": "my-native-session-unique-id",
  "title": "Implementare la dashboard",
  "agentName": "Codex",
  "detailLevel": "medium",
  "goals": [{ "id": "g1", "title": "Visualizzare progressi e risultati" }]
}
```

Esempio di aggiornamento dopo l'apertura con revisione 0:

```json
{
  "handle": "HANDLE_RESTITUITO_DAL_SERVER",
  "requestId": "start-1",
  "expectedRevision": 0,
  "operations": [
    { "op": "goal", "id": "g1", "status": "active" },
    {
      "op": "block", "id": "b1", "title": "Definire il modello dei dati",
      "status": "active", "goalId": "g1",
      "details": [{ "id": "d1", "action": "Chiarite le informazioni da mostrare", "result": "Separati obiettivi, attività e proposte", "reference": "packages/core/src/contracts.ts" }]
    },
    { "op": "block", "id": "b2", "title": "Implementare la persistenza", "status": "proposed" }
  ]
}
```

## Regole del reporting

- La to-do list contiene pochi obiettivi ampi: più blocchi possono contribuire allo stesso obiettivo. I blocchi descrivono attività circoscritte; i passaggi interni contengono azione, esito e un riferimento verificabile, quando disponibile. Un blocco concluso non completa automaticamente il suo obiettivo.
- `overview_open.detailLevel` è opzionale: `low` raggruppa lavori correlati, `medium` separa attività con un risultato proprio, `high` distingue anche sottoattività e verifiche significative. Predefinito: `medium`. Non impone un numero di blocchi né cambia gli obiettivi; la skill guida l'agent e i subagent ereditano il livello. Il livello è salvato nella sessione, restituito alla ripresa ed esposto dall'API.
- Puoi indicarlo nel prompt, per esempio: «Usa AOVerview con dettaglio basso/medio/alto». È una scelta all'apertura della run; non riclassifica i blocchi delle sessioni precedenti. Per una prova: «Usa AOVerview con dettaglio medio. Mantieni gli obiettivi macro; descrivi il lavoro in blocchi e i passaggi come azione, esito e riferimento, seguendo la skill».
- Nei dettagli, `reference` è testo breve (massimo 600 caratteri): percorso, comando di verifica o altro riferimento realmente osservato. Si aggiorna per ID; ometterlo conserva il valore e `null` lo cancella. Non inviare output grezzi e non inventare evidenze mancanti.
- Un solo blocco `active` per agent; altri possono restare `blocked`. I nuovi blocchi sono `proposed` o `active`.
- Le proposte sono modificabili; l'attivazione conferma l'avvio. Non possono contenere passaggi già svolti.
- Il lavoro attivo può diventare `blocked`, `completed`, `failed` o `cancelled`. Quello bloccato può riprendere; gli stati terminali non riaprono.
- Campi omessi conservano il valore; `null` cancella un valore opzionale. I dettagli sono aggiunti/corretti per ID, senza sostituire la lista completa.
- Le chiavi brevi dei blocchi appartengono all'agent e quelle dei dettagli al blocco: due agent possono usare `b1` senza sovrascriversi. Solo il principale gestisce gli obiettivi della sessione.
- Ogni nuova richiesta ha un nuovo `requestId`. Un retry identico riusa tutti gli argomenti originali. Il riuso con contenuto diverso è rifiutato.
- Ogni batch è atomico, compresa la notifica alla dashboard. Le revisioni sono per agent: i figli non invalidano quelle dei genitori.
- Per `REVISION_CONFLICT`, riprendi il contesto prima di preparare un aggiornamento corretto.

Prima dello spawn, registra il subagent dal blocco attivo del genitore. Passa al figlio handle, identità e skill nel messaggio di avvio. Il primo aggiornamento del figlio conferma l'esecuzione. Se lo spawn fallisce, annulla la riserva con un'operazione `delegation`.

Quando utilizzi realmente un contributo concluso, registra `delegation` con `status: "integrated"` e il tuo `blockId`. Completamento e integrazione restano distinti. Lo stesso flusso supporta deleghe annidate.

Per concludere con successo, chiudi i blocchi attivi/bloccati, attendi i discendenti e completa o annulla gli obiettivi. L'operazione `finish` registra l'esito e annulla le proposte rimaste. Un fallimento del genitore non viene propagato automaticamente ai figli.

## API e aggiornamenti live

L’API espone le viste e i comandi di archiviazione della dashboard; non espone handle di scrittura o ricevute interne. Il reporting degli agent resta gestito tramite MCP.

| Endpoint | Dati |
| --- | --- |
| `GET /api/v1/sessions` | Sessioni non archiviate e attività correnti |
| `GET /api/v1/sessions/:id` | Obiettivi e gerarchia degli agent |
| `POST /api/v1/sessions/:id/archive` | Archivia una sessione senza eliminarne i dati |
| `DELETE /api/v1/sessions/:id/archive` | Ripristina una sessione archiviata |
| `GET /api/v1/agents/:agentId/blocks` | Blocchi senza dettagli completi |
| `GET /api/v1/agents/:agentId/blocks/:blockId` | Blocco e passaggi svolti |
| `GET /api/v1/events` | Notifiche SSE |

Le liste accettano `limit` (1–100, predefinito 30) e il `cursor` restituito dalla pagina precedente. Per i blocchi, `view=history` mostra il lavoro avviato dalla fase più recente; `view=proposed` mostra le proposte. Senza filtro sono restituiti tutti i blocchi in ordine di avvio/creazione, incluse le proposte annullate.

L'API effettua un solo polling del registro persistente ogni 500 ms, indipendentemente dal numero di browser. Le notifiche SSE contengono sequenza, sessione e agent; la dashboard recupera le viste interessate. Le riconnessioni recuperano uno snapshot aggiornato; `Last-Event-ID` permette replay limitato o reset per backlog lunghi.

```bash
curl http://localhost:3002/api/v1/sessions
```

## Configurazione e servizi indipendenti

Copia `.env.example` in `.env` per cambiare porte e archivio. I percorsi relativi del database vengono risolti dalla root del monorepo anche avviando un singolo workspace.

```dotenv
AOVERVIEW_DB_PATH=./data/aoverview.sqlite
AOVERVIEW_MCP_PORT=3001
AOVERVIEW_API_PORT=3002
AOVERVIEW_DASHBOARD_PORT=3000
```

Prima di avviare i singoli servizi:

```bash
npm run db:migrate
npm run dev -w @aoverview/mcp
npm run dev -w @aoverview/api
npm run dev -w @aoverview/dashboard
```

Esegui gli ultimi tre comandi in terminali distinti. Per i servizi compilati usa `start`, dopo `npm run build`.

SQLite usa WAL, foreign key e timeout dei lock. MCP scrive il reporting; l’API può modificare solo lo stato di archiviazione tramite i suoi endpoint. Le migrazioni sono versionate e idempotenti. La migrazione alla versione 2 mantiene sessioni e ricevute esistenti, assegna `medium` alle sessioni precedenti e lascia i riferimenti non riportati a `null`. La versione 3 aggiunge `archivedAt`, inizialmente `null`, senza cambiare la cronologia o le revisioni degli agent.

## Verifica

```bash
npm run typecheck
npm test
npm run build
```

I test usano database temporanei e coprono atomicità, isolamento, retry, stati, deleghe annidate, ripresa, paginazione, concorrenza multiprocesso, API/SSE, client MCP reali e avvio/spegnimento del launcher.

La prima versione è personale e locale, senza login o accesso remoto. Non registra conversazioni o log grezzi: invia contenuti adatti alla dashboard. Le UI MCP Apps potranno riutilizzare in seguito modello e API.

## Licenza

AOVerview è distribuito con [licenza MIT](LICENSE). Le attribuzioni e la licenza dei componenti shadcn/ui sono riportate in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).