closedhumanPR #216Payments

Payments: Prava plugin + policy_commerce scenario

Adds packages/nest-plugin-prava, a Payments-layer plugin that moves real

Author

Nerdboss-stm avatar

@Nerdboss-stm

github profile →
Status
Closed without merging
Opened on
Aug 3
Branch
hackathon/nerdboss-stm-prava-payments

Description

The pitch.

Adds `packages/nest-plugin-prava`, a Payments-layer plugin that moves real
money in the Prava Agentic Payments Sandbox under a human-granted policy,
plus a `policy_commerce` scenario and `scenarios/prava_marketplace.yaml`.

It implements the `Payments` protocol — `quote`, `pay`, `verify_payment`,
`refund` — and `balance`, so it also drops into the bundled `marketplace`
scenario.

## Why it is shaped this way

"Autonomous agent with a credit card" is the wrong shape, so authority is
split in two.

The owner approves a bounded **envelope** with their passkey: merchant
scoped, per-charge capped, one charge per payment cycle, enforced at the
Visa network. That happens once, before the simulation, and this plugin
never automates or simulates it. Then a deterministic arbiter evaluates
every charge against a signed clause tree before any money call is made.
No model sits in the decision path.

Inside the approved envelope the agent transacts on its own. Outside it,
the answer is no.

## Refusals are first class

`POLICY_NEEDS_HUMAN` (over the per-charge cap), `POLICY_REFUSED` (a
capability clause failed), `NO_ENVELOPE_CAPACITY` (every envelope's cycle
is spent) and `NO_OFFER` all raise `PravaPaymentError` carrying the failing
clause path, and all happen before any network call — so a simulation that
hits them consumes nothing. `refund()` always raises: Prava has no refund
on the surface this uses, and pretending otherwise would be worse than
saying so.

`sandbox-evidence.json` records a real run of both paths: a settled $18.00
purchase with its transaction id, and a refusal at `root.all_of[3]` with
"amount $70.50 exceeds cap $47.00" and zero transactions consumed.

## Notes for review

- The scenario registers through a new `nest.scenarios` entry point rather
  than an import inside `nest_core.scenarios`, so core stays free of any
  knowledge of packages that contribute scenarios. That is the only change
  outside the new package, and it mirrors how the layer plugins already
  load.
- Contract and scenario tests run offline with no credentials and no
  network. `tests/test_sandbox_live.py` is the only file that spends
  anything, and it skips unless `QUARTERMASTER_CONSOLE_URL` is reachable.
- `make ci-local` exits 0 here: ruff, `ruff format --check`, pyright strict
  and pytest at 1323 passed, 4 skipped.

Built for the Agentic Commerce Hackathon (Prava x OpenAI). The plugin is a
thin client over a Quartermaster deployment, which holds the arbiter, the
envelope router and the append-only ledger; `console_url` points it at any
instance.

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/216/head:pr-216
git checkout pr-216