agentic-wallet-mcp 0.9.2 → 0.11.0

package/dist/server-bundle.cjs

@@ -12147,7 +12147,7 @@ var require_prepare_client = __commonJS({
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              "User-Agent": "x402-zetrix-js/1.0 (+https://git.myeg.com.my/genesis/x402/x402-zetrix-js)"
+              "User-Agent": "x402-zetrix-js/1.0 (+https://github.com/Zetrix-Chain/x402-zetrix-js)"
             },
             body: JSON.stringify(params),
             signal: controller.signal
@@ -12538,18 +12538,20 @@ var require_dist2 = __commonJS({
 var index_exports = {};
 __export(index_exports, {
   asPayRequest: () => asPayRequest,
+  buildPayers: () => buildPayers,
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto5 = require("node:crypto");
+var import_node_crypto6 = require("node:crypto");
 var import_node_fs = require("node:fs");
+var import_promises6 = require("node:fs/promises");
 var import_node_os2 = require("node:os");
-var import_node_path6 = require("node:path");
+var import_node_path7 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.9.2",
+  version: "0.11.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -12592,7 +12594,7 @@ var package_default = {
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "x401-zetrix-client": "^0.2.1",
-    "x402-zetrix-client": "^0.2.2",
+    "x402-zetrix-client": "^0.2.4",
     "zetrix-sdk-nodejs": "^1.0.3"
   },
   devDependencies: {
@@ -21511,10 +21513,15 @@ var PaymentCapError = class extends Error {
     this.detail = detail;
   }
 };
+function formatCapRefusal(detail, renderRequired = detail.requiredRaw, renderCap = detail.capRaw) {
+  const asset = detail.asset || "(unknown asset)";
+  const base = `payment blocked: this call needs ${renderRequired} of asset "${asset}", but the limit that applies is ${renderCap}`;
+  return detail.matchedKey === detail.asset ? `${base}, set for that asset.` : `${base}. No limit is set for this asset, so the "*" fallback applies \u2014 set a limit keyed by "${asset}" to allow it.`;
+}
 function isNonNegativeIntegerString(v) {
   return /^\d+$/.test(v);
 }
-function parsePaymentCaps(json) {
+function parsePaymentCaps(json, opts = {}) {
   if (json === void 0) return void 0;
   let parsed;
   try {
@@ -21532,12 +21539,43 @@ function parsePaymentCaps(json) {
     }
     caps[asset] = raw;
   }
-  return caps;
+  return opts.resolveSymbol ? expandSymbolKeys(caps, opts.resolveSymbol, opts.onWarn) : caps;
+}
+function expandSymbolKeys(caps, resolveSymbol, onWarn) {
+  const out = {};
+  const pendingSymbols = [];
+  for (const [key, value] of Object.entries(caps)) {
+    const address = key === "*" || key === "ZTX" ? void 0 : resolveSymbol(key);
+    if (address === void 0) out[key] = value;
+    else pendingSymbols.push([key, address, value]);
+  }
+  for (const [symbol, address, value] of pendingSymbols) {
+    if (out[address] !== void 0) continue;
+    out[address] = value;
+    const previous = caps["*"] ?? "0";
+    if (BigInt(value) > BigInt(previous)) {
+      onWarn?.(
+        `MAX_PAYMENT_AMOUNT: the limit written as "${symbol}" now applies to ${address} and permits ${value}. Until this version a ticker matched nothing, so that asset was limited to ${previous}. If you did not intend to allow ${value}, change or remove the "${symbol}" entry.`
+      );
+    }
+  }
+  return out;
+}
+function describePaymentCap(asset, requiredRaw, caps) {
+  if (caps === void 0) return { asset, capRaw: null, matchedKey: null, wouldPass: true };
+  const { capRaw, matchedKey } = resolveCap(asset, caps);
+  if (capRaw === void 0) return { asset, capRaw: null, matchedKey: null, wouldPass: false };
+  const wouldPass = isNonNegativeIntegerString(requiredRaw) && BigInt(requiredRaw) <= BigInt(capRaw);
+  return { asset, capRaw, matchedKey, wouldPass };
+}
+function resolveCap(asset, caps) {
+  const explicit = caps[asset];
+  return explicit !== void 0 ? { capRaw: explicit, matchedKey: asset } : { capRaw: caps["*"], matchedKey: "*" };
 }
 function assertWithinPaymentCap(accept, caps) {
   if (caps === void 0) return;
   const asset = accept.asset ?? "";
-  const capRaw = caps[asset] ?? caps["*"];
+  const { capRaw, matchedKey } = resolveCap(asset, caps);
   if (capRaw === void 0) {
     throw new PaymentCapError(`payment blocked: no MAX_PAYMENT_AMOUNT entry for asset "${asset}" and no "*" fallback configured`);
   }
@@ -21548,10 +21586,13 @@ function assertWithinPaymentCap(accept, caps) {
   const required2 = BigInt(requiredRaw);
   const cap = BigInt(capRaw);
   if (required2 > cap) {
-    throw new PaymentCapError(
-      `payment blocked: requested ${required2} ${asset || "(unknown asset)"} exceeds configured MAX_PAYMENT_AMOUNT ${cap}`,
-      { asset, requiredRaw: required2.toString(), capRaw: cap.toString() }
-    );
+    const detail = {
+      asset,
+      requiredRaw: required2.toString(),
+      capRaw: cap.toString(),
+      matchedKey
+    };
+    throw new PaymentCapError(formatCapRefusal(detail), detail);
   }
 }
 
@@ -21583,10 +21624,22 @@ function deriveAiBirthcertVerifiedTemplateId(network) {
 var TOKEN_REGISTRY = {
   JMYR: { testnet: "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b", mainnet: "ZTX3NCkXBqbyJWjZZxciQez945Lu6tGAcjNJr" }
 };
+function defaultPaymentCaps(network) {
+  const jmyr = resolveTokenAddress("JMYR", network);
+  return isTestnet(network) && jmyr ? { [jmyr]: "1000000", "*": "0" } : { "*": "0" };
+}
+function defaultCredentialIssuanceCaps(network) {
+  const jmyr = resolveTokenAddress("JMYR", network);
+  return jmyr ? { [jmyr]: "1000000", "*": "0" } : { "*": "0" };
+}
+var KNOWN_NETWORKS = ["zetrix:testnet", "zetrix:mainnet"];
+function isTestnet(network) {
+  return network.includes("testnet");
+}
 function resolveTokenAddress(symbol, network) {
   const entry = TOKEN_REGISTRY[symbol.toUpperCase()];
   if (!entry) return void 0;
-  return network.includes("testnet") ? entry.testnet : entry.mainnet;
+  return isTestnet(network) ? entry.testnet : entry.mainnet;
 }
 function loadConfig(env) {
   const req = (key, hint) => {
@@ -21599,7 +21652,17 @@ function loadConfig(env) {
     return v && v.trim() ? v.trim() : void 0;
   };
   const network = opt("ZETRIX_NETWORK") ?? "zetrix:testnet";
+  if (!KNOWN_NETWORKS.includes(network)) {
+    throw new Error(
+      `agentic-wallet-mcp: unrecognised ZETRIX_NETWORK "${network}" \u2014 expected one of ${KNOWN_NETWORKS.join(", ")}. Values are matched exactly and are case-sensitive; anything unrecognised would otherwise resolve to MAINNET addresses and grant a real spending allowance.`
+    );
+  }
   const oid4vpBaseUrlOverride = opt("OID4VP_BASE_URL");
+  const explicitCaps = parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT"), {
+    resolveSymbol: (symbol) => resolveTokenAddress(symbol, network),
+    onWarn: (message) => process.stderr.write(`agentic-wallet-mcp: ${message}
+`)
+  });
   return {
     walletBeUrl: stripTrailingSlash(opt("WALLET_BE_URL") ?? deriveWalletBeUrl(network)),
     oid4vpBaseUrl: oid4vpBaseUrlOverride ? stripTrailingSlash(oid4vpBaseUrlOverride) : void 0,
@@ -21619,7 +21682,11 @@ function loadConfig(env) {
     // Fail closed: an unset cap means "spend nothing", not "spend anything". A wallet that starts
     // with no configuration at all must not be able to auto-pay a hostile x402 challenge. Raising
     // it is a deliberate act.
-    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT")) ?? { "*": "0" },
+    //
+    // An explicit MAX_PAYMENT_AMOUNT governs BOTH caps below — a user who sets a limit means it
+    // everywhere. Only the defaults differ, and only because the two surfaces carry different risk.
+    maxPaymentAmount: explicitCaps ?? defaultPaymentCaps(network),
+    credentialIssuanceCaps: explicitCaps ?? defaultCredentialIssuanceCaps(network),
     ssivcBaseUrl: (() => {
       const v = opt("SSIVC_BASE_URL") ?? deriveSsivcBaseUrl(network);
       return v ? stripTrailingSlash(v) : void 0;
@@ -21738,27 +21805,42 @@ async function fetchZTP20BalanceStrict(contractAddress, address, query) {
   if (typeof balance !== "string") {
     throw new Error("balanceOf returned no balance field");
   }
+  if (!/^\d+$/.test(balance)) {
+    throw new Error(`balanceOf returned a non-numeric balance: ${JSON.stringify(balance)}`);
+  }
   return balance;
 }
+function looksLikeContractAddress(token) {
+  return /^ZTX[0-9A-Za-z]{30,}$/.test(token);
+}
 async function queryTokenBalance(deps, token) {
   const symbol = token.toUpperCase();
   if (symbol === "ZTX") {
     try {
-      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS2 };
+      const balance2 = await deps.fetchNativeBalance(deps.address);
+      return { token: symbol, balance: balance2, decimals: ZTX_DECIMALS2, display: renderDisplay(balance2, ZTX_DECIMALS2, symbol) };
     } catch {
       return { token: symbol, error: "query_failed" };
     }
   }
-  const contractAddress = deps.resolveTokenAddress(symbol);
+  const registered = deps.resolveTokenAddress(symbol);
+  const byAddress = registered === null && looksLikeContractAddress(token);
+  const contractAddress = registered ?? (byAddress ? token : null);
   if (!contractAddress) return { token: symbol, error: "unknown_token" };
+  const asked = byAddress ? token : symbol;
   let balance;
   try {
     balance = await fetchZTP20BalanceStrict(contractAddress, deps.address, deps.query);
   } catch {
-    return { token: symbol, error: "query_failed" };
+    return { token: asked, error: "query_failed" };
   }
   const info = await fetchTokenInfo(contractAddress, deps.query);
-  return { token: symbol, balance, decimals: info?.decimals ?? null };
+  const label = byAddress ? info?.symbol ?? asked : symbol;
+  const decimals = info?.decimals ?? null;
+  return { token: label, balance, decimals, display: renderDisplay(balance, decimals, label) };
+}
+function renderDisplay(raw, decimals, label) {
+  return `${decimals === null ? raw : formatHumanAmount(raw, decimals)} ${label}`;
 }
 
 // src/clients/template-info-client.ts
@@ -22032,6 +22114,24 @@ var MbiClient = class _MbiClient {
     if (!res.ok) throw await this.error(res, "apply (phase 2) failed");
     return this.unwrap(res);
   }
+  /**
+   * POST /v1/vc/pay/quote — the price for a template, with no issuance and no payment record.
+   *
+   * Unlike `applyChallenge`, this cannot mint anything: MBI resolves the template, builds the
+   * canonical sign payload, and reads its configured price. Notably a FREE template does not
+   * short-circuit into synchronous issuance here, which is what makes this safe to call purely to
+   * find out a cost — `applyChallenge` is not (see its docstring).
+   *
+   * `data` is required to be non-empty by MBI's DTO but does not affect the price, which comes from
+   * MBI's own asset config keyed by the resolved template. A caller pricing a credential before it
+   * has collected any attribute therefore passes a throwaway value, and must not present it as
+   * anything the user supplied.
+   */
+  async quote(templateId, data) {
+    const res = await this.fetch("POST", "/v1/vc/pay/quote", { templateId, data });
+    if (!res.ok) throw await this.error(res, "quote failed");
+    return this.unwrap(res);
+  }
   /** Idempotent recovery — GET /v1/vc/pay/status/{paymentId}. */
   async getStatus(paymentId) {
     const res = await this.fetch("GET", `/v1/vc/pay/status/${encodeURIComponent(paymentId)}`);
@@ -22169,6 +22269,43 @@ function payAndFetch(payer, req) {
   return payer(req);
 }
 
+// src/accept-selection.ts
+function extraOf(accept) {
+  const extra = accept.extra;
+  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return {};
+  return extra;
+}
+function assetOf(accept) {
+  return String(accept.asset ?? "");
+}
+function declaresFacilitator(accept) {
+  return extraOf(accept).gasModel === "facilitator";
+}
+function isSponsored(accept) {
+  if (!declaresFacilitator(accept)) return false;
+  const prepareEndpoint = extraOf(accept).prepareEndpoint;
+  if (typeof prepareEndpoint !== "string" || prepareEndpoint === "") return false;
+  const asset = assetOf(accept);
+  return asset !== "" && asset !== "ZTX";
+}
+function isUnusable(accept) {
+  return declaresFacilitator(accept) && !isSponsored(accept);
+}
+function orderAccepts(accepts, prefer) {
+  const usable = accepts.filter((a) => !isUnusable(a));
+  const sponsored = usable.filter(isSponsored);
+  const selfPay = usable.filter((a) => !isSponsored(a));
+  return prefer === "sponsored" ? [...sponsored, ...selfPay] : [...selfPay, ...sponsored];
+}
+function prepareBaseUrl(prepareEndpoint) {
+  return prepareEndpoint.replace(/\/+$/, "").replace(/\/prepare$/, "");
+}
+function needsNativeGasCheck(accept) {
+  const asset = String(accept.asset ?? "");
+  if (asset === "" || asset === "ZTX") return false;
+  return !isSponsored(accept);
+}
+
 // src/zetrix-hex.ts
 function zetrixHexStringToBytes(s) {
   const up = s.toUpperCase();
@@ -22293,6 +22430,31 @@ async function payWithReadinessCheck(requestedAsset, rawPay, activated) {
   }
 }
 
+// src/clients/vc-pass-image.ts
+var import_node_crypto2 = require("node:crypto");
+var import_promises2 = require("node:fs/promises");
+var import_node_path3 = require("node:path");
+var MAX_PASS_IMAGE_PAGES = 10;
+var MAX_PASS_IMAGE_BASE64_LENGTH = 8e6;
+function extractVcPassBase64(extraData) {
+  if (typeof extraData !== "object" || extraData === null) return void 0;
+  const raw = extraData.vcPassBase64;
+  if (!Array.isArray(raw)) return void 0;
+  const strings = raw.filter((v) => typeof v === "string" && v.length > 0 && v.length <= MAX_PASS_IMAGE_BASE64_LENGTH).slice(0, MAX_PASS_IMAGE_PAGES);
+  return strings.length > 0 ? strings : void 0;
+}
+async function writeVcPassImages(baseDir, vcId, base64Images) {
+  await (0, import_promises2.mkdir)(baseDir, { recursive: true });
+  const hash = (0, import_node_crypto2.createHash)("sha256").update(vcId).digest("hex");
+  const paths = [];
+  for (let i = 0; i < base64Images.length; i++) {
+    const filePath = (0, import_node_path3.join)(baseDir, `${hash}-${i}.png`);
+    await (0, import_promises2.writeFile)(filePath, Buffer.from(base64Images[i], "base64"));
+    paths.push(filePath);
+  }
+  return paths;
+}
+
 // src/orchestrator/subscribe.ts
 function diffAgainstTemplate(vc, fields) {
   const held = new Set(extractAttributeKeys(vc));
@@ -22322,6 +22484,36 @@ async function pollSettlementOutcome(deps, paymentId) {
   }
   return { ...last, polls: RECOVERY_MAX_POLLS };
 }
+async function resolveVcPassImagePaths(deps, vcId) {
+  const downloadVcs = deps.mbi.downloadVcs;
+  const auth = deps.auth;
+  const address = deps.address;
+  const quarantine = deps.quarantine;
+  const passImagesDir = deps.passImagesDir;
+  if (!downloadVcs || !auth || !address || !quarantine || !passImagesDir) return void 0;
+  try {
+    const entries = await quarantine.withLock(vcId, async () => {
+      const quarantined = await quarantine.get(vcId);
+      if (quarantined) return quarantined.entries;
+      let downloaded;
+      try {
+        downloaded = await downloadVcs({ address }, await auth());
+      } catch {
+        return void 0;
+      }
+      await quarantine.set({ vcId, entries: downloaded, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      return downloaded;
+    });
+    if (!entries) return void 0;
+    const match = entries.find((e) => typeof e.vc === "object" && e.vc !== null && e.vc.id === vcId);
+    if (!match) return void 0;
+    const base64Images = extractVcPassBase64(match.extraData);
+    if (!base64Images) return void 0;
+    return await writeVcPassImages(passImagesDir, vcId, base64Images);
+  } catch {
+    return void 0;
+  }
+}
 async function subscribeAndIssue(deps, opts) {
   if (!/^did:zid:/.test(opts.templateId)) {
     return { issued: false, reason: `templateId must be a did:zid:... credential-definition id, got "${opts.templateId}"` };
@@ -22359,7 +22551,48 @@ async function subscribeAndIssue(deps, opts) {
       };
     }
   }
-  const data = JSON.stringify([{ templateId: opts.templateId, metadata: attributes }]);
+  if (opts.dryRun) {
+    if (!deps.mbi.quote) {
+      return {
+        issued: false,
+        reason: "dry run unavailable \u2014 this wallet has no MBI quote client, and pricing any other way risks issuing the credential",
+        ...schema ? { schema } : {}
+      };
+    }
+    let quoted;
+    try {
+      quoted = await deps.mbi.quote(opts.templateId, attributes);
+    } catch (err) {
+      if (err instanceof MbiError) {
+        return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+      }
+      throw err;
+    }
+    const quotedAccept = quoted.accepts?.[0];
+    if (!quotedAccept) {
+      return { issued: false, reason: "MBI quoted no payment options", ...schema ? { schema } : {} };
+    }
+    const quotedRaw = String(quotedAccept.asset ?? "");
+    const quotedAsset = deps.resolveSymbol ? await deps.resolveSymbol(quotedRaw) : quotedRaw;
+    const reason = quoted.paymentRequired === false ? "dry run \u2014 issuance is free right now, no payment required" : quoted.paymentRequired === true ? "dry run \u2014 quoted only, no payment made" : "dry run \u2014 quoted only, no payment made. This MBI does not report whether issuance is free, so the quoted amount may not actually be charged.";
+    return {
+      issued: false,
+      reason,
+      quote: {
+        asset: quotedAsset,
+        maxAmountRequired: quotedAccept.maxAmountRequired,
+        payTo: quotedAccept.payTo,
+        // credential_preflight reads a missing gasModel as self-pay (preflight.ts), so a
+        // sponsored template credential must say so explicitly rather than fall through as absent.
+        gasModel: isSponsored(quotedAccept) ? "sponsored" : "self",
+        ...quoted.paymentRequired === void 0 ? {} : { paymentRequired: quoted.paymentRequired }
+      },
+      ...schema ? { schema } : {}
+    };
+  }
+  const data = JSON.stringify([
+    deps.passDesignId ? { templateId: opts.templateId, passDesignId: deps.passDesignId, metadata: attributes } : { templateId: opts.templateId, metadata: attributes }
+  ]);
   const blob = zetrixHexStringToBytes(data).toString("hex");
   const { signBlob: signData, publicKey } = await deps.sign(blob);
   const body = { data, signData, publicKey };
@@ -22375,6 +22608,7 @@ async function subscribeAndIssue(deps, opts) {
   }
   if (challenge.issued) {
     const issued2 = challenge.issued;
+    const vcPassImagePaths2 = issued2.vcId ? await resolveVcPassImagePaths(deps, issued2.vcId) : void 0;
     if (deps.cache) {
       await deps.cache.set(opts.templateId, {
         templateId: opts.templateId,
@@ -22384,7 +22618,8 @@ async function subscribeAndIssue(deps, opts) {
         paidAsset: "none",
         amountPaid: "0",
         issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        validUntil: extractValidUntil(issued2.verifiableCredential, opts.expirationDate)
+        validUntil: extractValidUntil(issued2.verifiableCredential, opts.expirationDate),
+        ...vcPassImagePaths2 ? { vcPassImagePaths: vcPassImagePaths2 } : {}
       });
     }
     return {
@@ -22395,25 +22630,11 @@ async function subscribeAndIssue(deps, opts) {
       paidAsset: "none",
       amountPaid: "0",
       ...schema ? { schema } : {},
-      ...opts.dryRun ? { reason: "this template requires no payment \u2014 MBI issues synchronously at phase 1, so dryRun could not prevent this issuance" } : {}
+      ...vcPassImagePaths2 ? { vcPassImagePaths: vcPassImagePaths2 } : {}
     };
   }
   const accept = challenge.accepts[0];
   if (!accept) return { issued: false, reason: "MBI 402 returned no payment options", ...schema ? { schema } : {} };
-  if (opts.dryRun) {
-    const quotedRaw = String(accept.asset ?? "");
-    const quotedAsset = deps.resolveSymbol ? await deps.resolveSymbol(quotedRaw) : quotedRaw;
-    return {
-      issued: false,
-      reason: "dry run \u2014 quoted only, no payment made",
-      quote: {
-        asset: quotedAsset,
-        maxAmountRequired: accept.maxAmountRequired,
-        payTo: accept.payTo
-      },
-      ...schema ? { schema } : {}
-    };
-  }
   let xPayment;
   try {
     xPayment = await deps.pay(accept);
@@ -22444,6 +22665,7 @@ async function subscribeAndIssue(deps, opts) {
     }
     throw err;
   }
+  const vcPassImagePaths = issued.vcId ? await resolveVcPassImagePaths(deps, issued.vcId) : void 0;
   if (deps.cache) {
     await deps.cache.set(opts.templateId, {
       templateId: opts.templateId,
@@ -22453,7 +22675,8 @@ async function subscribeAndIssue(deps, opts) {
       paidAsset,
       amountPaid,
       issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      validUntil: extractValidUntil(issued.verifiableCredential, opts.expirationDate)
+      validUntil: extractValidUntil(issued.verifiableCredential, opts.expirationDate),
+      ...vcPassImagePaths ? { vcPassImagePaths } : {}
     });
   }
   return {
@@ -22463,7 +22686,8 @@ async function subscribeAndIssue(deps, opts) {
     txHash: issued.txHash,
     paidAsset,
     amountPaid,
-    ...schema ? { schema } : {}
+    ...schema ? { schema } : {},
+    ...vcPassImagePaths ? { vcPassImagePaths } : {}
   };
 }
 
@@ -22826,7 +23050,11 @@ var TEMPLATE_ALIASES = [
     testnet: "did:zid:3c0fb79adff08e14e06dcd6e3243205010dd65f533434a3d96c55575d1d3d959",
     mainnet: "did:zid:19091d19049abb8869b4b8e2f4a887bd1d1d86e5f5ebd0c8297000255f67765b",
     deriveAttributes: { id: "agentUsername" },
-    validateAttributes: { dob: validateDob, countryOfOrigin: validateCountryOfOrigin }
+    validateAttributes: { dob: validateDob, countryOfOrigin: validateCountryOfOrigin },
+    passDesignId: {
+      testnet: "did:zid:992e1e18985ba36a09ba0fbfeb601ddeb449f5e4e882ed69d0d620085f399818",
+      mainnet: "did:zid:915955cb71c6fd2a256d04344f57381084903cb6a85a1c9ddb71c746f08932ab"
+    }
   }
 ];
 function normalize2(s) {
@@ -22873,6 +23101,109 @@ function validateTemplateAttributes(templateId, network, attributes) {
   }
   return errors;
 }
+function resolvePassDesignId(templateId, network) {
+  const entry = findEntry(templateId, network);
+  if (!entry?.passDesignId) return void 0;
+  return network.includes("testnet") ? entry.passDesignId.testnet : entry.passDesignId.mainnet;
+}
+
+// src/orchestrator/preflight.ts
+var VERIFIED_AI_BIRTHCERT = "verified_ai_birthcert";
+var NATIVE = "ZTX";
+function placeholderAgentName() {
+  return `preflight-quote-only-${Date.now()}`;
+}
+async function credentialPreflight(deps, input) {
+  const blockers = [];
+  const notChecked = [];
+  const isVerified = input.credential === VERIFIED_AI_BIRTHCERT;
+  const quoted = isVerified ? await deps.quoteVerified({ agentName: input.agentName?.trim() || placeholderAgentName(), dryRun: true }) : await deps.quoteTemplate(input.credential);
+  const quote = quoted.quote;
+  const schema = quoted.schema;
+  if (!quote) {
+    const why = String(quoted.error ?? quoted.reason ?? "the price could not be read");
+    return {
+      credential: input.credential,
+      ready: false,
+      balances: [],
+      ...schema ? { schema } : {},
+      blockers: [`Could not price this credential: ${why}`],
+      notChecked: uncheckable(isVerified)
+    };
+  }
+  const asset = String(quote.asset ?? "");
+  const requiredRaw = String(quote.maxAmountRequired ?? "0");
+  const gasModel = quote.gasModel === "sponsored" || quote.gasModel === "self" ? quote.gasModel : void 0;
+  const selfPaysGas = gasModel !== "sponsored";
+  const wanted = asset === NATIVE || !selfPaysGas ? [asset] : [asset, NATIVE];
+  const balances = await Promise.all(wanted.map((token) => deps.queryTokenBalance(token)));
+  const isFree = quote.paymentRequired === false;
+  const feeBalance = balances[0];
+  if ("error" in feeBalance) {
+    blockers.push(`Could not read the ${asset} balance (${feeBalance.error}) \u2014 retry before paying.`);
+  } else if (!isFree && BigInt(feeBalance.balance) < BigInt(requiredRaw)) {
+    blockers.push(`Not enough ${feeBalance.token}: the fee is ${renderAmount(requiredRaw, feeBalance)}, the balance is ${feeBalance.display}.`);
+  }
+  if (selfPaysGas && asset !== NATIVE) {
+    const gas = balances[1];
+    if (gas && "error" in gas) {
+      blockers.push(`Could not read the ZTX balance (${gas.error}) \u2014 ZTX pays network gas and is separate from the fee.`);
+    } else if (gas && BigInt(gas.balance) === 0n) {
+      blockers.push(`No ZTX for network gas. ZTX is separate from the ${feeBalance.token ?? asset} fee and is needed for every transaction.`);
+    }
+  }
+  const cap = describePaymentCap(asset, requiredRaw, deps.caps);
+  if (!cap.wouldPass && !isFree) blockers.push(renderCapBlocker(cap, requiredRaw, feeBalance));
+  return {
+    credential: input.credential,
+    ready: blockers.length === 0,
+    fee: {
+      asset,
+      maxAmountRequired: requiredRaw,
+      ...quote.payTo ? { payTo: String(quote.payTo) } : {},
+      ...gasModel ? { gasModel } : {},
+      ..."error" in feeBalance ? {} : { display: renderAmount(requiredRaw, feeBalance) },
+      ...quote.paymentRequired === void 0 ? {} : { paymentRequired: quote.paymentRequired }
+    },
+    balances,
+    cap,
+    ...schema ? { schema } : {},
+    blockers,
+    notChecked: uncheckable(isVerified, isFree)
+  };
+}
+function renderAmount(raw, balance) {
+  if ("error" in balance || balance.decimals === null) return raw;
+  const d = BigInt(10) ** BigInt(balance.decimals);
+  const whole = BigInt(raw) / d;
+  const frac = (BigInt(raw) % d).toString().padStart(balance.decimals, "0").replace(/0+$/, "");
+  return `${whole}${frac ? `.${frac}` : ""} ${balance.token}`;
+}
+function renderCapBlocker(cap, requiredRaw, feeBalance) {
+  const requiredHuman = renderAmount(requiredRaw, feeBalance);
+  if (cap.capRaw === null) {
+    return `No spending limit applies to ${cap.asset}, and limits are configured \u2014 so this payment would be refused. Set a limit keyed by "${cap.asset}".`;
+  }
+  const capHuman = renderAmount(cap.capRaw, feeBalance);
+  const misKeyed = cap.matchedKey !== cap.asset;
+  return misKeyed ? `The spending limit that applies is ${capHuman} (from the "*" fallback \u2014 no limit is set for ${cap.asset}), and this needs ${requiredHuman}.` : `The spending limit for ${cap.asset} is ${capHuman}, and this needs ${requiredHuman}.`;
+}
+function uncheckable(isVerified, isFree = false) {
+  const items = [
+    "Whether the wallet address is activated on chain \u2014 a never-funded address fails differently from a low balance."
+  ];
+  if (isVerified) {
+    items.unshift(
+      "Whether the agent name is still free. myid checks uniqueness at issuance, not now, so a name in use still prices normally and is only refused after payment."
+    );
+  }
+  if (isFree) {
+    items.unshift(
+      "Whether issuance is still free at apply time \u2014 `paymentRequired` is a service-wide MBI setting and can change between this quote and issuance."
+    );
+  }
+  return items;
+}
 
 // src/mcp-tools.ts
 async function loadValidCachedCredentials(cache) {
@@ -22882,10 +23213,15 @@ async function loadValidCachedCredentials(cache) {
 }
 var AI_BIRTHCERT_NOT_CONFIGURED_ERROR = "AI Birthcert verification is not configured on this wallet. On mainnet this is expected until SSIVC_BASE_URL is set explicitly (the mainnet host was never confirmed reachable \u2014 APP-M04); on testnet it means verifyAiBirthcert was not wired at all.";
 function createTools(deps) {
-  return {
+  const tools = {
     async wallet_status(input = {}) {
       const balances = deps.getBalances ? await deps.getBalances() : void 0;
       const tokenBalance = input.token && deps.queryTokenBalance ? await deps.queryTokenBalance(input.token) : void 0;
+      let tokenBalances;
+      if (input.tokens?.length && deps.queryTokenBalance) {
+        tokenBalances = [];
+        for (const t of input.tokens) tokenBalances.push(await deps.queryTokenBalance(t));
+      }
       const credentials = input.heldCredentials ?? (await loadValidCachedCredentials(deps.cache)).map((entry) => entry.vc);
       return {
         holderDid: deps.config.holderDid,
@@ -22893,7 +23229,8 @@ function createTools(deps) {
         network: deps.config.network,
         credentials,
         ...balances !== void 0 ? { balances } : {},
-        ...tokenBalance !== void 0 ? { tokenBalance } : {}
+        ...tokenBalance !== void 0 ? { tokenBalance } : {},
+        ...tokenBalances !== void 0 ? { tokenBalances } : {}
       };
     },
     async prove_identity(input) {
@@ -22927,7 +23264,11 @@ function createTools(deps) {
       if (errors.length > 0) {
         return { issued: false, reason: errors.join("; ") };
       }
-      const result = await subscribeAndIssue(deps.subscribeDeps, { ...input, templateId, attributes });
+      const passDesignId = resolvePassDesignId(templateId, deps.config.network);
+      const result = await subscribeAndIssue(
+        { ...deps.subscribeDeps, passDesignId },
+        { ...input, templateId, attributes }
+      );
       if (!result.schema) return result;
       const hidden = /* @__PURE__ */ new Set(["agentDid", ...derivedAttributeKeys(templateId, deps.config.network)]);
       return {
@@ -22990,6 +23331,38 @@ function createTools(deps) {
       }
       return deps.verifyAiBirthcert.request(input);
     },
+    /**
+     * One read-only answer to "can this wallet buy this, and what does it cost?", before any
+     * application field is collected. Composes the free pieces that already exist — a phase-1 quote,
+     * balances, the spending cap — into a single verdict, so the balance and the cap stop being two
+     * sequential dead ends.
+     */
+    async credential_preflight(input) {
+      if (input.credential === VERIFIED_AI_BIRTHCERT && !deps.verifyAiBirthcert) {
+        return { credential: input.credential, ready: false, balances: [], blockers: [AI_BIRTHCERT_NOT_CONFIGURED_ERROR], notChecked: [] };
+      }
+      if (!deps.queryTokenBalance) {
+        return {
+          credential: input.credential,
+          ready: false,
+          balances: [],
+          blockers: ["This wallet cannot read balances, so readiness cannot be confirmed."],
+          notChecked: []
+        };
+      }
+      return credentialPreflight(
+        {
+          quoteVerified: (q) => deps.verifyAiBirthcert.request(q),
+          quoteTemplate: async (templateId) => {
+            const resolved = resolveTemplateAlias(templateId, deps.config.network) ?? templateId;
+            return priceTemplate(deps, tools, resolved);
+          },
+          queryTokenBalance: deps.queryTokenBalance,
+          caps: deps.paymentCaps
+        },
+        input
+      );
+    },
     check_ai_birthcert_verification() {
       if (!deps.verifyAiBirthcert) {
         return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
@@ -22997,6 +23370,42 @@ function createTools(deps) {
       return deps.verifyAiBirthcert.check();
     }
   };
+  return tools;
+}
+async function priceTemplate(deps, tools, templateId) {
+  const schemaResult = await tools.get_template_schema({ templateId });
+  const schema = schemaResult.schema;
+  if (!schema && schemaResult.error) {
+    return { reason: schemaResult.error };
+  }
+  const quoteFn = deps.subscribeDeps.mbi.quote;
+  if (!quoteFn) {
+    return { reason: "this wallet cannot price template credentials (MBI quote unavailable)", ...schema ? { schema } : {} };
+  }
+  let accepts;
+  let paymentRequired;
+  try {
+    ;
+    ({ accepts, paymentRequired } = await quoteFn.call(deps.subscribeDeps.mbi, templateId, { preflight: "quote-only" }));
+  } catch (err) {
+    return { reason: err.message, ...schema ? { schema } : {} };
+  }
+  const accept = accepts?.[0];
+  if (!accept) return { reason: "MBI quoted no payment options for this template", ...schema ? { schema } : {} };
+  return {
+    quote: {
+      asset: accept.asset,
+      maxAmountRequired: accept.maxAmountRequired,
+      payTo: accept.payTo,
+      // Stated either way: preflight reads a missing gasModel as self-pay, so silence here would be
+      // indistinguishable from a deliberate "you pay the gas".
+      gasModel: isSponsored(accept) ? "sponsored" : "self",
+      // Carried through: this is the only thing in the response that
+      // says whether `maxAmountRequired` will actually be charged, and preflight gates on it.
+      ...paymentRequired === void 0 ? {} : { paymentRequired }
+    },
+    ...schema ? { schema } : {}
+  };
 }
 
 // src/orchestrator/resolve-holder.ts
@@ -23058,12 +23467,12 @@ function configPathFrom(argv) {
   if (!path || path.startsWith("--")) throw new Error("agentic-wallet-mcp: --config requires a file path");
   return path;
 }
-function loadConfigFileEnv(argv, readFile5) {
+function loadConfigFileEnv(argv, readFile6) {
   const path = configPathFrom(argv);
   if (path === null) return {};
   let raw;
   try {
-    raw = readFile5(path);
+    raw = readFile6(path);
   } catch (e) {
     throw new Error(`agentic-wallet-mcp: cannot read config file ${path}: ${e.message}`);
   }
@@ -23095,9 +23504,9 @@ function loadConfigFileEnv(argv, readFile5) {
 }
 
 // src/hsm-password.ts
-var import_node_crypto2 = require("node:crypto");
+var import_node_crypto3 = require("node:crypto");
 function generateHsmPassword() {
-  return (0, import_node_crypto2.randomBytes)(24).toString("base64url");
+  return (0, import_node_crypto3.randomBytes)(24).toString("base64url");
 }
 
 // src/export-credentials.ts
@@ -23134,8 +23543,8 @@ permanently inaccessible.
 }
 
 // src/clients/account-store.ts
-var import_promises2 = require("node:fs/promises");
-var import_node_path3 = require("node:path");
+var import_promises3 = require("node:fs/promises");
+var import_node_path4 = require("node:path");
 function isStoredAccountShape(value) {
   return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
 }
@@ -23143,7 +23552,7 @@ function createFsAccountStore(filePath) {
   return {
     async get() {
       try {
-        const raw = await (0, import_promises2.readFile)(filePath, "utf8");
+        const raw = await (0, import_promises3.readFile)(filePath, "utf8");
         const parsed = JSON.parse(raw);
         return isStoredAccountShape(parsed) ? parsed : null;
       } catch {
@@ -23151,12 +23560,31 @@ function createFsAccountStore(filePath) {
       }
     },
     async set(account) {
-      await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(filePath), { recursive: true, mode: 448 });
-      await (0, import_promises2.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises3.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
     }
   };
 }
 
+// src/tool-result.ts
+function extractVcPassImagePaths(result) {
+  if (typeof result !== "object" || result === null) return [];
+  const paths = result.vcPassImagePaths;
+  if (!Array.isArray(paths)) return [];
+  return paths.filter((p) => typeof p === "string");
+}
+async function buildToolContent(result, readFile6) {
+  const blocks = [{ type: "text", text: JSON.stringify(result) }];
+  for (const path of extractVcPassImagePaths(result)) {
+    try {
+      const data = await readFile6(path);
+      blocks.push({ type: "image", data: data.toString("base64"), mimeType: "image/png" });
+    } catch {
+    }
+  }
+  return blocks;
+}
+
 // src/clients/ssivc-client.ts
 var SsivcError = class extends Error {
   httpStatus;
@@ -23259,8 +23687,8 @@ var SsivcClient = class {
 };
 
 // src/clients/ssivc-session-store.ts
-var import_promises3 = require("node:fs/promises");
-var import_node_path4 = require("node:path");
+var import_promises4 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
 function isStoredSessionShape(value) {
   if (typeof value !== "object" || value === null) return false;
   const v = value;
@@ -23270,7 +23698,7 @@ function createFsSsivcSessionStore(filePath) {
   return {
     async get() {
       try {
-        const raw = await (0, import_promises3.readFile)(filePath, "utf8");
+        const raw = await (0, import_promises4.readFile)(filePath, "utf8");
         const parsed = JSON.parse(raw);
         return isStoredSessionShape(parsed) ? parsed : null;
       } catch {
@@ -23278,20 +23706,20 @@ function createFsSsivcSessionStore(filePath) {
       }
     },
     async set(session) {
-      await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(filePath), { recursive: true, mode: 448 });
       const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-      await (0, import_promises3.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
-      await (0, import_promises3.rename)(tmpPath, filePath);
+      await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises4.rename)(tmpPath, filePath);
     }
   };
 }
 
 // src/clients/ssivc-download-quarantine-store.ts
-var import_node_crypto3 = require("node:crypto");
-var import_promises4 = require("node:fs/promises");
-var import_node_path5 = require("node:path");
+var import_node_crypto4 = require("node:crypto");
+var import_promises5 = require("node:fs/promises");
+var import_node_path6 = require("node:path");
 function quarantineFileName(vcId) {
-  return `${(0, import_node_crypto3.createHash)("sha256").update(vcId).digest("hex")}.json`;
+  return `${(0, import_node_crypto4.createHash)("sha256").update(vcId).digest("hex")}.json`;
 }
 function isQuarantinedDownloadShape(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -23299,12 +23727,22 @@ function isQuarantinedDownloadShape(value) {
   return typeof v.vcId === "string" && "entries" in v && typeof v.downloadedAt === "string";
 }
 function createFsDownloadQuarantineStore(baseDir) {
-  const pathFor = (vcId) => (0, import_node_path5.join)(baseDir, quarantineFileName(vcId));
+  const pathFor = (vcId) => (0, import_node_path6.join)(baseDir, quarantineFileName(vcId));
+  const locks = /* @__PURE__ */ new Map();
   return {
     filePathFor: pathFor,
+    withLock(vcId, fn) {
+      const previous = locks.get(vcId) ?? Promise.resolve();
+      const next = previous.then(fn, fn);
+      locks.set(
+        vcId,
+        next.catch(() => void 0)
+      );
+      return next;
+    },
     async get(vcId) {
       try {
-        const raw = await (0, import_promises4.readFile)(pathFor(vcId), "utf8");
+        const raw = await (0, import_promises5.readFile)(pathFor(vcId), "utf8");
         const parsed = JSON.parse(raw);
         return isQuarantinedDownloadShape(parsed) ? parsed : null;
       } catch {
@@ -23312,17 +23750,17 @@ function createFsDownloadQuarantineStore(baseDir) {
       }
     },
     async set(entry) {
-      await (0, import_promises4.mkdir)(baseDir, { recursive: true, mode: 448 });
+      await (0, import_promises5.mkdir)(baseDir, { recursive: true, mode: 448 });
       const filePath = pathFor(entry.vcId);
       const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-      await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 384 });
-      await (0, import_promises4.rename)(tmpPath, filePath);
+      await (0, import_promises5.writeFile)(tmpPath, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises5.rename)(tmpPath, filePath);
     }
   };
 }
 
 // src/orchestrator/verify-ai-birthcert.ts
-var import_node_crypto4 = require("node:crypto");
+var import_node_crypto5 = require("node:crypto");
 
 // src/canonical-json.ts
 function canonicalizeJson(value) {
@@ -23338,43 +23776,6 @@ function canonicalizeJson(value) {
   return JSON.stringify(value);
 }
 
-// src/accept-selection.ts
-function extraOf(accept) {
-  const extra = accept.extra;
-  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return {};
-  return extra;
-}
-function assetOf(accept) {
-  return String(accept.asset ?? "");
-}
-function declaresFacilitator(accept) {
-  return extraOf(accept).gasModel === "facilitator";
-}
-function isSponsored(accept) {
-  if (!declaresFacilitator(accept)) return false;
-  const prepareEndpoint = extraOf(accept).prepareEndpoint;
-  if (typeof prepareEndpoint !== "string" || prepareEndpoint === "") return false;
-  const asset = assetOf(accept);
-  return asset !== "" && asset !== "ZTX";
-}
-function isUnusable(accept) {
-  return declaresFacilitator(accept) && !isSponsored(accept);
-}
-function orderAccepts(accepts, prefer) {
-  const usable = accepts.filter((a) => !isUnusable(a));
-  const sponsored = usable.filter(isSponsored);
-  const selfPay = usable.filter((a) => !isSponsored(a));
-  return prefer === "sponsored" ? [...sponsored, ...selfPay] : [...selfPay, ...sponsored];
-}
-function prepareBaseUrl(prepareEndpoint) {
-  return prepareEndpoint.replace(/\/+$/, "").replace(/\/prepare$/, "");
-}
-function needsNativeGasCheck(accept) {
-  const asset = String(accept.asset ?? "");
-  if (asset === "" || asset === "ZTX") return false;
-  return !isSponsored(accept);
-}
-
 // src/orchestrator/verify-ai-birthcert.ts
 function subjectMatches(vc, holderDid) {
   if (typeof vc !== "object" || vc === null) return false;
@@ -23581,29 +23982,48 @@ async function requestAiBirthcertVerification(deps, input) {
     throw new Error("requestAiBirthcertVerification: agentName is required");
   }
   const agentName = input.agentName.trim();
+  if (input.dryRun) return quoteVerification(deps, agentName, input);
   return withRequestLock(() => requestAiBirthcertVerificationLocked(deps, agentName, input));
 }
+async function buildSessionBody(deps, agentName, input) {
+  const fields = {
+    publicKey: deps.publicKeyHex,
+    address: deps.address,
+    timestamp: isoSeconds(deps.now()),
+    agentName,
+    id: agentName,
+    ownerReference: deps.holderDid
+  };
+  if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
+  if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
+  if (input.ownerType) fields.ownerType = input.ownerType;
+  if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
+  const digestHex = (0, import_node_crypto5.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
+  const { signBlob: signedData } = await deps.signHexBlob(digestHex);
+  return { ...fields, signedData };
+}
+async function quoteVerification(deps, agentName, input) {
+  const requestedGasPayer = input.gasPayer === "self" || input.gasPayer === "sponsored" ? input.gasPayer : void 0;
+  const body = await buildSessionBody(deps, agentName, input);
+  const challenge = await deps.ssivc.createSessionChallenge(body);
+  const chosen = orderAccepts(challenge.accepts, requestedGasPayer ?? deps.gasPreference ?? "sponsored")[0];
+  if (!chosen) return { error: "SSIVC 402 returned no usable payment options" };
+  return {
+    quote: {
+      asset: String(chosen.asset ?? ""),
+      maxAmountRequired: String(chosen.maxAmountRequired ?? ""),
+      ...chosen.payTo ? { payTo: String(chosen.payTo) } : {},
+      // Report the option that would actually be paid, not merely what was offered — the ranking
+      // already discards a sponsored quote we could not act on.
+      gasModel: isSponsored(chosen) ? "sponsored" : "self"
+    }
+  };
+}
 async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
   const decision = await decidePriorSession(deps, agentName);
   if (decision.kind === "still_pending") return decision.result;
   if (decision.kind === "blocked") return { error: decision.message };
-  const buildBody = async () => {
-    const fields = {
-      publicKey: deps.publicKeyHex,
-      address: deps.address,
-      timestamp: isoSeconds(deps.now()),
-      agentName,
-      id: agentName,
-      ownerReference: deps.holderDid
-    };
-    if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
-    if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
-    if (input.ownerType) fields.ownerType = input.ownerType;
-    if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
-    const digestHex = (0, import_node_crypto4.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
-    const { signBlob: signedData } = await deps.signHexBlob(digestHex);
-    return { ...fields, signedData };
-  };
+  const buildBody = () => buildSessionBody(deps, agentName, input);
   const persistQueuedReceipt = async (receipt) => {
     try {
       await deps.sessionStore.set({
@@ -23639,8 +24059,8 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
     }
   } catch (rawErr) {
     const err = rawErr instanceof PrepareStageError ? rawErr.cause : rawErr;
-    if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}` };
-    if (err instanceof PaymentCapError) return { error: err.message };
+    if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}`, insufficientFunds: err.shortfall };
+    if (err instanceof PaymentCapError) return { error: err.message, ...err.detail ? { paymentCap: err.detail } : {} };
     if (err instanceof NoPaymentOptionsError) return { error: err.message };
     if (err instanceof FacilitatorInsufficientFundsError) return { error: err.message };
     if (err instanceof SettlementStillQueuedError) {
@@ -23693,7 +24113,11 @@ async function checkAiBirthcertVerification(deps) {
     };
   }
   const status = await deps.ssivc.getSession(stored.sessionId);
+  if (status.status !== "issued" && stored.verificationUrl) {
+    return { ...status, verificationUrl: stored.verificationUrl };
+  }
   if (status.status !== "issued" || !status.vcId) return status;
+  const vcId = status.vcId;
   if (deps.verifiedTemplateId && deps.cache) {
     const cached2 = await deps.cache.get(deps.verifiedTemplateId);
     if (cached2 && cached2.vcId === status.vcId && isVcValid(cached2)) return { ...status, vc: cached2.vc };
@@ -23701,20 +24125,22 @@ async function checkAiBirthcertVerification(deps) {
   if (!deps.verifiedTemplateId || !deps.cache) {
     return { ...status, cacheError: "AI Birthcert verified-template id is not configured \u2014 cannot fetch or cache the credential yet." };
   }
-  const quarantined = await deps.quarantine.get(status.vcId);
-  const quarantineFilePath = deps.quarantine.filePathFor(status.vcId);
-  let entries;
-  if (quarantined) {
-    entries = quarantined.entries;
-  } else {
+  const quarantineFilePath = deps.quarantine.filePathFor(vcId);
+  const locked = await deps.quarantine.withLock(vcId, async () => {
+    const quarantined = await deps.quarantine.get(vcId);
+    if (quarantined) return { entries: quarantined.entries };
     const auth = await deps.messageSigner(deps.address).then((r) => ({ signedData: r.signBlob, publicKey: r.publicKey }));
+    let downloaded;
     try {
-      entries = await deps.mbi.downloadVcs({ address: deps.address }, auth);
+      downloaded = await deps.mbi.downloadVcs({ address: deps.address }, auth);
     } catch (err) {
-      return { ...status, cacheError: `failed to fetch credential from MBI: ${err instanceof Error ? err.message : String(err)}` };
+      return { error: `failed to fetch credential from MBI: ${err instanceof Error ? err.message : String(err)}` };
     }
-    await deps.quarantine.set({ vcId: status.vcId, entries, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() });
-  }
+    await deps.quarantine.set({ vcId, entries: downloaded, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    return { entries: downloaded };
+  });
+  if ("error" in locked) return { ...status, cacheError: locked.error };
+  const entries = locked.entries;
   const match = entries.find((e) => typeof e.vc === "object" && e.vc !== null && e.vc.id === status.vcId);
   if (!match) {
     return {
@@ -23741,14 +24167,23 @@ async function checkAiBirthcertVerification(deps) {
       cacheError: `downloaded credential expired at ${validUntil} \u2014 refusing to cache or return; raw response preserved for recovery at ${quarantineFilePath}`
     };
   }
+  const vcPassImagePaths = deps.passImagesDir ? await (async () => {
+    try {
+      const base64Images = extractVcPassBase64(match.extraData);
+      return base64Images ? await writeVcPassImages(deps.passImagesDir, status.vcId, base64Images) : void 0;
+    } catch {
+      return void 0;
+    }
+  })() : void 0;
   await deps.cache.set(deps.verifiedTemplateId, {
     templateId: deps.verifiedTemplateId,
     vc: match.vc,
     vcId: status.vcId,
     issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    validUntil
+    validUntil,
+    ...vcPassImagePaths ? { vcPassImagePaths } : {}
   });
-  return { ...status, vc: match.vc };
+  return { ...status, vc: match.vc, ...vcPassImagePaths ? { vcPassImagePaths } : {} };
 }
 
 // src/index.ts
@@ -23762,7 +24197,8 @@ function buildToolList() {
         type: "object",
         properties: {
           heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds. Omit to report whatever the wallet has cached locally from prior subscribe_and_issue calls instead." },
-          token: { type: "string", description: `Optional token symbol (e.g. "ZTX", "JMYR") to check its balance for the active network, alongside the usual status fields. Returns { balance, decimals } where balance is in the asset's raw base units \u2014 divide by 10^decimals for the human amount (e.g. balance "473999900" with decimals 6 is 473.9999 JMYR). A failed lookup reports { error: "query_failed" } rather than a zero balance.` }
+          token: { type: "string", description: 'Optional token symbol (e.g. "ZTX", "JMYR") OR a ZTP20 contract address, to check its balance for the active network alongside the usual status fields. Returns { balance, decimals, display } \u2014 `balance` is in the asset\'s raw base units and `display` is the same amount in whole tokens with its symbol (e.g. balance "473999900", decimals 6, display "473.9999 JMYR"). Quote a `display` value to the user, never a bare `balance`. A failed lookup reports { error: "query_failed" } rather than a zero balance; an unrecognised name reports { error: "unknown_token" }.' },
+          tokens: { type: "array", items: { type: "string" }, description: 'Several tokens (symbols and/or ZTP20 contract addresses) in one call, returned as `tokenBalances` in the order asked. Prefer this over repeated single-token calls when checking affordability: a credential fee and the native ZTX needed for gas are separate balances, and asking one at a time is how "you hold the token but no gas" is discovered only after the first shortfall was already fixed. Each entry carries its own result or error, so one failure does not hide the rest.' }
         }
       }
     },
@@ -23845,7 +24281,7 @@ function buildToolList() {
           expirationDate: { type: "string" },
           dryRun: {
             type: "boolean",
-            description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo }, schema: { required, optional } } without paying or issuing \u2014 use this to check the payment requirement AND the template's full attribute schema (read from chain) before spending funds. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
+            description: "Price the credential without paying, signing, or issuing anything. Returns { quote: { asset, maxAmountRequired, payTo, gasModel, paymentRequired? }, schema: { required, optional } }. Priced via MBI's /quote endpoint, which cannot issue \u2014 so this is safe even on a template that issues for free (such a template mints synchronously on the real path, which is why pricing never goes through it). Never writes the VC cache, so it cannot displace a credential you already hold. `quote.paymentRequired` is the authoritative free-vs-paid answer: false means issuance is currently free and `maxAmountRequired` will not be charged. When the field is ABSENT the MBI predates it and the amount is unconfirmed \u2014 report it as a possible charge, never as certainly free. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
           },
           forceReissue: {
             type: "boolean",
@@ -23857,7 +24293,7 @@ function buildToolList() {
     },
     {
       name: "request_ai_birthcert_verification",
-      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the wallet's configured MAX_PAYMENT_AMOUNT cap, the same as pay_and_fetch/subscribe_and_issue. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that.`,
+      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the same credential-issuance payment cap as subscribe_and_issue \u2014 a separate, narrower cap than pay_and_fetch's, which defaults to refusing everything on mainnet. Set MAX_PAYMENT_AMOUNT to override either. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -23873,14 +24309,36 @@ function buildToolList() {
             type: "string",
             enum: ["sponsored", "self"],
             description: `Who pays network gas. "sponsored" (default) asks the platform paymaster to cover gas, so this wallet needs no ZTX. "self" pays gas from this wallet's own ZTX balance. Omit to use the configured default.`
+          },
+          dryRun: {
+            type: "boolean",
+            description: "Ask the price WITHOUT paying. Returns { quote: { asset, maxAmountRequired, payTo, gasModel } } and spends nothing, creates no session, and starts no verification \u2014 so you can tell the user the cost before collecting anything. `maxAmountRequired` is in the asset's RAW base units; resolve decimals (wallet_status returns `display`) before quoting a figure to a human. A quote does NOT reserve the name and does NOT check whether it is already taken \u2014 myid checks uniqueness only at issuance, so a name already in use still quotes cleanly. `agentName` is still required because the server rejects a request without one, but the fee does not depend on it."
           }
         },
         required: ["agentName"]
       }
     },
+    {
+      name: "credential_preflight",
+      description: "FREE readiness check \u2014 call this FIRST, before collecting ANY application detail from the user, whenever they ask for a credential. Spends nothing, signs no transaction, creates no session. Returns { ready, fee, balances, cap, schema?, blockers, notChecked }: the live fee and which side pays gas, the balances that matter, whether the spending limit permits it, and \u2014 for a template credential \u2014 the attributes it requires. `blockers` lists EVERY reason it is not ready at once (a low balance and a too-low spending limit are different problems and both appear together), so one round of fixes is enough rather than discovering them one failed payment at a time. ALWAYS relay `notChecked` too: a clean result is not a guarantee. In particular it does NOT check whether an agent name is free \u2014 myid decides that at issuance, after payment. Report `fee.display` and each balance's `display` to the user, never the raw base-unit numbers. `fee.paymentRequired: false` means issuance is currently FREE \u2014 `fee.display` is then only what it WOULD cost if payment were switched back on, so do not ask the user to fund it and do not present that amount as a charge. Gas is separate and can still block a free credential. When the field is ABSENT the cost is unknown (an older MBI), and it is treated as chargeable \u2014 never report absent as free.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          credential: {
+            type: "string",
+            description: 'Which credential to price: "verified_ai_birthcert" for the MyDigital-ID-verified AI Birthcert, or a template id (did:zid:...) / known template name (e.g. "AI Birthcert") for a template-issued one.'
+          },
+          agentName: {
+            type: "string",
+            description: 'Optional, and only used for "verified_ai_birthcert". The fee does not depend on it, so omit it when pricing before the user has chosen a name \u2014 the wallet substitutes a placeholder purely to satisfy the server. Never present that placeholder as the name that will be used.'
+          }
+        },
+        required: ["credential"]
+      }
+    },
     {
       name: "check_ai_birthcert_verification",
-      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
+      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). FREE \u2014 spends nothing and starts nothing. Use this, not request_ai_birthcert_verification, whenever the user asks where their verification link is, what happened to their session, or whether their credential is ready. While the session is still open the result carries `verificationUrl` (the same link issued at creation) and `expiresAt` \u2014 give the user both, so they know how long it is good for. Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
       inputSchema: { type: "object", properties: {} }
     },
     {
@@ -23900,6 +24358,13 @@ function buildToolList() {
     }
   ];
 }
+function buildPayers(config2, makePay) {
+  return {
+    pay: makePay(config2.maxPaymentAmount),
+    payForCredential: makePay(config2.credentialIssuanceCaps),
+    preflightCaps: config2.credentialIssuanceCaps
+  };
+}
 function asPayRequest(accept) {
   const extra = accept.extra ?? {};
   const prepareEndpoint = extra.prepareEndpoint;
@@ -23908,8 +24373,8 @@ function asPayRequest(accept) {
 }
 async function main() {
   const fileEnv = loadConfigFileEnv(process.argv, (p) => (0, import_node_fs.readFileSync)(p, "utf8"));
-  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path6.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
-  const accountStore = createFsAccountStore((0, import_node_path6.join)(stateDir, "account.json"));
+  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path7.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
+  const accountStore = createFsAccountStore((0, import_node_path7.join)(stateDir, "account.json"));
   if (process.argv[2] === "export-credentials") {
     const { exitCode } = await exportCredentials({
       getAccount: () => accountStore.get(),
@@ -23982,8 +24447,8 @@ async function main() {
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
-  const cacheScope = (0, import_node_crypto5.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
-  const vcCache = createFsVcCache((0, import_node_path6.join)(config2.stateDir, "vc-cache", cacheScope));
+  const cacheScope = (0, import_node_crypto6.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
+  const vcCache = createFsVcCache((0, import_node_path7.join)(config2.stateDir, "vc-cache", cacheScope));
   const mbi = new MbiClient(config2.mbiBaseUrl);
   const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
   const formatAssetAmount = async (asset, raw) => {
@@ -23992,15 +24457,19 @@ async function main() {
     const human = formatHumanAmount(raw, decimals);
     return human === raw ? `${raw} ${label}` : `${raw} (${human} ${label})`;
   };
-  const pay = async (accept) => {
+  const makePay = (caps) => async (accept) => {
     const rawAsset = String(accept.asset ?? "");
     try {
-      assertWithinPaymentCap(accept, config2.maxPaymentAmount);
+      assertWithinPaymentCap(accept, caps);
     } catch (err) {
       if (err instanceof PaymentCapError && err.detail) {
         const { asset, requiredRaw, capRaw } = err.detail;
         throw new PaymentCapError(
-          `payment blocked: requested ${await formatAssetAmount(asset, requiredRaw)} exceeds configured MAX_PAYMENT_AMOUNT ${await formatAssetAmount(asset, capRaw)}`,
+          formatCapRefusal(
+            err.detail,
+            await formatAssetAmount(asset, requiredRaw),
+            await formatAssetAmount(asset, capRaw)
+          ),
           err.detail
         );
       }
@@ -24034,16 +24503,22 @@ async function main() {
       throw err;
     }
   };
+  const { pay, payForCredential, preflightCaps } = buildPayers(config2, makePay);
+  const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path7.join)(config2.stateDir, "ssivc-download-quarantine"));
+  const passImagesDir = (0, import_node_path7.join)(config2.stateDir, "vc-pass-images");
+  const mbiAuth = async () => {
+    const { signBlob, publicKey } = await messageSigner(zetrixAddress);
+    return { signedData: signBlob, publicKey };
+  };
   const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
-    const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path6.join)(config2.stateDir, "ssivc-session.json"));
-    const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path6.join)(config2.stateDir, "ssivc-download-quarantine"));
+    const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path7.join)(config2.stateDir, "ssivc-session.json"));
     const ssivc = new SsivcClient(config2.ssivcBaseUrl);
     const verifyAiBirthcertDeps = {
       ssivc,
       signHexBlob: walletBeSignerFn,
       messageSigner,
       mbi,
-      pay,
+      pay: payForCredential,
       publicKeyHex,
       address: zetrixAddress,
       holderDid,
@@ -24054,7 +24529,8 @@ async function main() {
       quarantine: downloadQuarantine,
       gasPreference: config2.gasPreference,
       maxSettlementAttempts: config2.maxSettlementAttempts,
-      formatAssetAmount
+      formatAssetAmount,
+      passImagesDir
     };
     return {
       request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),
@@ -24105,9 +24581,25 @@ async function main() {
     config: { holderDid, zetrixAddress, network: config2.network },
     makeWallet,
     payer,
-    subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
+    subscribeDeps: {
+      mbi,
+      sign: subscribeSign,
+      pay: payForCredential,
+      resolveSymbol,
+      holderDid,
+      resolveTemplateFields,
+      cache: vcCache,
+      auth: mbiAuth,
+      address: zetrixAddress,
+      quarantine: downloadQuarantine,
+      passImagesDir
+    },
     queryContract: (input) => queryContract(input, contractQuery),
     queryTokenBalance: queryTokenBalance2,
+    // Read-only, for credential_preflight's cap headroom. Preflight only ever prices credentials,
+    // so it must report against the issuance cap — the same map payForCredential enforces, or
+    // preflight and the guard would disagree about what is permitted.
+    paymentCaps: preflightCaps,
     // The session password is bound here, in the wiring, so it never crosses into the tool
     // layer — create_holder_account has no password parameter for a model to be asked for.
     createAccount: (label, purpose) => be.createAccount(hsmPassword, label, purpose),
@@ -24126,7 +24618,7 @@ async function main() {
     if (!fn) throw new Error(`Unknown tool: ${name}`);
     try {
       const result = await fn(args ?? {});
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      return { content: await buildToolContent(result, (p) => (0, import_promises6.readFile)(p)) };
     } catch (err) {
       const chain = [];
       let e = err;
@@ -24150,5 +24642,6 @@ if (process.env.NODE_ENV !== "test") {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   asPayRequest,
+  buildPayers,
   buildToolList
 });