Output di file con approvazione umana in NextPDF Connect

In sintesi

Il gate di conferma con intervento umano (HITL) protegge il filesystem da scritture non intenzionali. Quando output_pdf viene chiamato con un file_path, il gate intercetta la chiamata e restituisce una sfida monouso invece di scrivere il file. Una persona approva la sfida, l’agente ripete la chiamata con il token e solo allora il file viene scritto. L’output in Base64 (senza file_path) non passa dal gate.

Installazione

composer require nextpdf/server

Associare un trasporto. Per impostazione predefinita, output_pdf ha livello di rischio Approvazione richiesta.

Panoramica concettuale

Il gate valuta il livello di rischio effettivo, ovvero il livello che rimane dopo qualsiasi override della configurazione o dell’identità del chiamante. Per uno strumento classificato come Approvazione richiesta:

modalità base64 — output_pdf senza file_path viene declassato a Revisione e consentito senza conferma. Non si verifica alcun effetto collaterale sul filesystem.
modalità file — output_pdf con un file_path resta in Approvazione richiesta. Il gate memorizza un token monouso associato al nome dello strumento e restituisce una sfida. Se il file di destinazione esiste già, il testo della sfida include un avviso di sovrascrittura. Il token scade dopo una finestra temporale fissa.

In ogni trasporto, il risultato del gate è una risposta normale. Un’approvazione in sospeso è una pausa nel flusso di lavoro, non un errore di trasporto (PSR-18 §3; PSR-18 §p2).

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Apre la sessione	Sicuro
`set_font`, `add_text`	Costruisce il contenuto	Cautela
`output_pdf` (base64)	Restituzione inline; nessun gate	Revisione
`output_pdf` (file)	Scrittura su disco; con gate	Approvazione richiesta

Il catalogo degli strumenti è il riferimento per il catalogo e gli strumenti disponibili dipendono dal livello installato. La scala dei rischi e il gate sono definiti nel riferimento ai livelli di rischio HITL.

Esempio di codice — Avvio rapido

create_pdf → costruire il contenuto con set_font/add_text.
output_pdf con un file_path → il gate restituisce un involucro con la sfida (il file non viene scritto).
Inoltrare la sfida alla persona.
In caso di approvazione, richiamare output_pdf con gli stessi argomenti più _confirmation_token impostato sul token della sfida → il file viene scritto e la sessione viene distrutta.

Esempio di codice — Produzione

Trattare sempre la sfida come una pausa. Non riprovare in ciclo e non fabbricare un token.
Il token è monouso ed è associato al nome dello strumento. Un token emesso per output_pdf non può autorizzare un altro strumento.
Se la persona rifiuta, non richiamare. Per recuperare i byte senza scrivere un file, chiamare invece output_pdf in modalità base64. Questo richiede che la sessione esista ancora, quindi usare destroy: false nel tentativo sottoposto al gate se si prevede di averne bisogno.
Se il token scade prima dell’approvazione, il gate emette una nuova sfida. Inoltrare la nuova sfida.

Casi limite e insidie

Token mai fornito. L’operazione rimane in sospeso. La persona deve approvare; quindi inoltrare e richiamare.
Token scaduto. Viene emessa una nuova sfida. Inoltrarla di nuovo.
Strumento errato. I token sono associati allo strumento. Il riutilizzo per uno strumento diverso fallisce e viene emessa una nuova sfida.
Percorso non assoluto. Rifiutato prima del gate come percorso non valido.
Nessun permesso di scrittura / disco pieno. Si tratta di un errore di scrittura del file dopo l’approvazione. Segnalarlo. Non riprovare alla cieca.
Sessione distrutta prima del richiamo. Se un precedente output_pdf ha usato destroy: true, la sessione non esiste più. Usare destroy: false quando si prevede il ciclo di approvazione.

Prestazioni

Il gate aggiunge una ricerca nello store dei token e un passaggio di approvazione umana. Il tempo complessivo è dominato dall’intervento umano, non dal server. Il profilo è structural.

Note sulla sicurezza

Il gate è il confine tra un agente e il filesystem del server. Esiste perché la scrittura di un file è un effetto collaterale irreversibile che una persona dovrebbe autorizzare. Il token è monouso, associato allo strumento e a tempo limitato. Per scelta, gli argomenti non vengono sottoposti ad hashing nel token, perché i client potrebbero riserializzare il JSON con un ordine delle chiavi diverso. Il vincolo è quindi strumento + nonce + TTL, non l’esattezza degli argomenti. Non registrare il token nei log. Trattarlo come un segreto monouso.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Un’approvazione in sospeso è una risposta normale, non un errore.	PSR-18	§3
Il trasporto restituisce una risposta indipendentemente dal risultato.	PSR-18	§p2

Questa ricetta descrive il meccanismo del gate. Non afferma che il gate renda «sicura» alcuna operazione. Il gate fa sì che un effetto collaterale sia autorizzato da una persona.

Contesto commerciale

Non applicabile — il gate e output_pdf sono Core.

Disponibilità dei trasporti

Trasporto	Disponibile	Note
MCP (stdio)	Sì	La sfida viene presentata all’host come risultato dello strumento, affinché la persona la confermi.
REST	Sì	La sfida viene restituita nel corpo della risposta; richiamare con il token.
gRPC	Sì	Chiamata unaria; la sfida è il messaggio di risposta; richiamare con il token.

Livello di rischio HITL

La scala dei rischi è Sicuro (0) → Cautela (1) → Revisione (2) → Approvazione richiesta (3). Solo gli strumenti classificati come Approvazione richiesta richiedono la conferma umana. output_pdf è classificato come Approvazione richiesta. La modalità base64 lo declassa a Revisione ed evita il gate. La modalità file mantiene Approvazione richiesta e applica il gate. La scala canonica e la risoluzione delle policy si trovano nel riferimento ai livelli di rischio HITL.

Involucro JSON del gate di conferma

Il risultato del gate ha esattamente due forme, come esposte dal gate di conferma del server:

Consentito (Sicuro/Cautela/Revisione, oppure un token valido consumato):

{ "allowed": true }

Sfida (Approvazione richiesta senza un token valido):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Quando il file di destinazione esiste già, il testo della challenge contiene anche una riga di avviso di sovrascrittura. Richiamare lo stesso strumento con _confirmation_token impostato sul valore del token restituisce { "allowed": true } e l’operazione procede. Il token è monouso e scade dopo la finestra indicata nella sfida.