1. Cos'è un executor (in trenta secondi)

Un executor è una piccola utilità specializzata che fa una cosa sola: legge la posta, cerca un file, scatta una foto dell'orologio, manda un messaggio. Vive da solo, in una sua cartella, e parla con Metnos attraverso un contratto preciso.

Pensa a una cassetta degli attrezzi. Ogni attrezzo è semplice e riconoscibile: il cacciavite stringe le viti, il martello batte i chiodi. Nessuno chiederebbe al cacciavite di battere un chiodo. In Metnos è lo stesso: ogni executor è un attrezzo con un compito chiaro. Quando l'utente chiede qualcosa, il pianificatore sceglie l'attrezzo giusto e lo usa.

Le tre cose che lo definiscono sono:

• fa una cosa sola — tutta la sua vita gira intorno a un compito ristretto;
• ha un contratto — dichiara cosa accetta in entrata e cosa restituisce;
• vive in un recinto — può toccare solo certe cartelle, certi indirizzi di rete, certi servizi.

2. Anatomia: cinque cose nella cartella

Un executor è una cartella sul disco. Dentro ci sono al massimo cinque file, ognuno con un mestiere. Niente di più.

I tre file obbligatori sono il cuore. Il codice fa il lavoro. Il manifesto descrive il codice in modo che il pianificatore possa decidere se usarlo. La firma dimostra che il manifesto non è stato manomesso da quando l'autore l'ha scritto.

3. Il manifesto: il biglietto da visita

Il manifesto è un file in formato TOML. Lo apri con un editor di testo e ci capisci qualcosa anche senza essere un programmatore. Dichiara tutto quello che il pianificatore deve sapere: come si chiama l'executor, cosa fa, che argomenti accetta, come è fatto il risultato, qualche esempio per orientarsi.

Cosa c'è di importante

Tre cose meritano un secondo sguardo, perché sono quelle su cui si regge l'intero sistema.

L'impronta del codice (digest): è un'impronta crittografica calcolata sui byte del file .py. Se qualcuno modifica anche solo una virgola nel codice senza ricalcolare l'impronta, il loader rifiuta l'executor. Il manifesto e il codice sono legati come un certificato e il documento che certifica.

La forma del risultato (output.schema_inline): dichiara campo per campo cosa restituisce l'executor. Serve a chi compone catene di executor (il pianificatore non vola alla cieca: legge lo schema e sa cosa aspettarsi al passo successivo) e a chi genera codice in automatico.

I permessi (capabilities): non è il manifesto a stabilire cosa l'executor può fare. Il manifesto dichiara di cosa avrebbe bisogno per funzionare; poi il sistema decide se concedere quei permessi e con che vincoli. Vedi sandbox.

4. Il recinto: cosa può fare e cosa no

Un executor non gira a piede libero sul sistema. Vive dentro un recinto, costruito proprio sui permessi che il suo manifesto dichiara. Il recinto stabilisce: cosa può leggere sul disco, cosa può scrivere, con quali macchine può parlare in rete, quali file di sistema sono comunque off limits anche se l'executor li chiedesse.

La regola d'oro è semplice: il recinto è sempre più stretto del manifesto. Se un manifesto chiede di leggere /home, il recinto può comunque tagliare la richiesta a /home/user/notes. Se chiede di parlare con qualunque dominio, il recinto può limitare a imap.example.com. La differenza è importante: il manifesto è quello che l'autore sperava, il recinto è quello che il sistema ha deciso dopo aver visto chi lo invoca, in che contesto, con che livello di fiducia.

5. La vita di un executor

Un executor non nasce attivo e non rimane attivo per sempre. Attraversa una serie di stati che il sistema gestisce automaticamente. Capire questi stati aiuta a leggere il catalogo: se un attrezzo non viene scelto più, magari è perché è passato in quarantena, non perché sia rotto.

6. Le quattro origini: a mano, generato, importato, di sistema

Tutti gli executor hanno la stessa anatomia esterna, ma nascono in quattro modi diversi. La distinzione non è cosmetica: cambia chi li scrive, dove vivono sul disco, e da dove provengono le idee che li abitano.

Perché l'origine importata esiste

Una libreria di terzi ha tipicamente una sua documentazione testuale che spiega come si usa: «per leggere il calendario chiama gws calendar list; per creare un evento usa --summary e --start». Lo standard agentskills.io ha codificato questa documentazione in un formato preciso (un file Markdown con intestazione strutturata). L'importatore di Metnos legge quel formato, lo traduce nel vocabolario chiuso del sistema, e genera la cartella dell'executor come se fosse scritta a mano.

Il vantaggio: ogni servizio già documentato come skill (calendario di Google, posta, drive di archiviazione,...) si può portare in Metnos senza riscriverlo da capo. Lo svantaggio: bisogna fidarsi di chi ha scritto la skill (e dei suoi script di supporto). Per questo l'importatore non installa nulla in /opt/metnos/executors/: gli executor importati vivono in una cartella separata, sotto sorveglianza, e passano comunque dal vaglio prima di ogni chiamata.

Un dettaglio operativo: gli executor importati che hanno bisogno di credenziali (una chiave di una API esterna, il file di sessione di un account) non se le inventano. La prima volta che li chiami, ti aprono una finestra di dialogo, ti chiedono il dato mancante, lo cifrano in una cassaforte locale, e proseguono. Le chiamate successive trovano la credenziale già al suo posto. Niente password nel codice, niente file di configurazione da modificare a mano.

7. Tre esempi concreti

Vediamo tre executor realmente in uso, raccontati da fuori. Niente codice sorgente: solo cosa chiedi e cosa ottieni.

7.1 get_now — "che ora è?"

L'attrezzo più semplice del catalogo. Non ha argomenti obbligatori. Ritorna un dizionario con la data e l'ora correnti.

chiamata: get_now(timezone="Europe/Rome")
risposta: { ok: true,
 content: "2026-05-06T16:45:23+02:00",
 metadata: { timezone: "Europe/Rome", iso8601: "...", epoch:... } }

Niente rete, nessun file letto, nessuna scrittura. Permessi: time:read. È uno di quegli attrezzi che sembrano superflui finché non si capisce perché servono: il pianificatore non deve mai inventarsi la data dalla memoria di addestramento. Quando deve calcolare "le mail di ieri", chiama prima get_now, poi calcola "ieri" sottraendo. Così "ieri" è sempre quello vero, non quello del giorno in cui il modello è stato addestrato.

7.2 find_files — "trovami le foto"

Cerca file per nome o per modello (le classiche "estensioni"). Restituisce la lista con i metadati di base: percorso, nome, dimensione, data ultima modifica, tipo.

chiamata: find_files(base_path="/home/user/images", pattern="*.jpg")
risposta: { ok: true,
 entries: [
 {path: "/home/.../foto1.jpg", size: 2458123,...},
 {path: "/home/.../foto2.jpg", size: 1923456,...},...
 ],
 metadata: { count: 247,... } }

Il pianificatore lo usa quando deve passare la lista a un altro attrezzo: per esempio filtrare le foto più recenti, calcolare la dimensione totale, comprimere quelle più vecchie. Notare che la filtrazione non sta in find_files: l'attrezzo torna i file e basta. Se vuoi un sottoinsieme, glielo chiedi col modello, oppure passi il risultato a un altro attrezzo che filtra. Una cosa sola alla volta.

7.3 filter_lists — "trovami eventi che si sovrappongono"

Un attrezzo che mette in relazione due liste invece di una. Lo usi quando la domanda dell’utente incrocia due insiemi: «quali appuntamenti HLT si sovrappongono a quelli MNM nei prossimi tre mesi?», oppure «quali file sono presenti sia in questa cartella sia nell’altra?».

chiamata: filter_lists(op="overlap",
 from_step=2, # lista A (eventi HLT)
 with_step=3) # lista B (eventi MNM)
risposta: { ok: true,
 op: "overlap",
 entries: [...gli eventi di A che si sovrappongono ad almeno uno di B... ],
 metadata: { count_a: 4, count_b: 5, count_out: 0 } }

Le operazioni disponibili sono cinque. intersect tiene solo le entries presenti in entrambe le liste (il confronto avviene su una chiave indicata, ad esempio il percorso del file). union unisce le due liste eliminando i duplicati. difference tiene le entries di A che non compaiono in B. symdiff è la differenza simmetrica (quel che c’è solo in A o solo in B). overlap è un’operazione temporale: tiene gli eventi di A che cadono in un intervallo sovrapposto a qualche evento di B, riconoscendo da solo i campi di inizio e fine.

Le tre primitive che lavorano sulle liste hanno ruoli complementari e ben separati: filter_entries riduce una lista applicando un predicato a un campo (where_starts_with, where_contains, where_glob, where_regex); filter_lists combina due liste con le operazioni di insieme appena viste; compute_entries calcola un singolo numero a partire da una lista (somma, media, minimo, massimo, conteggio). Le tre primitive coprono insieme la quasi totalità delle manipolazioni che servono, senza dover introdurre verbi nuovi.

7.4 send_messages — "manda un messaggio a Lucia"

Spedisce uno o più messaggi via Telegram (oggi) o via email (in arrivo). Argomento principale: una lista di messaggi, ognuno con destinatario e testo.

chiamata: send_messages(messages=[
 {to_user: "lucia", body: "Sono uscito, torno alle 7."}
 ])
risposta: { ok: true, ok_count: 1, fail_count: 0,
 results: [{to_user: "lucia", channel: "telegram", message_id: "abc123"}] }

Un attrezzo "trasformativo": modifica il mondo, manda davvero un messaggio. Per questo gli executor che cambiano qualcosa al mondo vengono trattati con più cautela: il loro manifesto dichiara permessi più ampi (net:write), passano da un controllo prima dell'esecuzione, e il loro effetto resta tracciato in modo da poterlo annullare. Vedi vaglio per i controlli pre-esecuzione e approval_ux per come si chiede conferma all'utente.

8. Per andare più a fondo

Questo documento è un'introduzione. Se vuoi capire i meccanismi che stanno sotto — come si firma un manifesto, come si applica il recinto, come il Synt genera il codice, come il pianificatore sceglie un attrezzo — i documenti seguenti vanno letti uno alla volta.

Per le decisioni di progetto (perché questa scelta e non quella) è tenuto un registro in /opt/metnos/decisions/. Esempi: perché gli executor generati stanno in una cartella diversa da quelli scritti a mano; come si chiede una password senza farla finire in chiaro nei log; come si fa l'indicizzazione di trentamila foto senza bloccare tutto il resto.

Metnos — executor, introduzione didattica