feat(aifp1): describeQuote — say what a payment buys, not just the amount - #56
Merged
Conversation
…ount
Agent-flow audit, point 6. The 402 and the quote answer "1.06 POL" and leave the
agent — and whoever is watching it — to work out FOR WHAT: how many requests,
which paths, until when, at what fee. A payment prompt that states an amount
without the terms is one a careful agent should refuse and a careless one
over-pays on.
Every field needed already lives in the quote. describeQuote assembles them into
the sentence a reasonable payer needs before signing:
Pay 1.055375555391386 POL ($0.10) for 200 requests to /api/agent/genres
(incl. 1.00% fee), valid until 2026-09-04T13:00:00Z.
Three things it makes legible that the raw fields do not:
- the on-chain figure AND the USD, side by side, so neither is a surprise
- the fee as a RATE, computed from the split the quote carries, so an agent
can tell 1% from 50% rather than seeing only a total
- the scope in words — "any path under /api/agent" vs one exact path vs the
whole merchant. Scope is the field the wildcard bug proved everyone misreads,
and it decides what the money actually buys.
wei is converted with no float, so "1 POL" is exactly one. No native settlement
falls back to the USD amount rather than inventing a token figure.
Pure function, no I/O, so an MCP tool or a CLI can put it in front of an LLM or
a human unchanged. node suite: 215 passing. Version rc.7 -> rc.8.
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
1 participant
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.
Agent-flow audit, point 6. The 402 and the quote answer "1.06 POL" and leave the agent — and whoever is watching it — to work out for what: how many requests, which paths, until when, at what fee.
A payment prompt that states an amount without the terms is one a careful agent should refuse and a careless one over-pays on.
Every field is already in the quote.
describeQuoteassembles them:Three things it makes legible that the raw fields don't:
wei converted with no float ("1 POL" is exactly one). No native settlement → falls back to the USD amount rather than inventing a token figure.
Pure function, no I/O — an MCP tool or CLI can put it in front of an LLM or a human unchanged. node suite 215 passing. Version rc.7 → rc.8.