agentic-wallet-mcp 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -8,6 +8,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.12.0] — 22 September 2026
+
+### Added
+
+- **Three free policy read tools**: `get_policy_template_schema` (which spending rules a template
+  allows), `get_my_policy` (the policies this owner has deployed on chain) and `policy_preflight`
+  (is a draft policy valid, and does it MEAN what the user thinks). All read-only: they sign
+  nothing, spend nothing and deploy nothing. Each reports a three-state result, so "this network has
+  no policy system" is never reported as "you have no policy".
+- **`clear_stuck_payment_receipt`**: the supported way to discard a Verified AI Birthcert payment
+  receipt the wallet is holding and refusing to pay past — previously only possible by deleting a
+  file on the server, which a hosted subscriber cannot do. Two steps by construction: the first call
+  clears nothing and returns the receipt id, and clearing requires echoing that exact id back.
+- **`request_ai_birthcert_verification` gains `discardStuckReceiptAndPayFresh`**: discard a stuck
+  receipt and pay again in one call. Takes the receipt id, never a boolean, so a receipt cannot be
+  discarded that was not first shown to the user. Refuses a mismatched id, a receipt belonging to a
+  live session, and combination with `dryRun` — spending nothing in each case.
+- **`SETTLEMENT_STUCK_AFTER_MS`** (default `86400000`, 24h): how long an unconfirmed settlement may
+  stay unresolved before the wallet stops calling it "still settling" and calls it permanently stuck.
+
+### Changed
+
+- **`check_ai_birthcert_verification` now advances a queued settlement** instead of only reporting
+  it. It replays the saved receipt — never a new payment — and returns the live session once it
+  settles, so "check back in a few minutes" genuinely progresses the flow.
+- **A queued settlement no longer blocks the tool call for ~20 minutes.** It returns within a bounded
+  wall-clock budget (`SETTLEMENT_WAIT_BUDGET_MS`, default 90s) as
+  `{ settlementPending: true, paymentReceipt, message }` — the payment succeeded and is in flight,
+  which is not an error.
+- **Settlement messages lead with their verdict** (`PAYMENT SENT` / `OUTCOME UNKNOWN` / `RECEIPT VOID`)
+  and carry `paymentReceipt` as its own field, so an assistant summarising the result cannot turn
+  "we do not know yet" into "it failed".
+- **The three settlement verdicts are now told apart.** A receipt the service declares finished is
+  terminal and reported as `status: "receipt_void"`; an unresolved one is judged by the receipt's own
+  age — recent means "still settling, check back", older than `SETTLEMENT_STUCK_AFTER_MS` means
+  "this is not coming back". None of them claims the fee was refunded: a settlement can expire after
+  the money has already moved, so the receipt id is always handed back for support.
+
+### Fixed
+
+- A stuck receipt no longer dead-ends. The wallet still refuses to buy a new credential while one is
+  held — that refusal is what prevents a second charge — but it now names the way out and states
+  plainly that starting over costs the fee a second time.
+
+## [0.11.0] — 17 September 2026
+
+### Added
+
+- **VC pass-design images are now surfaced for basic and verified birthcert issuance.** When the
+  issuer returns a pass-design image alongside a credential, the wallet extracts it, writes it to
+  disk, and — since a remote MCP client has no filesystem access to read a local path back —
+  returns it as an inline image in the tool response too, so the pass is actually visible rather
+  than just referenced by path.
+
+### Fixed
+
+- **The spending-cap blocker now shows human-readable amounts.** It previously showed the raw
+  base-unit number with no symbol or decimal conversion, while the balance/fee blocker in the same
+  response already showed the correctly formatted amount — the cap blocker now matches it.
+
 ## [0.10.0] — 14 September 2026
 
 ### Added

package/README.md

@@ -28,8 +28,9 @@ VC issuance → identity proof → pay-per-use).
 | `create_holder_account` | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns `{ alreadyExists: true, existing }` without creating anything; pass `confirmNew: true` (after asking the user) to mint a new one anyway | `{ password, label?, purpose?, confirmNew? }` | `{ created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message }` |
 | `get_template_schema` | **Free** read of a VC template's declared attribute schema. Call before `subscribe_and_issue` to learn which attributes it requires | `{ templateId }` | `{ templateId, schema: { required, optional } }` or `{ templateId, error }` |
 | `query_contract` | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | `{ contractAddress, method, params? }` | `{ ok: true, result }` or `{ ok: false, error }` |
-| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate. `dryRun: true` quotes instead of paying: it stops after the 402 challenge, pays nothing, creates no session, and returns `{ quote }` — the asset, the amount and which side pays gas. Quote and paid request send byte-identical signed bodies | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun? }` | `{ sessionId, verificationUrl, expiresAt }` or `{ quote: { asset, maxAmountRequired, payTo?, gasModel } }` |
-| `check_ai_birthcert_verification` | **Free.** Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential. While the session is still open it replays the stored `verificationUrl` alongside SSIVC's live `expiresAt` — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes *"where is my link?"* answerable without touching the paid tool. No link is returned once `status` is `"issued"`: the link is spent | (none) | `{ status: "pending" \| "issued" \| "no_session", verificationUrl?, expiresAt?, vcId?, vc?, cacheError? }` |
+| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate. `dryRun: true` quotes instead of paying: it stops after the 402 challenge, pays nothing, creates no session, and returns `{ quote }` — the asset, the amount and which side pays gas. Quote and paid request send byte-identical signed bodies | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun?, discardStuckReceiptAndPayFresh? }` | `{ sessionId, verificationUrl, expiresAt }`, `{ quote: { asset, maxAmountRequired, payTo?, gasModel } }`, or — when the sponsored settlement is still clearing after ~90s — `{ settlementPending: true, paymentReceipt, message }`, which means the payment SUCCEEDED and is in progress, not that it failed. While a stuck receipt is held this tool can only REPLAY it — it never buys a new credential, which is what stops a second charge. `discardStuckReceiptAndPayFresh: "<exact receipt id>"` is the way to start over: it throws that payment away and pays the fee again, refuses a mismatched id (discarding and paying nothing), refuses a receipt that belongs to a live session, and returns `discardedPaymentReceipt` so the lost payment stays traceable |
+| `check_ai_birthcert_verification` | **Free** (never pays). Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential. While the session is still open it replays the stored `verificationUrl` alongside SSIVC's live `expiresAt` — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes *"where is my link?"* answerable without touching the paid tool. No link is returned once `status` is `"issued"`: the link is spent. If a prior payment is still clearing this tool **advances** it — it replays the saved receipt (never a new payment) and returns the live session once it settles, so "check back in a few minutes" genuinely progresses the flow | (none) | `{ status: "pending" \| "issued" \| "no_session" \| "settlement_pending" | "receipt_void", verificationUrl?, expiresAt?, vcId?, vc?, cacheError?, paymentReceipt?, outcomeUnknown?, message? }` — `settlement_pending` means a payment was made and is being followed: without `outcomeUnknown` it is queued and progressing (check again shortly); with `outcomeUnknown: true` the outcome could not be determined at all and has been unresolved longer than `SETTLEMENT_STUCK_AFTER_MS` (24h default), so it is not coming back on its own — `stuckFor` says how long, the fee was most likely already taken, and quoting `paymentReceipt` to support is the way forward. Starting over via `clear_stuck_payment_receipt` costs a second fee. `receipt_void` is terminal and different: SSIVC has ruled the receipt finished (status_code 67 expired / 68 failed), so checking again cannot help — it does NOT mean the fee was refunded, and buying the credential means paying again |
+| `clear_stuck_payment_receipt` | **Free, last resort, destructive.** Discard a stuck Verified AI Birthcert payment receipt the wallet is holding and refusing to pay past — the supported replacement for deleting `<stateDir>/ssivc-session.json` by hand, which a hosted subscriber cannot do. Two steps by construction: with no argument it clears nothing and returns the receipt id plus a warning; clearing requires echoing that exact id back as `confirmReceiptId`, and a mismatch clears nothing. If the settlement completed in between — which is what happens when you follow the advice to call `check_ai_birthcert_verification` first — the receipt now belongs to a **live, paid-for session**, and the id alone no longer clears it: the tool hands back `sessionId` and `verificationUrl` instead, and only `confirmDiscardLiveSession: true` will discard them. The discarded payment is unrecoverable | `{ confirmReceiptId?, confirmDiscardLiveSession? }` | `{ cleared, paymentReceipt?, requiresConfirmation?, sessionId?, verificationUrl?, message?, error? }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
 > (scoped per network + holder — different identities or networks never share a cache).
@@ -183,6 +184,8 @@ Node ≥ 18 required (built-in `fetch`).
 | `AI_BIRTHCERT_VERIFIED_TEMPLATE_ID` | no | The Verified AI Birthcert's on-chain `did:zid:...` template id. Auto-derived per network by default — **the mainnet default is unverified**, so override this explicitly once the mainnet template id is confirmed |
 | `GAS_PREFERENCE` | no | `sponsored` or `self` — the default gas payer for the Verified AI Birthcert flow (`request_ai_birthcert_verification`). **Defaults to `sponsored`; any unrecognised value also falls back to `sponsored`** rather than throwing. Sponsorship only actually engages when the resource server's x402 quote offers a sponsored option (`extra.gasModel: "facilitator"`) — a server that only quotes self-pay behaves unchanged. **Sponsorship is testnet-only today**; override per-call with the tool's `gasPayer` parameter |
 | `MAX_SETTLEMENT_ATTEMPTS` | no | Cap on retry attempts while polling a sponsored payment for settlement after SSIVC returns `202 Accepted` (queued). **Defaults to `20`; a non-positive or unparseable value also falls back to `20`** |
+| `SETTLEMENT_WAIT_BUDGET_MS` | no | Total time `request_ai_birthcert_verification` **and** `check_ai_birthcert_verification` will each wait for a queued settlement before returning `{ settlementPending: true }` / `{ status: "settlement_pending" }` — `check_` advances the settlement too, so it can block for this long. The attempt cap alone cannot bound this, because the delay between attempts is server-supplied. At least one poll always happens, even if the budget is shorter than the first retry delay. Not capped at the top end — raising it *and* `MAX_SETTLEMENT_ATTEMPTS` together can reinstate the long blocking call this budget exists to prevent, so raise it deliberately and temporarily. **Defaults to `90000` (90s); a non-positive or unparseable value also falls back to `90000`** |
+| `SETTLEMENT_STUCK_AFTER_MS` | no | How long a settlement SSIVC cannot confirm may stay unresolved before `check_ai_birthcert_verification` stops calling it "still settling" and calls it permanently stuck. SSIVC returns the same `status_code 69` for a settlement two minutes old and one three weeks old, so the receipt's own age is what separates *"payment sent, check back shortly"* from *"this is not coming back, the fee was most likely already taken, and starting over costs a second fee"*. This changes **only the wording**: either side of the line the wallet never pays again and never discards the receipt by itself. **Defaults to `86400000` (24h); a non-positive or unparseable value also falls back to `86400000`** |
 
 \* sensitive — never logged, never returned in a tool result, and never a tool parameter.