Saída de arquivo com humano no circuito (human-in-the-loop) no NextPDF Connect

Visão geral

A barreira de confirmação com humano no circuito (human-in-the-loop, HITL) ajuda a evitar gravações não intencionais no sistema de arquivos. Quando você chama output_pdf com um file_path, a barreira pausa a chamada e retorna um desafio de uso único em vez de gravar o arquivo. Depois que uma pessoa aprova, o agente chama novamente com o token e só então o arquivo é gravado. A saída em Base64 (sem file_path) não passa pela barreira.

Instalação

composer require nextpdf/server

Vincule um transporte. Por padrão, output_pdf usa o nível de risco Aprovação Obrigatória.

Visão conceitual

A barreira avalia o nível de risco efetivo: o nível que permanece depois de qualquer substituição por configuração ou identidade do chamador. Para uma ferramenta com Aprovação Obrigatória:

modo base64 — output_pdf sem file_path é rebaixado para Revisão e permitido sem confirmação. Esse modo não tem efeito colateral no sistema de arquivos.
modo de arquivo — output_pdf com um file_path permanece em Aprovação Obrigatória. A barreira armazena um token de uso único vinculado ao nome da ferramenta e, em seguida, retorna um desafio. Se o arquivo de destino já existir, o texto do desafio inclui um aviso de sobrescrita. O token expira após uma janela de tempo fixa.

Em todos os transportes, o resultado da barreira é uma resposta normal. Uma aprovação pendente é uma pausa no fluxo de trabalho, não uma falha de transporte (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

Superfície da API

Ferramenta	Função	Nível de risco
`create_pdf`	Abrir a sessão	Seguro
`set_font`, `add_text`	Montar o conteúdo	Cautela
`output_pdf` (base64)	Retorna em linha; sem barreira	Revisão
`output_pdf` (arquivo)	Grava em disco; com barreira	Aprovação Obrigatória

O catálogo de ferramentas é a referência principal, e as ferramentas disponíveis dependem do tier instalado. A referência dos níveis de risco HITL define a escala de risco e a barreira.

Exemplo de código — Início rápido

create_pdf → monte o conteúdo com set_font/add_text.
output_pdf com um file_path → a barreira retorna um envelope de desafio (o arquivo não é gravado).
Repasse o desafio à pessoa responsável pela aprovação.
Após a aprovação, chame output_pdf novamente com os mesmos argumentos, além de _confirmation_token definido com o token do desafio → o arquivo é gravado e a sessão é destruída.

Exemplo de código — Produção

Sempre trate o desafio como uma pausa. Não faça novas tentativas em loop e não invente um token.
O token é de uso único e vinculado ao nome da ferramenta. Um token emitido para output_pdf não pode autorizar outra ferramenta.
Se a pessoa responsável rejeitar, não faça a chamada novamente. Para recuperar os bytes sem gravar um arquivo, chame output_pdf em modo base64. Isso exige que a sessão ainda exista; por isso, use destroy: false na tentativa com barreira se você acredita que vai precisar dela.
Se o token expirar antes da aprovação, a barreira emite um novo desafio. Repasse o novo desafio.

Casos extremos e pegadinhas

Token nunca fornecido. A operação permanece pendente. A pessoa responsável precisa aprovar; depois, repasse o token e chame novamente.
Token expirado. Um novo desafio é emitido. Repasse esse novo desafio.
Ferramenta errada. Os tokens são vinculados à ferramenta. A reutilização para uma ferramenta diferente falha e um novo desafio é emitido.
Caminho não absoluto. É rejeitado antes da barreira como caminho inválido.
Sem permissão de gravação / disco cheio. Isso é uma falha de gravação de arquivo após a aprovação. Propague a falha. Não tente novamente às cegas.
Sessão destruída antes da nova chamada. Se um output_pdf anterior usou destroy: true, a sessão deixou de existir. Use destroy: false quando você espera passar pelo ciclo de ida e volta da aprovação.

Desempenho

A barreira adiciona uma consulta ao armazenamento de tokens e uma ida e volta para a aprovação humana. A pessoa responsável pela aprovação determina o tempo real, não o servidor. O perfil é structural.

Notas de segurança

A barreira é o limite entre um agente e o sistema de arquivos do servidor. Ela existe porque uma gravação de arquivo é um efeito colateral irreversível que uma pessoa deve autorizar. O token é de uso único, vinculado à ferramenta e tem validade limitada. Os argumentos deliberadamente não entram no hash dele porque os clientes podem reserializar o JSON com uma ordem de chaves diferente. Portanto, a vinculação é ferramenta + nonce + TTL, não exata por argumento. Não registre o token em log. Trate-o como um segredo de uso único.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Uma aprovação pendente é uma resposta normal, não uma falha.	PSR-18	§3
O transporte retorna uma resposta independentemente do resultado.	PSR-18	§p2

Esta receita descreve o mecanismo da barreira. Ela não afirma que a barreira torna qualquer operação “segura”. A barreira faz com que um efeito colateral tenha autorização humana.

Contexto comercial

Não se aplica — a barreira e output_pdf são Core.

Disponibilidade por transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	O desafio é exposto ao host como um resultado de ferramenta para uma pessoa confirmar.
REST	Sim	O desafio é retornado no corpo da resposta; chame novamente com o token.
gRPC	Sim	Unário; o desafio é a mensagem de resposta; chame novamente com o token.

Nível de risco HITL

A escala de risco é Seguro (0) → Cautela (1) → Revisão (2) → Aprovação Obrigatória (3). Apenas as ferramentas com Aprovação Obrigatória exigem confirmação humana. output_pdf é Aprovação Obrigatória. O modo base64 o rebaixa para Revisão e ignora a barreira. O modo de arquivo mantém Aprovação Obrigatória e aplica a barreira à chamada. A escala canônica e a resolução de política ficam na referência dos níveis de risco HITL.

Envelope JSON da barreira de confirmação

O resultado da barreira tem exatamente dois formatos, expostos pela barreira de confirmação do servidor:

Permitido (Seguro/Cautela/Revisão, ou um token válido consumido):

{ "allowed": true }

Desafio (Aprovação Obrigatória sem um token válido):

{
  "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 o arquivo de destino já existe, o texto de challenge também contém uma linha de aviso de sobrescrita. Invocar a mesma ferramenta novamente com _confirmation_token definido como o valor de token retorna { "allowed": true }, e a operação continua. O token é de uso único e expira após a janela de tempo indicada no desafio.