runtime/scratchpad.py implementa un archivio temporaneo pensato per tenere fuori dal contesto del modello i risultati troppo grandi. Potrebbe conservare il risultato completo e lasciarne nel piano soltanto un riepilogo con un identificatore. L'API esiste, ma il motore corrente non la usa per archiviare automaticamente le osservazioni e non espone scratchpad_read nel catalogo ordinario. È quindi un componente disponibile, non una funzione attiva del prodotto.

1. Comportamento corrente

L'idea è semplice. Se un executor restituisse, per esempio, mille righe di testo, lo scratchpad potrebbe conservarle e mostrare al modello soltanto «mille righe disponibili, identificatore X». Il modello potrebbe poi leggere solo l'inizio, la fine o l'intervallo che gli serve. Questo evita di riempire il contesto con dati che potrebbero non essere necessari.

Nel motore attivo, i risultati dei passi restano nella cronologia di esecuzione del turno. Un passo successivo li riusa con from_step o con un riferimento ${stepN.campo}; il runtime risolve il valore effettivo senza chiedere al modello di ricopiarlo. La sintesi finale proietta e limita i campi testuali che presenta al modello, mentre i dati completi restano nel risultato del passo.

Nel codice il termine scratchpad compare anche, in senso più generico, per indicare la cronologia dei passi usata durante un turno o la sua copia durante la ripresa di un dialogo. Quella cronologia è attiva, ma non è il database SQLite descritto in questa pagina.

All'inizio di un turno agent_runtime apre il database dello scratchpad ed elimina le voci scadute. Nel percorso corrente, però, non chiama Scratchpad.put. Anche il parametro storico scratchpad_threshold non governa l'esecuzione del motore. Di conseguenza non è corretto affermare che ogni osservazione sopra i 4 KB venga scaricata automaticamente nel database.

2. API disponibile

3. Archivio e durata

Il percorso predefinito è PATH_USER_DATA/scratchpad.db. La tabella conserva:

id · turn_id · step_num · executor_name · content_kind
content · size_bytes · summary · created_at · expires_at

Il valore predefinito di put è una durata di un'ora. L'eliminazione non è un processo autonomo: avviene soltanto quando un chiamante esegue gc. Una voce scaduta può quindi restare su disco fino alla pulizia successiva.

4. Il riepilogo prodotto dal modulo

Quando viene chiamato put, un testo lungo viene conservato per intero e il riepilogo ne mostra l'inizio e la fine. Per dati binari il modulo registra i byte e mostra dimensione e prefisso dell'impronta SHA-256. Per un risultato strutturato cerca campi quali entries, matches o results e comunica conteggio e schema, senza riversare gli elementi nel riepilogo.

Il riepilogo può mantenere anche valori semplici utili, per esempio conteggi, stato di troncamento, dimensione, messaggio ed errore. Il campo ref_hint spiega come riusare il risultato di un passo o come chiedere una porzione del contenuto.

5. Lettura a porzioni

Il testo viene restituito come UTF-8 con sostituzione dei byte non validi. Il contenuto binario viene codificato in Base64. I metadati indicano dimensione completa, dimensione restituita, tipo e modalità di lettura.

6. Cosa occorre per collegarlo

Un'integrazione corretta nel motore richiede almeno:

1. un solo punto di decisione che confronti la dimensione dell'osservazione con una configurazione canonica;
2. la chiamata a put prima di costruire il contesto visibile al modello;
3. l'esposizione di scratchpad_read soltanto quando esistono voci accessibili al turno e all'utente correnti;
4. un controllo di proprietà su ogni get, read e list_for_turn;
5. limiti sulla lettura full, che oggi non ha un tetto proprio, così una voce grande non rientra interamente nel contesto che si voleva proteggere;
6. pulizia, osservabilità e prove di ripresa dopo un dialogo sospeso.

7. Verifiche necessarie

Il collegamento automatico fra motore e database non è attivo. La sua attivazione richiede prove dedicate su testo, binari, risultati strutturati, intervalli, scadenza, concorrenza e ripresa del turno.

La verifica più importante è multiutente: un identificatore ottenuto da un utente non deve permettere di leggere una voce appartenente a un altro, nemmeno passando direttamente l'identificatore all'API incorporata.

8. Confini di sicurezza

• Lo schema corrente non contiene un proprietario. Conserva turn_id, ma non owner_user_id, attore o canale. get e read accettano soltanto l'identificatore e non applicano autorizzazione.
• L'identificatore opaco non è una credenziale. La difficoltà di indovinarlo non sostituisce un controllo di proprietà.
• Il database è condiviso dall'installazione. Non va descritto come isolato per utente finché schema e chiamanti non applicano quella separazione.
• Il contenuto non è cifrato dal modulo. La protezione a riposo dipende dai permessi del percorso dati e dall'ambiente che lo ospita.
• La scadenza è logica. I dati vengono rimossi soltanto all'esecuzione di gc.

Per questi motivi il modulo può essere studiato e collaudato come componente, ma non deve essere collegato a una superficie multiutente senza prima aggiungere proprietà, autorizzazione e prove di isolamento.