Repository navigation
fix(bills-agent): an approval hold is a wait, not a failed payment - #138
Merged
Merged
Conversation
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
approved these changes
Nov 18, 2026
rapguit
left a comment
Contributor
There was a problem hiding this comment.
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:
- Em
codesparPay, com uma retenção viva, qualquer recusa do pedido repetido volta ao modelo comoin_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. - 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.
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.
Contributor
Author
|
Obrigado pela revisão, Rapha. Registrei os três pontos em
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O problema
Com autonomia
confirm_eachno Teste,POST /v1/consumer-payments/executeresponde 403policy_deniedcomreason: "approval_required",approval_ideattempt_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
awaiting_approval), e não como recusa. O engine mantém a execução emexecutingcomreason: rail_awaiting_approvale guarda oapproval_idpor tentativa emrail_approvals.resumeereconcilereapresentam o mesmoattempt_id: pendente continua em espera, aprovado fechasettledcom o recibo, negado ou expirado fechafailed(psp_attempt_conflict), sem tentativa nova.policyExtensionrecusa, nos três gates, um pedido do mesmo mandato com o mesmoitems_hashenquanto 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 rodarnpm run resume. Na repetição ele mostra a mesma linha, com a execução original.reconcileganha o achadoawaiting_approval. Ele também passa a procurar o recibo no run que gravou oreceipt.saved: um recibo salvo numa retomada era relatado comoreceipt_missing_locally.StubRailaceitaapprovalPayeesesetApprovalDecision, para os testes percorrerem pendente, aprovado, negado e expirado sem rede.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 emerror(error: "approval_required",reason: "policy_rule"). Oapproval_idé o mesmo. O rail aceita os dois formatos, e só comapproval_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-agentenpm run pt-accents.packages/agent-core/test/approval-hold.test.ts,packages/agent-core/test/attempt-replay.test.ts,agents/bills-agent/test/approval-hold.test.tsepackages/agent-runtime/test/outcome.test.ts. Nenhum teste existente foi removido, pulado ou afrouxado.test/one-agent-scaffold.test.tsfalha com e sem esta mudança (o diretório temporário é um link para/private); não é tocado aqui.csk_test_, simulador, sem dinheiro real), em 17/11/2026:resumeereconcilecom a aprovação pendenteresumesettled, um recibo;npm run verify -- <recibo> --from-apirespondeVERIFIED,sandbox trueresumefailedcompsp_attempt_conflict; nenhuma tentativa novaFora deste PR
items_hash: os mesmos itens em outra ordem são outro pedido. Também fica para a kits#113.resumeoureconcile.packages/agent-runtime/src/hosted/) não trata o eventoexecution.awaiting_approval; uma execução retida aparece ali comoawaiting_payer. Anotado em §68.