1. Cos'è approval_ux

approval_ux è lo schema visuale e di flusso con cui Metnos chiede a Roberto (e a chi è pairato come Supervised) di confermare un'azione critica prima di eseguirla. Vive nel canale di pairing — oggi Telegram, domani Signal e voce — e si attiva quando la policy calcola un effective_outcome uguale a approval_required.

Il pattern di base è quello del dialog manager: una carta a 3 righe, due bottoni inline (Approva / Rifiuta), un token opaco che identifica univocamente la richiesta. La carta viene modulata in funzione di quante volte la stessa richiesta è già stata posta — al decimo "vuoi che scarichi?" Roberto sa già cosa sta approvando e una riga compatta basta. Una concessione di territorio (per una sessione, in modo permanente) è segnalata con un marker testuale.

Sul retro della carta vive un'infrastruttura di tre componenti:

• il renderer (runtime/channels/approval.py) che produce l'OutboundMessage con testo e bottoni;
• il registry SQLite (runtime/approval_registry.py) che traccia ogni pending request con TTL e stato;
• il dispatcher (runtime/channels/daemon.py + runtime/channels/telegram.py) che riceve i click sui bottoni e risolve il token.

2. La carta a 3 righe

Il pattern dal dialog manager prescrive tre righe canoniche, ognuna con una funzione precisa. La funzione render_approval_card (runtime/channels/approval.py:60-87) le compone a partire dai campi della ApprovalRequest:

Sotto le tre righe, due bottoni inline:

buttons = [[
 {"text": "Approva", "data": f"approve:{req.token}"},
 {"text": "Rifiuta", "data": f"reject:{req.token}"},
]]

Il token è il riferimento opaco emesso dal approval_registry al momento della creazione della pending request (vedi cap. 6); il data dei bottoni è l'unica informazione che tornerà indietro quando l'utente clicca, dunque il token deve essere sufficiente a identificare la richiesta.

La firma del rendering è minima:

def render_approval_card(req: ApprovalRequest) -> OutboundMessage:
 """Produce un OutboundMessage con la carta a 3 righe + due bottoni."""

Niente parametri di stile, niente i18n: tutto quello che varia è nei campi di ApprovalRequest (runtime/channels/approval.py:60-62).

3. La dataclass ApprovalRequest

Il contratto fra chi solleva la richiesta (Vaglio, Policy, futuro pianificatore integrato) e il renderer è una dataclass frozen di otto campi. Citazione: runtime/channels/approval.py:27-38.

La dataclass è frozen=True: una volta costruita, una ApprovalRequest non può essere modificata. Questo rende sicuro passarla fra moduli senza paura di mutazioni laterali, e si presta bene al hashing per deduplica futura.

4. Modulazione per ricorrenza

La stessa richiesta posta dieci volte di fila non merita la stessa cura della prima. Il modulo prevede tre forme della carta, scelte in base al campo recurrence_count:

La selezione è fatta da _shape_for_recurrence (runtime/channels/approval.py:52-57):

def _shape_for_recurrence(n: int) -> Literal["full", "medium", "short"]:
 if n >= _RECURRENCE_THRESHOLDS[1]:
 return "short"
 if n >= _RECURRENCE_THRESHOLDS[0]:
 return "medium"
 return "full"

Le soglie sono in una costante a livello di modulo, dichiarata vicino al renderer:

_RECURRENCE_THRESHOLDS = (3, 8) # < 3: full | 3..7: medium | ≥ 8: short

Citazione: runtime/channels/approval.py:48-49. Cambiare le soglie è una modifica locale di una riga; la struttura del rendering non si tocca.

La forma medium e la forma short sono pensate per casi in cui Roberto sa cosa sta approvando: un agente che esegue una macro ricorrente, una sessione lunga in cui la stessa azione si ripete ogni minuto. La forma full resta il default per la prima volta e per le seconde volte: la cura di mostrare i dettagli è più importante della velocità di lettura.

5. Marker territorio

Una concessione di territorio è quando, approvando, Roberto non solo dice "sí a questa azione" ma anche "sí a questa classe di azioni nel futuro". Tre livelli, tre marker testuali:

Il marker viene appeso in coda alla classificazione meta. Citazione: runtime/channels/approval.py:42-46:

_TERRITORY_MARKER = {
 "none": "",
 "session": " [territorio: sessione]",
 "permanent": " [territorio: permanente]",
}

È un dizionario, non una funzione: la mappatura è statica e non dipende da altro. ASCII robusto su tutti i client (niente glifi che variano da font a font). La parentesi quadra apre un blocco visivamente distinto dal resto della meta-riga, che usa la barra verticale come separatore. La concessione si vede a colpo d'occhio anche in una notifica push troncata.

6. Approval registry SQLite

Quando la policy decide che un'azione richiede approvazione, qualcuno deve tener traccia della pending request finché l'utente non risponde (o il TTL scade). Quel qualcuno è runtime/approval_registry.py: un modulo a sola SQLite, niente daemon, niente classi (a parte la dataclass del record).

6.1 Schema

Una sola tabella pending, primary key il token. Citazione: runtime/approval_registry.py:34-52:

CREATE TABLE IF NOT EXISTS pending (
 token TEXT PRIMARY KEY,
 channel TEXT NOT NULL,
 sender_id TEXT NOT NULL,
 capability_class TEXT NOT NULL,
 action_verb TEXT NOT NULL,
 target_summary TEXT NOT NULL,
 created_at TEXT NOT NULL,
 expires_at TEXT NOT NULL,
 status TEXT NOT NULL DEFAULT 'pending',
 decision_at TEXT,
 decision_by_channel TEXT,
 decision_by_sender TEXT,
 request_extra TEXT
);
CREATE INDEX IF NOT EXISTS idx_pending_status ON pending(status);
CREATE INDEX IF NOT EXISTS idx_pending_expires ON pending(expires_at);

Quattro stati riconosciuti per la colonna status: pending, approved, rejected, expired. Le date sono ISO-8601 in UTC (%Y-%m-%dT%H:%M:%SZ), comode da confrontare lessicograficamente.

6.2 API

Cinque funzioni pubbliche. Tutte aprono e chiudono la connessione SQLite a ogni chiamata: niente connection pool, niente stato globale.

6.3 Database e TTL

Il path del DB è risolto in ordine: argomento esplicito db_path > variabile d'ambiente METNOS_APPROVALS_DB > default ~/.local/state/metnos/approvals.db. La directory viene creata se manca. Citazione: runtime/approval_registry.py:86-92.

Il TTL di default è 600 secondi (10 minuti). È il tempo entro cui Roberto deve rispondere prima che la richiesta venga marcata expired; un sistema di reminder o di re-issue rimane responsabilità del chiamante. Citazione: runtime/approval_registry.py:30.

6.4 La regola di sicurezza

Il punto di tensione è resolve. Quattro verifiche, in ordine, e un dettaglio importante sulla persistenza. Citazione: runtime/approval_registry.py:177-205:

1. Token noto. Se il token non esiste, ApprovalError("token sconosciuto").
2. Status pending. Se è già risolto (approved/rejected/expired), ApprovalError("token già risolto"): niente double-spending della decisione.
3. Non scaduto. Se expires_at < now, viene scritto uno UPDATE che marca status='expired' e poi sollevato ApprovalError. La connessione è aperta in autocommit (isolation_level=None) proprio perché la transizione a expired deve sopravvivere all'eccezione.
4. Decisore = richiedente. Se row["channel"] != by_channel o row["sender_id"] != by_sender, ApprovalError("decisore non autorizzato"): chi ha richiesto è chi può approvare. È l'asse identità descritto al cap. 5 dell'Architettura.

Solo dopo i quattro check, lo UPDATE finale scrive la decisione e ritorna la PendingRequest aggiornata.

7. Dispatcher callback Telegram

Resta da spiegare come un click sul bottone "Approva" su Telegram diventi una chiamata a approval_registry.resolve. La catena attraversa tre componenti: il channel out (che ha disegnato i bottoni), il channel in (che riceve il callback), il dispatcher del daemon.

7.1 Bottoni in uscita

OutboundMessage.buttons è list[list[dict]]; ogni dict ha le chiavi text (etichetta visibile) e data (callback_data che tornerà al server). render_approval_card usa una sola riga di due bottoni:

buttons = [[
 {"text": "Approva", "data": f"approve:{req.token}"},
 {"text": "Rifiuta", "data": f"reject:{req.token}"},
]]

TelegramChannel.send traduce questa struttura in reply_markup.inline_keyboard nel formato Telegram (runtime/channels/telegram.py:108-114). I bottoni vengono cosí mostrati attaccati al messaggio della carta.

7.2 Callback_query in arrivo

Quando l'utente clicca, Telegram non invia un nuovo messaggio: invia un oggetto callback_query nel prossimo getUpdates. TelegramChannel.poll lo riconosce esplicitamente. Citazione: runtime/channels/telegram.py:135-156:

cbq = u.get("callback_query")
if cbq:
 msg_ctx = cbq.get("message") or {}
 out.append(InboundMessage(
 channel=self.name,
 sender_id=str(cbq.get("from", {}).get("id")
 or msg_ctx.get("chat", {}).get("id", "")),
 text=cbq.get("data", ""),
 message_id=str(msg_ctx.get("message_id", "")),
 received_at=float(msg_ctx.get("date", time.time)),
 extra={"kind": "callback", "callback_id": cbq.get("id"),
 "from": cbq.get("from", {}), "update_id": uid},
 ))
 cb_id = cbq.get("id")
 if cb_id:
 self._call("answerCallbackQuery", {"callback_query_id": cb_id})
 continue

Tre dettagli da notare. (a) Il text dell'InboundMessage non è un testo umano: è il callback_data grezzo (approve:<tok> o reject:<tok>). (b) Il sender_id è preso da cbq.from.id (chi ha cliccato), con fallback alla chat originale: serve a verificare che chi clicca sia chi ha generato la richiesta. (c) Il marker extra={"kind": "callback"} distingue il messaggio dai testi normali quando il dispatcher decide come trattarlo. La chiamata finale a answerCallbackQuery è richiesta da Telegram per togliere la rotella di caricamento sul bottone cliccato; non manda contenuto, solo un acknowledgement.

7.3 Dispatch nel daemon

ChannelDaemon.handle_message guarda extra.kind prima di tutto: se è callback, instrada al dispatcher dedicato. Citazione: runtime/channels/daemon.py:122-154 e runtime/channels/daemon.py:156-162:

def _handle_callback(self, msg: InboundMessage) -> dict:
 """Risolve un callback_query 'approve:<token>' o 'reject:<token>'."""
 data = (msg.text or "").strip
 if data.startswith("approve:"):
 decision = "approved"
 token = data[len("approve:"):]
 user_label = "Approvato"
 elif data.startswith("reject:"):
 decision = "rejected"
 token = data[len("reject:"):]
 user_label = "Rifiutato"
 else:
 log.warning("callback_data non riconosciuto: %r", data)
 return {"ok": False, "reason": "unknown_callback", "data": data}
 if not token:
 return {"ok": False, "reason": "missing_token"}
 try:
 rec = approval_registry.resolve(
 token, decision,
 by_channel=self.channel.name, by_sender=msg.sender_id,
 )
 except approval_registry.ApprovalError as e:
 self._send_text(msg.sender_id,
 f"Approval non risolvibile: {e}",
 reply_to=msg.message_id)
 return {"ok": False, "reason": "approval_failed", "error": str(e)}
 log.info("approval risolto: token=%s decision=%s sender=%s",
 token, decision, msg.sender_id)
 self._send_text(msg.sender_id,
 f"{user_label}: {rec.action_verb} {rec.target_summary}",
 reply_to=msg.message_id)
 return {"ok": True, "decision": decision, "token": token,
 "capability_class": rec.capability_class}

La logica è lineare: parsing del prefisso approve: / reject:, estrazione del token, chiamata a resolve, conferma testuale all'utente. Eventuali ApprovalError (token già risolto, scaduto, decisore non autorizzato) si traducono in un messaggio di errore al sender.

7.4 L'asse identità in pratica

L'Architettura cap. 5 distingue tre assi della sicurezza: libertà/safety, identità/safety, perimetro/robustezza. Il flusso di approval mette in opera l'asse identità: ogni richiesta è etichettata col canale e il sender che l'hanno generata, e ogni risoluzione verifica l'identità del decisore prima di consumare il token. Un attaccante che riuscisse a sniffare un token e a usarlo da un altro chat ID non riuscirebbe a risolverlo: ApprovalError("decisore non autorizzato").

8. Test

Tre raggruppamenti, tutti verdi alla data. I numeri puntano ai cluster del framework di test del runtime.

8.1 Cluster approval_registry (6/6)

8.2 Cluster channels — callback dispatcher (5/5)

8.3 Module case — rendering carta (3)

9. Esempi end-to-end

Tre esempi della stessa richiesta a tre stadi di ricorrenza. I bottoni sono renderizzati come pseudo-elementi sotto la carta.

In tutti i casi i due bottoni hanno callback_data della forma approve:<tok> e reject:<tok>; il token è lo stesso che il approval_registry ha emesso quando la richiesta è stata creata. Quando l'utente clicca, il flusso descritto al cap. 7 si avvia: il callback_query arriva al daemon, _handle_callback chiama resolve, l'utente riceve la conferma testuale "Approvato: scarichi rapporto.pdf da drive.google.com -> ~/downloads/ (~2.4 MB)".

10. Limiti e cosa è rimandato a +

Note finali

approval_ux è un componente piccolo per linee di codice (renderer ~90 righe, registry ~280, dispatcher ~30 nel daemon) ma denso per significato: è il momento in cui Metnos si ferma e chiede. La cura della carta a 3 righe — verbo coniugato, oggetto leggibile, classificazione meta — non è estetica: è il modo in cui si rende possibile la decisione informata dell'utente in due secondi.

La regola del decisore = richiedente, scritta dentro resolve, è il punto fermo che permette al dispatcher dei callback di precedere il check di pairing senza creare buchi. Non si fida del dispatcher; si fida solo del registry. La sicurezza è concentrata nel posto giusto.