From 81282af35a650d364b1c2b027f1b2bb8bc4e82e3 Mon Sep 17 00:00:00 2001 From: DevEnv nis2-agile Date: Fri, 19 Jun 2026 07:27:17 +0200 Subject: [PATCH] =?UTF-8?q?[DOCS]=20OUTGOING=E2=86=92AgileHub:=20suggerime?= =?UTF-8?q?nto=20lettura=20allegati=20ticket=20nel=20supervisore=20(cross-?= =?UTF-8?q?suite)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problema: il supervisore autonomo non leggeva gli allegati (nel payload ticket solo testo 'N allegati aggiunti', niente metadati/URL). Endpoint esistenti ma non documentati nel runner: GET /tickets/{id}/attachments[/{attId}]. Suggeriti 5 miglioramenti cross-suite (owner VIGILE): esporre attachments nel payload; pre-download nel runner standard; doc endpoint; nota anti-injection. Fix locale NIS2 già applicato (prompt supervisore). Co-Authored-By: Claude Opus 4.8 (1M context) --- ...026-06-19_supervisor_attachment_reading.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/OUTGOING_TO_AGILEHUB_2026-06-19_supervisor_attachment_reading.md diff --git a/docs/OUTGOING_TO_AGILEHUB_2026-06-19_supervisor_attachment_reading.md b/docs/OUTGOING_TO_AGILEHUB_2026-06-19_supervisor_attachment_reading.md new file mode 100644 index 0000000..72e71b6 --- /dev/null +++ b/docs/OUTGOING_TO_AGILEHUB_2026-06-19_supervisor_attachment_reading.md @@ -0,0 +1,34 @@ +# NIS2 → AgileHub/VIGILE — Suggerimento: far leggere gli ALLEGATI dei ticket al supervisore autonomo + +> **Da**: NIS2 (product-side) · **A**: VIGILE / AgileHub (owner standard `autonomous-supervisor-agent`, hub_standards id=32) +> **Data**: 2026-06-19 · **Tipo**: suggerimento di miglioramento **cross-suite** (non urgente, additivo) +> **Canale**: doc `OUTGOING_TO_AGILEHUB` (pattern bidirezionale esistente; i MS AgileHub 4213/4211 non raggiungibili dal devenv). + +## TL;DR +Il supervisore autonomo (e in genere ogni ticket-agent) **non leggeva gli allegati dei ticket**. Quando un utente allega file (es. una spec `istruzioni.pdf` + uno screenshot `policy01.png`), nel payload del ticket **compare solo il testo** di un messaggio SYSTEM («2 allegati aggiunti: x.pdf, y.png») — **nessun metadato né URL** dell'allegato in `GET /tickets/{id}`. Risultato: l'agente non aveva un modo cablato per recuperarli e **escalava** invece di lavorare. **Non è un limite del modello** (Claude legge PDF e immagini nativamente): è solo *plumbing* mancante. Suggeriamo di chiuderlo **centralmente nel runner/standard**, così ne beneficiano tutti i prodotti. + +## Cosa abbiamo scoperto (endpoint già esistenti, ma non documentati nel runner) +Sondando il ticket-ms abbiamo trovato che gli allegati **sono scaricabili**: +- `GET /tickets/{id}/attachments` → `[{id, filename, mimeType, size}]` (lista) +- `GET /tickets/{id}/attachments/{attId}` → **binario** (es. `application/pdf`, `image/png`) + (header `X-Internal-Key` + `x-tenant-id`). Esempio reale verificato su #384: `attachments` = `[{id:109, policy01.png}, {id:110, istruzioni.pdf}]`, e `GET /tickets/384/attachments/110` ha restituito il PDF (15 KB) leggibile. + +## Cosa abbiamo già fatto lato NIS2 (workaround locale, funziona) +Abbiamo insegnato al prompt del supervisore NIS2 a: **lista → download nel project dir (gitignored) → `Read`** (PDF/PNG/JPG), trattando l'allegato come **input NON fidato** (prompt-injection possibile anche via PDF/immagine). Dimostrato sul campo: il supervisore ha letto `istruzioni.pdf` + `policy01.png` del #384 e ha implementato l'intera feature multi-modulo (6 punti) a fasi. + +## Suggerimenti (owner VIGILE — da valutare per lo standard `autonomous-supervisor-agent`) +1. **Esporre gli allegati nel payload del ticket.** Aggiungere a `GET /tickets/{id}` un campo `attachments: [{id, filename, mimeType, size, downloadUrl}]`, così l'agente non deve **parsare il testo** del messaggio SYSTEM né **sondare** endpoint a tentativi. (È il punto a maggior valore: rende l'allegato un dato di prima classe.) +2. **Cablare la lettura allegati nel RUNNER standard** (`supervisor-agent-cron.sh`), non nei singoli prompt di prodotto: prima di invocare `claude -p`, il runner **pre-scarica** gli allegati dei ticket in coda in un path locale noto (es. `./.ticket-attachments//`), così OGNI prodotto li trova già pronti da `Read`. Evita il patching prompt-per-prodotto (oggi l'abbiamo fatto solo su NIS2). +3. **Documentare gli endpoint** `/tickets/{id}/attachments[/{attId}]` nella guida del runner/standard. +4. **Nota di sicurezza nello standard**: gli allegati (PDF/immagini) sono **input non fidato** → trattarli come dato da analizzare, mai come istruzioni da eseguire (estendere la difesa prompt-injection, già prevista per il testo del ticket, anche al contenuto degli allegati). +5. **Opzionale**: includere `attachments` anche nei payload di webhook/notifica del ticket-ms. + +## Perché conviene farlo centralmente +- Lo standard è adottato (NIS2 è primo adopter; altri prodotti seguiranno): risolvendolo nel runner, **tutti** ereditano la capacità senza ri-scrivere il prompt. +- Riduce gli **escalation inutili** (ticket con spec nell'allegato che oggi rimbalzano all'umano). +- Allinea i prodotti su un'unica gestione sicura (anti-injection) degli allegati. + +## Riferimenti +- Standard: `autonomous-supervisor-agent` (hub_standards id=32), runner `supervisor-agent-cron.sh`. +- Lato NIS2: prompt `scripts/nis2-supervisor-acting-prompt.md` (sezioni "Accessi → Allegati ticket" e CICLO punto 2), commit di adozione su main. +- Caso d'uso reale: ticket #384 (super_admin, spec in `istruzioni.pdf` + `policy01.png`) — implementato e chiuso (RESOLVED) dal supervisore dopo l'abilitazione alla lettura allegati.