← Indice documentazione Guida all'architettura › scratchpad

Metnos

Scratchpad delle osservazioni

Ciò che il modulo offre e ciò che il runtime usa davvero.

runtime/scratchpad.py implementa un archivio temporaneo per conservare un'osservazione completa e mostrarne al modello soltanto un riferimento o una porzione. L'API esiste, ma il motore corrente non collega automaticamente le grandi osservazioni a questo archivio e non espone scratchpad_read nel catalogo ordinario. La distinzione è essenziale: il modulo disponibile non va presentato come funzione attiva.

1. Comportamento corrente

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.

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

Metodo o valore	Funzione
`Scratchpad.open(path)`	Apre o crea il database SQLite e il relativo schema.
`put(turn_id, step_num, executor_name, observation, ttl_seconds)`	Salva l'osservazione e restituisce una rappresentazione sintetica.
`get(id)`	Restituisce la riga completa corrispondente all'identificatore.
`read(id, mode, n, start, end)`	Restituisce tutto il contenuto oppure una porzione iniziale, finale o compresa in un intervallo.
`list_for_turn(turn_id)`	Elenca metadati e riassunti delle voci appartenenti a un turno.
`gc(now)`	Elimina le righe la cui scadenza è trascorsa.
`stats()`	Conta voci e byte conservati.
`SCRATCHPAD_READ_TOOL`	Descrive il possibile strumento incorporato, ma la sola costante non lo rende visibile al pianificatore corrente.

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. Rappresentazione sintetica

Per un testo lungo, il modulo conserva l'intero contenuto e produce un riassunto formato dall'inizio e dalla fine. Per dati binari 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 riassunto.

La rappresentazione sintetica può mantenere anche scalari 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

Modalità	Risultato
`full`	Contenuto completo.
`head`	Primi `n` caratteri o byte; il valore predefinito dichiarato dallo strumento è 2000.
`tail`	Ultimi `n` caratteri o byte.
`range`	Intervallo da `start` incluso a `end` escluso.

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:

un solo punto di decisione che confronti la dimensione dell'osservazione con una configurazione canonica;
la chiamata a put prima di costruire il contesto visibile al modello;
l'esposizione di scratchpad_read soltanto quando esistono voci accessibili al turno e all'utente correnti;
un controllo di proprietà su ogni get, read e list_for_turn;
limiti sulla lettura full, così una voce grande non rientra interamente nel contesto che si voleva proteggere;
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.