Skip to content

fix(bills-agent): an approval hold is a wait, not a failed payment - #138

Merged
JLmachado404 merged 2 commits into
mainfrom
fix/approval-hold-not-failure
Nov 18, 2026
Merged

JLmachado404 merged 2 commits into
mainfrom
fix/approval-hold-not-failure

Conversation

@JLmachado404

Copy link
Copy Markdown
Contributor

O problema

Com autonomia confirm_each no Teste, POST /v1/consumer-payments/execute responde 403 policy_denied com reason: "approval_required", approval_id e attempt_id: o pagamento fica retido até uma pessoa decidir. O kit lia esse 403 como falha (rail_failed). Uma nova rodada criava outra tentativa e outro pedido de aprovação, e aprovar os dois liquidava a mesma conta duas vezes.

O que muda

  • Core. O rail lê a retenção como um desfecho próprio (awaiting_approval), e não como recusa. O engine mantém a execução em executing com reason: rail_awaiting_approval e guarda o approval_id por tentativa em rail_approvals. resume e reconcile reapresentam o mesmo attempt_id: pendente continua em espera, aprovado fecha settled com o recibo, negado ou expirado fecha failed (psp_attempt_conflict), sem tentativa nova.
  • bills-agent. Uma policyExtension recusa, nos três gates, um pedido do mesmo mandato com o mesmo items_hash enquanto existe uma execução com retenção registrada. O terminal diz, em pt-BR e em inglês, que o pagamento aguarda aprovação de uma pessoa, mostra o id da aprovação e manda rodar npm run resume. Na repetição ele mostra a mesma linha, com a execução original.
  • Runtime. reconcile ganha o achado awaiting_approval. Ele também passa a procurar o recibo no run que gravou o receipt.saved: um recibo salvo numa retomada era relatado como receipt_missing_locally.
  • Stub. StubRail aceita approvalPayees e setApprovalDecision, para os testes percorrerem pendente, aprovado, negado e expirado sem rede.
  • Docs. docs/OPEN_QUESTIONS.md §68 registra os dois formatos do 403; os READMEs do core e do bills-agent citam a retenção.

Divergência da API que o teste real mostrou

A reapresentação de uma tentativa pendente não devolve o mesmo corpo da primeira resposta. A primeira nomeia a retenção em reason (error: "policy_denied", reason: "approval_required"); a reapresentação nomeia em error (error: "approval_required", reason: "policy_rule"). O approval_id é o mesmo. O rail aceita os dois formatos, e só com approval_id. Os dois corpos estão em §68.

Como foi testado

  • npm run check, npm run typecheck, npm test (1143 passam, 44 pulados: os casos do emulador de WhatsApp), npm run eval --workspace=agents/bills-agent e npm run pt-accents.
  • Dos 25 testes novos, 23 falham na base e passam com a mudança; os outros dois são guardas de regressão, verdes nos dois lados. Estão em packages/agent-core/test/approval-hold.test.ts, packages/agent-core/test/attempt-replay.test.ts, agents/bills-agent/test/approval-hold.test.ts e packages/agent-runtime/test/outcome.test.ts. Nenhum teste existente foi removido, pulado ou afrouxado.
  • No macOS, test/one-agent-scaffold.test.ts falha com e sem esta mudança (o diretório temporário é um link para /private); não é tocado aqui.
  • Teste real no modo Teste (chave csk_test_, simulador, sem dinheiro real), em 17/11/2026:
Passo Resultado
Mesmo pedido duas vezes Primeira rodada sai 3 e mostra o id da aprovação; a repetição sai 0, mostra a mesma aprovação e não despacha
Caixa de Aprovações Um único pedido pendente
resume e reconcile com a aprovação pendente Continuam em espera; nada é reenviado
Aprovação, depois resume settled, um recibo; npm run verify -- <recibo> --from-api responde VERIFIED, sandbox true
Wallet Um único débito
Recusa, depois resume failed com psp_attempt_conflict; nenhuma tentativa nova

Fora deste PR

  • Pedido repetido depois da liquidação continua sendo pago de novo. É a kits#113 (chave de obrigação), cujo escopo ainda depende de decisão.
  • A regra de duplicata usa o items_hash: os mesmos itens em outra ordem são outro pedido. Também fica para a kits#113.
  • Uma retenção expirada ou negada segue recusando a repetição até alguém rodar resume ou reconcile.
  • A regra de duplicata lê o estado gravado: dois processos que rascunham antes de o primeiro 403 ser gravado ainda despacham os dois.
  • O canal hospedado (packages/agent-runtime/src/hosted/) não trata o evento execution.awaiting_approval; uma execução retida aparece ali como awaiting_payer. Anotado em §68.
  • O aviso de duplicata na caixa de Aprovações do dashboard.

With confirm_each in Test, POST /v1/consumer-payments/execute answers 403
with an approval_id and holds the payment for a person. The kit read that
as rail_failed; a second round made a second attempt and a second approval
request, and approving both paid the same bill twice.

The rail now reads the hold as its own outcome, on the first presentation
and on the replay of a pending attempt, whose body names it differently.
The engine keeps the execution executing (rail_awaiting_approval) with the
approval's id per attempt; resume and reconcile re-present the same
attempt_id, and the person's decision closes it: settled with its one
receipt, or failed on psp_attempt_conflict, never a fresh attempt.

The bills agent refuses, at every gate, a request with the same items
under the same mandate while a recorded hold is open, and tells the person
which provider approval it waits on, in pt-BR and en. reconcile finds a
receipt in the run that saved it, so one saved by resume is no longer
reported missing.

A request repeated after settlement is still paid again: that is kits#113.
docs/OPEN_QUESTIONS.md §68 has both 403 bodies and what is left open.

@rapguit rapguit left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revisei o código fora dos testes (rail, engine, runtime, bills-agent). O desenho está certo: a retenção vira um desfecho próprio, o resume e o reconcile reapresentam o mesmo attempt_id (o lookup chama o pay de novo) e o pedido repetido é recusado enquanto a retenção existe.

Três observações, nenhuma bloqueia:

  1. Em codesparPay, com uma retenção viva, qualquer recusa do pedido repetido volta ao modelo como in_progress, inclusive uma recusa por outro motivo (um mandato revogado depois da retenção, por exemplo). O comentário explica o caso do teto de janela; vale registrar em OPEN_QUESTIONS que os outros motivos também ficam atrás da retenção.
  2. A trava contra o pedido repetido lê só o estado local do kit. Outra pasta de estado ou outra máquina não vê a retenção. Fica coerente com o que a descrição deixa para a #113.
  3. expires_at é gravado e nada local age sobre ele: a expiração só aparece no próximo resume ou reconcile. Se for intencional, uma linha no README do core evita a dúvida.

Não rodei a suíte localmente; me apoiei no CI verde deste head.

@JLmachado404

Copy link
Copy Markdown
Contributor Author

Obrigado pela revisão, Rapha. Registrei os três pontos em 2f54fc8 (só documentação, nenhum código mudou):

  1. Recusa por outro motivo atrás da retenção. docs/OPEN_QUESTIONS.md §68 agora diz que, com uma retenção gravada do mesmo pedido, qualquer recusa da repetição volta ao modelo como in_progress, inclusive um mandato revogado ou pausado depois da retenção. O motivo real fica na linha da execução recusada.
  2. Trava só no estado local. O mesmo parágrafo registra que outra pasta de estado ou outra máquina não vê a retenção e despacha uma tentativa nova, e aponta para a bills-agent: the same bill can be paid again in the same window #113.
  3. expires_at. É intencional: o kit grava e não age sobre ele, a expiração chega pelo 409 no próximo resume ou reconcile. Ficou uma linha no README do core e outra em §68.

@JLmachado404
JLmachado404 merged commit 71295a3 into main Nov 18, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants