agentic-wallet-mcp 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -8,6 +8,37 @@ 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.9.2] — 3 September 2026
+
+### Fixed
+
+- **`request_ai_birthcert_verification`'s sponsored-payment path no longer surfaces a facilitator
+  insufficient-funds rejection as an opaque, unhandled MCP tool error.** A `461407`
+  (`X402_INSUFFICIENT_FUNDS`) rejection from the facilitator's `/prepare` endpoint is now reshaped
+  into a clean `{ error }` result naming the asset and amount, instead of falling through every
+  error branch and throwing raw.
+- **That message now renders amounts in human units, not raw base units.** A raw base-unit count
+  next to a token symbol (e.g. "requires 1,000,000 of JMYR") reads as a million *whole* tokens —
+  for a 6-decimal asset the actual requirement was 1 JMYR, a 1,000,000x misreading that could lead
+  to a drastically oversized top-up. Amounts are now resolved through the same symbol/decimals
+  formatter the rest of the wallet already uses.
+- **The reported "current balance" is read from the facilitator's structured response field when
+  available**, falling back to parsing it out of the free-text error message only for an
+  older/unfixed facilitator — the free-text format was never a stable contract between the two
+  services.
+
+## [0.9.1] — 28 August 2026
+
+### Fixed
+
+- **`request_ai_birthcert_verification` no longer blocks retrying an expired session.** If the
+  owner never completed MyDigital ID verification before a Verified AI Birthcert session's TTL
+  elapsed (`status: "expired"`), retrying previously threw an "unrecognized prior session status"
+  error and left the flow stuck — even though the settlement receipt was already safely persisted
+  locally and unconsumed. Any confirmed terminal session status other than `"issued"` (the only
+  status that consumes the receipt) is now treated the same as the existing 404/"gone" handling:
+  the receipt is replayed and a fresh verification session is opened, with no new payment made.
+
 ## [0.9.0] — 24 August 2026
 
 ### Added

package/dist/server-bundle.cjs

@@ -12549,7 +12549,7 @@ var import_node_path6 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.9.0",
+  version: "0.9.2",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -23406,13 +23406,14 @@ async function decidePriorSession(deps, agentName) {
   if (stored.agentName !== agentName) {
     const otherStatus = await getConfirmedStatus(deps, stored.sessionId);
     if (otherStatus === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
-    if (otherStatus.status !== "issued") {
+    if (otherStatus.status === "pending") {
       return {
         kind: "blocked",
-        message: `a verification session for a different agent ("${stored.agentName}") is still in progress (status: "${otherStatus.status}") and its payment has not been consumed yet \u2014 starting a new session for "${agentName}" would lose track of it. Call check_ai_birthcert_verification to resolve or confirm it first.`
+        message: `a verification session for a different agent ("${stored.agentName}") is still in progress (status: "pending") and its payment has not been consumed yet \u2014 starting a new session for "${agentName}" would lose track of it. Call check_ai_birthcert_verification to resolve or confirm it first.`
       };
     }
-    return { kind: "pay_fresh" };
+    if (otherStatus.status === "issued") return { kind: "pay_fresh" };
+    return { kind: "replay_receipt", receipt: stored.paymentReceipt };
   }
   const status = await getConfirmedStatus(deps, stored.sessionId);
   if (status === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
@@ -23423,9 +23424,7 @@ async function decidePriorSession(deps, agentName) {
     };
   }
   if (status.status === "issued") return { kind: "pay_fresh" };
-  throw new Error(
-    `requestAiBirthcertVerification: unrecognized prior session status "${status.status}" for session ${stored.sessionId} \u2014 refusing to guess whether its settlement receipt is safe to replay (see SPEC.md D8)`
-  );
+  return { kind: "replay_receipt", receipt: stored.paymentReceipt };
 }
 var requestQueue = Promise.resolve();
 function withRequestLock(fn) {
@@ -23497,6 +23496,7 @@ var DEFINITIVE_PREPARE_REFUSALS = /* @__PURE__ */ new Set([
   461415
   // X402_UNSUPPORTED_ASSET    — sponsorship is ZTP-20 only
 ]);
+var FACILITATOR_INSUFFICIENT_FUNDS_CODE = 461407;
 function facilitatorErrorCode(err) {
   const m = /"errorCode"\s*:\s*(\d{6})/.exec(err instanceof Error ? err.message : String(err));
   return m ? Number(m[1]) : void 0;
@@ -23516,6 +23516,41 @@ function isDefinitiveSponsorshipFailure(err) {
   if (code === void 0) return false;
   return DEFINITIVE_PREPARE_REFUSALS.has(code);
 }
+var FacilitatorInsufficientFundsError = class extends Error {
+  constructor(requiredHuman, availableHuman, rawMessage) {
+    super(
+      `insufficient funds: the sponsored payment requires ${requiredHuman}` + (availableHuman !== void 0 ? ` \u2014 this wallet currently holds ${availableHuman}` : " and this wallet does not hold enough of it") + ` (facilitator: ${rawMessage})`
+    );
+    this.name = "FacilitatorInsufficientFundsError";
+  }
+};
+function extractFacilitatorBalance(rawMessage) {
+  const braceIdx = rawMessage.indexOf("{");
+  if (braceIdx !== -1) {
+    try {
+      const body = JSON.parse(rawMessage.slice(braceIdx));
+      const detail = body.messages?.[0]?.detail;
+      if (Array.isArray(detail) && detail.length >= 3 && detail[2] !== null && detail[2] !== void 0) {
+        return String(detail[2]);
+      }
+    } catch {
+    }
+  }
+  const m = /insufficient_funds \[[^,]+,\s*[^,]+,\s*([^\]]+)\]/.exec(rawMessage);
+  return m ? m[1].trim() : void 0;
+}
+async function toFacilitatorInsufficientFundsError(err, accept, formatAssetAmount) {
+  if (!(err instanceof PrepareStageError)) return err;
+  if (facilitatorErrorCode(err.cause) !== FACILITATOR_INSUFFICIENT_FUNDS_CODE) return err;
+  const asset = accept.asset ?? "";
+  const maxAmountRequired = accept.maxAmountRequired ?? "";
+  if (!asset || !maxAmountRequired) return err;
+  const rawMessage = err.cause instanceof Error ? err.cause.message : String(err.cause);
+  const requiredHuman = formatAssetAmount ? await formatAssetAmount(asset, maxAmountRequired) : `${maxAmountRequired} of asset "${asset}"`;
+  const availableRaw = extractFacilitatorBalance(rawMessage);
+  const availableHuman = availableRaw !== void 0 && formatAssetAmount ? await formatAssetAmount(asset, availableRaw) : availableRaw;
+  return new FacilitatorInsufficientFundsError(requiredHuman, availableHuman, rawMessage);
+}
 async function attemptCandidate(deps, accept, buildBody, onQueued) {
   let xPayment;
   try {
@@ -23535,8 +23570,9 @@ async function payAndCreateSession(deps, buildBody, onQueued) {
     return await attemptCandidate(deps, primary, buildBody, onQueued);
   } catch (err) {
     const fallback = candidates[1];
-    if (!fallback || !isSponsored(primary) || isSponsored(fallback)) throw err;
-    if (!isDefinitiveSponsorshipFailure(err)) throw err;
+    if (!fallback || !isSponsored(primary) || isSponsored(fallback) || !isDefinitiveSponsorshipFailure(err)) {
+      throw await toFacilitatorInsufficientFundsError(err, primary, deps.formatAssetAmount);
+    }
     return await attemptCandidate(deps, fallback, buildBody, onQueued);
   }
 }
@@ -23606,6 +23642,7 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
     if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}` };
     if (err instanceof PaymentCapError) return { error: err.message };
     if (err instanceof NoPaymentOptionsError) return { error: err.message };
+    if (err instanceof FacilitatorInsufficientFundsError) return { error: err.message };
     if (err instanceof SettlementStillQueuedError) {
       try {
         await deps.sessionStore.set({
@@ -24016,7 +24053,8 @@ async function main() {
       cache: vcCache,
       quarantine: downloadQuarantine,
       gasPreference: config2.gasPreference,
-      maxSettlementAttempts: config2.maxSettlementAttempts
+      maxSettlementAttempts: config2.maxSettlementAttempts,
+      formatAssetAmount
     };
     return {
       request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",