Human-in-the-loop-bestandsuitvoer via NextPDF Connect

In één oogopslag

De human-in-the-loop (HITL)-bevestigingsgate helpt onbedoelde schrijfacties naar het bestandssysteem te voorkomen. Bij een aanroep van output_pdf met een file_path pauzeert de gate de aanroep en geeft deze een eenmalige challenge terug in plaats van het bestand te schrijven. Na menselijke goedkeuring roept de agent de tool opnieuw aan met het token; pas daarna wordt het bestand geschreven. Base64-uitvoer (geen file_path) valt niet onder de gate.

Installeren

composer require nextpdf/server

Bind een transport. Standaard gebruikt output_pdf het risiconiveau Approval Required.

Conceptueel overzicht

De gate evalueert het effectieve risiconiveau: het niveau dat overblijft na een eventuele override op basis van configuratie of de identiteit van de aanroeper. Voor een tool met Approval Required:

base64-modus — output_pdf zonder file_path wordt teruggebracht naar Review en zonder bevestiging toegestaan. Dit veroorzaakt geen neveneffect op het bestandssysteem.
bestandsmodus — output_pdf met een file_path blijft op Approval Required staan. De gate slaat een eenmalig token op dat aan de toolnaam is gebonden en geeft vervolgens een challenge terug. Als het doelbestand al bestaat, bevat de challenge-tekst een waarschuwing over overschrijven. Het token verloopt na een vast tijdvenster.

In elk transport is het resultaat van de gate een normaal antwoord. Een goedkeuring die nog in behandeling is, is een onderbreking van de workflow, geen transportfout (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

API-oppervlak

Tool	Rol	Risiconiveau
`create_pdf`	De sessie openen	Safe
`set_font`, `add_text`	Inhoud opbouwen	Caution
`output_pdf` (base64)	Inline teruggeven; geen gate	Review
`output_pdf` (bestand)	Naar schijf schrijven; gated	Approval Required

De tool catalog is de gezaghebbende bron; welke tools beschikbaar zijn, hangt af van het geïnstalleerde niveau. De HITL risk niveaus reference definieert de risicoladder en de gate.

Codevoorbeeld — Snelstart

create_pdf → bouw de inhoud op met set_font/add_text.
output_pdf met een file_path → de gate geeft een challenge-envelop terug (het bestand wordt niet geschreven).
Geef de challenge door aan de mens.
Roep na goedkeuring output_pdf opnieuw aan met dezelfde argumenten plus _confirmation_token ingesteld op het token uit de challenge → het bestand wordt geschreven en de sessie wordt vernietigd.

Codevoorbeeld — Productie

Behandel de challenge altijd als een pauze. Probeer het niet opnieuw in een lus en verzin geen token.
Het token is eenmalig en gebonden aan de toolnaam. Een token dat is uitgegeven voor output_pdf kan geen andere tool autoriseren.
Als de mens afwijst, roep dan niet opnieuw aan. Roep in plaats daarvan output_pdf in base64-modus aan om de bytes op te halen zonder een bestand te schrijven. Hiervoor moet de sessie nog bestaan, dus gebruik destroy: false bij de gated poging als dit nodig kan zijn.
Als het token verloopt voordat het wordt goedgekeurd, geeft de gate een nieuwe challenge uit. Geef de nieuwe door.

Randgevallen en valkuilen

Token nooit verstrekt. De bewerking blijft in behandeling. De mens moet goedkeuren; geef die goedkeuring vervolgens door en roep opnieuw aan.
Verlopen token. Er wordt een nieuwe challenge uitgegeven. Geef deze opnieuw door.
Verkeerde tool. Tokens zijn aan een tool gebonden. Hergebruik voor een andere tool mislukt en er wordt een nieuwe challenge uitgegeven.
Niet-absoluut pad. Wordt vóór de gate geweigerd als een ongeldig pad.
Geen schrijfrechten / schijf vol. Dit is een fout bij het schrijven van het bestand na goedkeuring. Maak deze zichtbaar. Probeer het niet blindelings opnieuw.
Sessie vernietigd vóór de herhaalde aanroep. Als een eerdere output_pdf destroy: true gebruikte, is de sessie verdwenen. Gebruik destroy: false wanneer er een goedkeuringsronde wordt verwacht.

Prestaties

De gate voegt een lookup in de token-store toe en een retourrit voor menselijke goedkeuring. De mens bepaalt de doorlooptijd, niet de server. Het profiel is structural.

Beveiligingsnotities

De gate vormt de grens tussen een agent en het bestandssysteem van de server. Deze grens bestaat omdat het schrijven van een bestand een onomkeerbaar neveneffect is dat door een mens moet worden geautoriseerd. Het token is eenmalig, aan een tool gebonden en in tijd beperkt. Argumenten worden er bewust niet in gehasht, omdat clients JSON opnieuw kunnen serialiseren met een andere sleutelvolgorde. De binding is daarom tool + nonce + TTL, niet exact op de argumenten. Log het token niet. Behandel het als een eenmalig geheim.

Conformiteit

Verklaring	Specificatie	Clausule	reference_id
Een goedkeuring die nog in behandeling is, is een normaal antwoord, geen fout.	PSR-18	§3
Het transport geeft ongeacht het resultaat een antwoord terug.	PSR-18	§p2

Dit recipe beschrijft het gate-mechanisme. Het beweert niet dat de gate een bewerking „veilig” maakt. De gate zorgt ervoor dat een neveneffect door een mens is geautoriseerd.

Commerciële context

Niet van toepassing — de gate en output_pdf behoren tot Core.

Beschikbaarheid per transport

Transport	Beschikbaar	Notities
MCP (stdio)	Ja	De challenge wordt aan de host getoond als een toolresultaat dat de mens moet bevestigen.
REST	Ja	De challenge wordt teruggegeven in de antwoordbody; roep opnieuw aan met het token.
gRPC	Ja	Unair; de challenge is het antwoordbericht; roep opnieuw aan met het token.

HITL-risiconiveau

De risicoladder is Safe (0) → Caution (1) → Review (2) → Approval Required (3). Alleen tools met Approval Required vereisen menselijke bevestiging. output_pdf is Approval Required. base64-modus brengt het terug naar Review en slaat de gate over. bestandsmodus houdt Approval Required aan en laat de gate de aanroep afhandelen. De canonieke ladder en policy-resolutie staan in de HITL risk niveaus reference.

JSON-envelop van de bevestigingsgate

Het resultaat van de gate heeft precies twee vormen, zoals blootgesteld door de bevestigingsgate van de server:

Toegestaan (Safe/Caution/Review, of een geldig token verbruikt):

{ "allowed": true }

Challenge (Approval Required zonder een geldig token):

{
  "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>"
}

Als het doelbestand al bestaat, bevat de challenge-tekst ook een waarschuwingsregel over overschrijven. Dezelfde tool opnieuw aanroepen met _confirmation_token ingesteld op de waarde van token geeft { "allowed": true } terug, waarna de bewerking doorgaat. Het token is eenmalig en verloopt na het in de challenge vermelde tijdvenster.