@fidacy/mcp 0.6.1 → 0.6.3

package/dist/core.js

@@ -488,7 +488,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.6.1" : "dev";
+var CLIENT_VERSION = true ? "0.6.3" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";

package/dist/index.js

@@ -15,6 +15,17 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  auditLogPath: () => auditLogPath,
+  configDir: () => configDir,
+  configPath: () => configPath,
+  ensureState: () => ensureState,
+  hasEngineKey: () => hasEngineKey,
+  readConfig: () => readConfig,
+  resolveMandateRules: () => resolveMandateRules,
+  writeConfig: () => writeConfig
+});
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -214,7 +225,7 @@ var init_telemetry = __esm({
   "src/telemetry.ts"() {
     "use strict";
     init_config();
-    CLIENT_VERSION = true ? "0.6.1" : "dev";
+    CLIENT_VERSION = true ? "0.6.3" : "dev";
     currentShell = "mcp";
     anonIdCache = null;
     buffer = [];
@@ -291,7 +302,7 @@ var init_register = __esm({
   "src/register.ts"() {
     "use strict";
     init_config();
-    CLIENT_VERSION3 = true ? "0.6.1" : "dev";
+    CLIENT_VERSION3 = true ? "0.6.3" : "dev";
   }
 });
 
@@ -583,6 +594,7 @@ var init_setup = __esm({
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createHash as createHash2 } from "node:crypto";
 import { z } from "zod";
 
 // src/core.ts
@@ -1267,7 +1279,7 @@ init_telemetry();
 
 // src/provision.ts
 init_config();
-var CLIENT_VERSION2 = true ? "0.6.1" : "dev";
+var CLIENT_VERSION2 = true ? "0.6.3" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -1384,7 +1396,7 @@ function renderSummary(s) {
   ];
   if (s.denied > 0) {
     const ranked = Object.entries(s.denied_by_rule).sort((a, b) => b[1] - a[1]);
-    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By rule: ${ranked.map(([rule, n]) => `${rule} (${n})`).join(", ")}.`);
+    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By reason: ${ranked.map(([rule, n]) => `${ruleLabel(rule)} (${n})`).join(", ")}.`);
   }
   if (s.amount_unknown > 0) {
     lines.push(`${s.amount_unknown} record(s) in this window predate amount logging, so the totals above are a floor, not the exact figure.`);
@@ -1411,32 +1423,82 @@ function renderRows(rows2) {
   return rows2.map((r) => {
     const amount = typeof r.amount === "number" ? `${r.amount.toLocaleString("en-US")} ${r.currency ?? ""}`.trim() : "amount not recorded";
     const who = r.payee ?? "payee not recorded";
-    const why = r.status === "DENY" ? ` blocked by ${r.violatedRule ?? "a rule not recorded on this older entry"}.` : "";
+    const why = r.status === "DENY" ? ` ${explainRule(r.violatedRule, r.payee)}` : "";
     const said = r.purpose ? ` Agent's stated reason: "${r.purpose}".` : "";
     return `#${r.seq} ${r.ts} ${r.status} ${amount} to ${who}.${why}${said} (decision ${r.decisionId})`;
   }).join("\n");
 }
+function ruleLabel(rule) {
+  if (rule.startsWith("payee_lookalike")) return "lookalike payee";
+  if (rule.startsWith("payee_not_in_allowlist")) return "payee not approved";
+  if (rule.startsWith("category_not_allowed")) return "purpose not allowed";
+  if (rule.startsWith("currency_not_allowed")) return "wrong currency";
+  if (rule.startsWith("per_tx") || rule.includes("perTxMax")) return "over the per-payment cap";
+  if (rule.includes("maxTotal") || rule.startsWith("total_cap") || rule.startsWith("budget")) return "over the total budget";
+  if (rule.startsWith("invoice") || rule.includes("duplicate")) return "duplicate invoice";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired")) return "outside the mandate window";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked")) return "mandate revoked";
+  if (rule.startsWith("invalid_mandate")) return "mandate misconfigured";
+  if (rule.startsWith("non_positive_amount")) return "invalid amount";
+  if (rule.startsWith("activation_required")) return "trial used up";
+  if (rule === "not_recorded") return "rule not recorded";
+  return rule;
+}
 function explainRule(rule, payee) {
   if (!rule) return "This entry predates readable rule logging, so the specific rule is not on the record. The decision payload is still covered by the chain digest.";
+  if (rule.startsWith("invalid_mandate")) {
+    const cap = rule.includes("perTxMax") ? "perTxMax" : rule.includes("maxTotal") ? "maxTotal" : null;
+    if (cap)
+      return `The mandate's \`${cap}\` is not a usable number, so the firewall denied rather than run without that cap. Values like "2,500", "$2500" or "2500 USD" all look right to a human and become NaN, and a cap that cannot be compared would silently let everything through. Write it as a bare number: ${cap}: 2500.`;
+    return "The mandate is missing its `allow` block, so there is nothing to enforce and the firewall denied. Check ~/.fidacy/config.json or FIDACY_MANDATE_JSON.";
+  }
+  if (rule.startsWith("payee_lookalike")) {
+    const approved = rule.includes("~") ? rule.split("~")[1] : "an approved payee";
+    return `The payee${payee ? ` "${payee}"` : ""} is a lookalike of your approved payee "${approved}": same name to a human glance, different string. That is the signature of a payee swap, whether from a prompt injection or a spoofed invoice. If it really is a separate vendor, add it to \`payees\` explicitly; if it is not, this attempt is exactly what the firewall exists to stop.`;
+  }
   if (rule.startsWith("payee_not_in_allowlist"))
-    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor.`;
+    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor. To authorize this one, add it to \`payees\` in ~/.fidacy/config.json, or pass a full mandate through FIDACY_MANDATE_JSON.`;
   if (rule.startsWith("category_not_allowed"))
-    return "The stated purpose category is not one the mandate permits for this agent.";
+    return "The stated purpose category is not one the mandate permits for this agent. Add it to `categories` in the mandate, or send the payment under a purpose the mandate already allows.";
   if (rule.startsWith("currency_not_allowed"))
-    return "The payment currency is not the mandate's currency.";
+    return "The payment currency is not the mandate's currency. Set `currency` to the one you intend to pay in. A mandate authorizes one currency at a time on purpose, so a swapped currency cannot slip past a cap set in another.";
   if (rule.startsWith("per_tx") || rule.includes("perTxMax"))
-    return "The amount exceeds the per-transaction ceiling in the mandate.";
-  if (rule.includes("maxTotal") || rule.startsWith("budget"))
-    return "The payment would push cumulative spend past the mandate's total budget for the window.";
+    return "The amount exceeds the per-transaction ceiling in the mandate. Raise `perTxMax` if payments this size are expected, or split the payment.";
+  if (rule.includes("maxTotal") || rule.startsWith("budget") || rule.startsWith("total_cap"))
+    return "The payment would push cumulative spend past the mandate's total budget for the window. Raise `maxTotal`, or wait for the window to roll over. Blocked attempts do not consume the budget; only payments that went through do.";
   if (rule.startsWith("invoice") || rule.includes("duplicate"))
-    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure.";
-  if (rule.startsWith("window") || rule.includes("expired"))
-    return "The mandate was outside its validity window at the moment of the request.";
-  if (rule.startsWith("revoked")) return "The mandate had been revoked.";
+    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure. If this genuinely is a second, separate payment, give it its own invoiceRef.";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired"))
+    return "The mandate was outside its validity window at the moment of the request. Check `notBefore` and `notAfter`, and issue a mandate whose window covers now.";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked"))
+    return "The mandate had been revoked. A revoked mandate cannot be un-revoked; issue a new one to authorize further payments.";
+  if (rule.startsWith("non_positive_amount"))
+    return "The amount was zero or negative, which is not a payment anyone can authorize. Check what produced that value before retrying.";
   if (rule.startsWith("activation_required"))
     return "The anonymous trial had been used up, so the firewall failed closed. No money can move until the install is activated with a free API key.";
   return `The mandate rule "${rule}" was violated.`;
 }
+function explainEngineError(action, status, type, reasons) {
+  const noun = action === "verdict" ? "assess this action" : action === "anchor" ? "anchor this artifact" : "check this artifact";
+  if (status === 401 || status === 403)
+    return `Fidacy could not ${noun}: the engine rejected the credential (HTTP ${status}). This is not an outage. The key is missing, wrong, or lacks the scope this call needs \u2014 an anonymous provisioned key has no scopes at all. Get an account key at https://fidacy.com/claim and set FIDACY_ENGINE_API_KEY. Nothing was executed.`;
+  if (status === 402)
+    return `Fidacy could not ${noun}: the account is past a spending or quota limit (HTTP 402). The integration is fine; the limit needs settling at https://fidacy.com/claim. Nothing was executed.`;
+  if (status === 429)
+    return `Fidacy could not ${noun}: too many requests in a short window (HTTP 429). Retry in a few seconds. Nothing was executed, and no decision was recorded.`;
+  if (status === 404 && action === "check")
+    return "No anchor exists for that hash on this account. Either the artifact was never anchored, or its contents changed since it was \u2014 if you expected a match, the file is not the one that was anchored.";
+  if (status === 422 || type === "mandate_violation") {
+    const first = reasons?.[0]?.key;
+    const why = first ? ` ${explainRule(first)}` : "";
+    return `Fidacy denied this action: it falls outside the mandate in force.${why} Nothing was executed.`;
+  }
+  if (status >= 500)
+    return `Fidacy could not ${noun}: the engine returned an error (HTTP ${status}). Nothing was executed, and the call was refused rather than allowed through. Retrying is safe.`;
+  if (status === 400)
+    return `Fidacy could not ${noun}: the request was malformed (HTTP 400${type ? `, ${type}` : ""}). This is a bug in how the call was built, not a policy decision. Nothing was executed.`;
+  return `Fidacy could not ${noun} (HTTP ${status}${type ? `, ${type}` : ""}), so the call was refused rather than allowed through. Nothing was executed.`;
+}
 
 // src/banner.ts
 init_activation();
@@ -1594,8 +1656,12 @@ function renderAlertLine(alerts) {
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.6.1" : "dev";
+var SERVER_VERSION = true ? "0.6.3" : "dev";
 var bootClaim = claimUrl();
+function derivedIdempotencyKey(req) {
+  const material = [req.payee, req.amount, req.currency, req.invoiceRef ?? "", req.category ?? ""].join("|");
+  return "auto-" + createHash2("sha256").update(material).digest("hex").slice(0, 24);
+}
 var server = new McpServer(
   // The commercial identity. `name` is the stable slug hosts key on; `title` is
   // what a human reads in the client's server list. The npm package stays
@@ -1629,7 +1695,9 @@ server.registerTool(
         "Your stated reason for this payment, in your own words. It is persisted readably on the tamper-evident audit record (ALLOW and DENY alike) and becomes part of the after-the-fact proof, so write the real reason."
       ),
       category: z.string().describe("Purpose category (must be allowed by the mandate)"),
-      idempotencyKey: z.string().describe("Caller-supplied idempotency key"),
+      idempotencyKey: z.string().describe(
+        "Optional. Your own key for this payment, if you have one (an order id, a job id). Leave it out and Fidacy derives one from the payment itself, which is the safer default: a retry of the SAME payment produces the SAME key, where an invented one would not."
+      ).optional(),
       invoiceRef: z.string().describe(
         "Optional invoice identity. When set, Fidacy enforces one payment per invoice: a second request for the same invoiceRef is DENIED, at any amount."
       ).optional()
@@ -1664,7 +1732,10 @@ server.registerTool(
       };
       return { content: [{ type: "text", text: halted }], structuredContent: out2 };
     }
-    const req = args;
+    const req = {
+      ...args,
+      idempotencyKey: args.idempotencyKey || derivedIdempotencyKey(args)
+    };
     let sentinelAlerts = [];
     try {
       const [before, mandate] = await Promise.all([core.history(5e3), core.getMandate(subject)]);
@@ -1859,9 +1930,8 @@ server.registerTool(
           markHostedLapsed();
           return { content: [{ type: "text", text: hostedWallCta("verdict", e.billing) }], isError: true };
         }
-        const reasons = e.rejection_reasons?.length ? " (" + e.rejection_reasons.map((x) => x.key).join(",") + ")" : "";
         return {
-          content: [{ type: "text", text: `ASSESS ${e.status}: ${e.type}${reasons}` }],
+          content: [{ type: "text", text: explainEngineError("verdict", e.status, e.type, e.rejection_reasons) }],
           isError: true
         };
       }
@@ -1925,7 +1995,7 @@ server.registerTool(
           markHostedLapsed();
           return { content: [{ type: "text", text: hostedWallCta("anchor", e.billing) }], isError: true };
         }
-        return { content: [{ type: "text", text: `ANCHOR ${e.status}: ${e.type}` }], isError: true };
+        return { content: [{ type: "text", text: explainEngineError("anchor", e.status, e.type) }], isError: true };
       }
       return { content: [{ type: "text", text: "ANCHOR failed: unexpected error" }], isError: true };
     }
@@ -1978,7 +2048,7 @@ server.registerTool(
       };
     } catch (e) {
       if (e instanceof AssessError) {
-        return { content: [{ type: "text", text: `CHECK ${e.status}: ${e.type}` }], isError: true };
+        return { content: [{ type: "text", text: explainEngineError("check", e.status, e.type) }], isError: true };
       }
       return { content: [{ type: "text", text: "CHECK failed: unexpected error" }], isError: true };
     }
@@ -2025,6 +2095,32 @@ async function main() {
     await runSetup2({ force: true });
     return;
   }
+  const allowAt = process.argv.indexOf("allow");
+  if (allowAt !== -1) {
+    const { readConfig: readConfig2, writeConfig: writeConfig2, configPath: configPath2 } = await Promise.resolve().then(() => (init_config(), config_exports));
+    const payees = process.argv.slice(allowAt + 1).filter((a) => !a.startsWith("-"));
+    if (!payees.length) {
+      console.error("Usage: npx @fidacy/mcp allow <payee> [more payees\u2026]\nApproves counterparties this agent may pay. Everything else stays denied.");
+      process.exitCode = 1;
+      return;
+    }
+    const cfg = readConfig2();
+    if (!cfg) {
+      console.error("No Fidacy config yet. Run the agent once (or `npx @fidacy/mcp setup`) so the install exists, then approve a payee.");
+      process.exitCode = 1;
+      return;
+    }
+    const mandate = { ...cfg.mandate ?? {} };
+    const current = Array.isArray(mandate.payees) ? mandate.payees : [];
+    const added = payees.filter((p) => !current.includes(p));
+    mandate.payees = [...current, ...added];
+    writeConfig2({ ...cfg, mandate });
+    console.error(
+      added.length ? `Approved ${added.map((p) => `"${p}"`).join(", ")}. This agent may now pay ${added.length === 1 ? "that counterparty" : "those counterparties"} within the mandate's caps; everything else is still denied.
+Written to ${configPath2()}. The firewall picks it up on the next call, no restart needed.` : `Already approved: ${payees.map((p) => `"${p}"`).join(", ")}. Nothing changed.`
+    );
+    return;
+  }
   const transport = new StdioServerTransport();
   await server.connect(transport);
   if (state.firstRun) recordInstall();

package/dist/lib.js

@@ -643,7 +643,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.6.1" : "dev";
+var CLIENT_VERSION = true ? "0.6.3" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -831,7 +831,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.6.1" : "dev";
+var CLIENT_VERSION2 = true ? "0.6.3" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -994,7 +994,7 @@ function activationBootLine() {
 }
 
 // src/register.ts
-var CLIENT_VERSION3 = true ? "0.6.1" : "dev";
+var CLIENT_VERSION3 = true ? "0.6.3" : "dev";
 function endpoint3() {
   const base = (process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com").replace(/\/$/, "");
   return `${base}/v1/register`;
@@ -1160,7 +1160,7 @@ function renderSummary(s) {
   ];
   if (s.denied > 0) {
     const ranked = Object.entries(s.denied_by_rule).sort((a, b) => b[1] - a[1]);
-    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By rule: ${ranked.map(([rule, n]) => `${rule} (${n})`).join(", ")}.`);
+    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By reason: ${ranked.map(([rule, n]) => `${ruleLabel(rule)} (${n})`).join(", ")}.`);
   }
   if (s.amount_unknown > 0) {
     lines.push(`${s.amount_unknown} record(s) in this window predate amount logging, so the totals above are a floor, not the exact figure.`);
@@ -1187,28 +1187,57 @@ function renderRows(rows) {
   return rows.map((r) => {
     const amount = typeof r.amount === "number" ? `${r.amount.toLocaleString("en-US")} ${r.currency ?? ""}`.trim() : "amount not recorded";
     const who = r.payee ?? "payee not recorded";
-    const why = r.status === "DENY" ? ` blocked by ${r.violatedRule ?? "a rule not recorded on this older entry"}.` : "";
+    const why = r.status === "DENY" ? ` ${explainRule(r.violatedRule, r.payee)}` : "";
     const said = r.purpose ? ` Agent's stated reason: "${r.purpose}".` : "";
     return `#${r.seq} ${r.ts} ${r.status} ${amount} to ${who}.${why}${said} (decision ${r.decisionId})`;
   }).join("\n");
 }
+function ruleLabel(rule) {
+  if (rule.startsWith("payee_lookalike")) return "lookalike payee";
+  if (rule.startsWith("payee_not_in_allowlist")) return "payee not approved";
+  if (rule.startsWith("category_not_allowed")) return "purpose not allowed";
+  if (rule.startsWith("currency_not_allowed")) return "wrong currency";
+  if (rule.startsWith("per_tx") || rule.includes("perTxMax")) return "over the per-payment cap";
+  if (rule.includes("maxTotal") || rule.startsWith("total_cap") || rule.startsWith("budget")) return "over the total budget";
+  if (rule.startsWith("invoice") || rule.includes("duplicate")) return "duplicate invoice";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired")) return "outside the mandate window";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked")) return "mandate revoked";
+  if (rule.startsWith("invalid_mandate")) return "mandate misconfigured";
+  if (rule.startsWith("non_positive_amount")) return "invalid amount";
+  if (rule.startsWith("activation_required")) return "trial used up";
+  if (rule === "not_recorded") return "rule not recorded";
+  return rule;
+}
 function explainRule(rule, payee) {
   if (!rule) return "This entry predates readable rule logging, so the specific rule is not on the record. The decision payload is still covered by the chain digest.";
+  if (rule.startsWith("invalid_mandate")) {
+    const cap = rule.includes("perTxMax") ? "perTxMax" : rule.includes("maxTotal") ? "maxTotal" : null;
+    if (cap)
+      return `The mandate's \`${cap}\` is not a usable number, so the firewall denied rather than run without that cap. Values like "2,500", "$2500" or "2500 USD" all look right to a human and become NaN, and a cap that cannot be compared would silently let everything through. Write it as a bare number: ${cap}: 2500.`;
+    return "The mandate is missing its `allow` block, so there is nothing to enforce and the firewall denied. Check ~/.fidacy/config.json or FIDACY_MANDATE_JSON.";
+  }
+  if (rule.startsWith("payee_lookalike")) {
+    const approved = rule.includes("~") ? rule.split("~")[1] : "an approved payee";
+    return `The payee${payee ? ` "${payee}"` : ""} is a lookalike of your approved payee "${approved}": same name to a human glance, different string. That is the signature of a payee swap, whether from a prompt injection or a spoofed invoice. If it really is a separate vendor, add it to \`payees\` explicitly; if it is not, this attempt is exactly what the firewall exists to stop.`;
+  }
   if (rule.startsWith("payee_not_in_allowlist"))
-    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor.`;
+    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor. To authorize this one, add it to \`payees\` in ~/.fidacy/config.json, or pass a full mandate through FIDACY_MANDATE_JSON.`;
   if (rule.startsWith("category_not_allowed"))
-    return "The stated purpose category is not one the mandate permits for this agent.";
+    return "The stated purpose category is not one the mandate permits for this agent. Add it to `categories` in the mandate, or send the payment under a purpose the mandate already allows.";
   if (rule.startsWith("currency_not_allowed"))
-    return "The payment currency is not the mandate's currency.";
+    return "The payment currency is not the mandate's currency. Set `currency` to the one you intend to pay in. A mandate authorizes one currency at a time on purpose, so a swapped currency cannot slip past a cap set in another.";
   if (rule.startsWith("per_tx") || rule.includes("perTxMax"))
-    return "The amount exceeds the per-transaction ceiling in the mandate.";
-  if (rule.includes("maxTotal") || rule.startsWith("budget"))
-    return "The payment would push cumulative spend past the mandate's total budget for the window.";
+    return "The amount exceeds the per-transaction ceiling in the mandate. Raise `perTxMax` if payments this size are expected, or split the payment.";
+  if (rule.includes("maxTotal") || rule.startsWith("budget") || rule.startsWith("total_cap"))
+    return "The payment would push cumulative spend past the mandate's total budget for the window. Raise `maxTotal`, or wait for the window to roll over. Blocked attempts do not consume the budget; only payments that went through do.";
   if (rule.startsWith("invoice") || rule.includes("duplicate"))
-    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure.";
-  if (rule.startsWith("window") || rule.includes("expired"))
-    return "The mandate was outside its validity window at the moment of the request.";
-  if (rule.startsWith("revoked")) return "The mandate had been revoked.";
+    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure. If this genuinely is a second, separate payment, give it its own invoiceRef.";
+  if (rule.startsWith("window") || rule.includes("mandate_window") || rule.includes("expired"))
+    return "The mandate was outside its validity window at the moment of the request. Check `notBefore` and `notAfter`, and issue a mandate whose window covers now.";
+  if (rule.startsWith("revoked") || rule.startsWith("mandate_revoked"))
+    return "The mandate had been revoked. A revoked mandate cannot be un-revoked; issue a new one to authorize further payments.";
+  if (rule.startsWith("non_positive_amount"))
+    return "The amount was zero or negative, which is not a payment anyone can authorize. Check what produced that value before retrying.";
   if (rule.startsWith("activation_required"))
     return "The anonymous trial had been used up, so the firewall failed closed. No money can move until the install is activated with a free API key.";
   return `The mandate rule "${rule}" was violated.`;

package/dist/postinstall.js

@@ -134,7 +134,7 @@ var init_register = __esm({
   "src/register.ts"() {
     "use strict";
     init_config();
-    CLIENT_VERSION = true ? "0.6.1" : "dev";
+    CLIENT_VERSION = true ? "0.6.3" : "dev";
   }
 });
 

package/dist/reporting.d.ts

@@ -56,4 +56,26 @@ export declare function renderRows(rows: DecisionRow[]): string;
  * "why" without reading a rule name: a violated rule is a policy sentence, and
  * the mandate that produced it is the thing they can actually change.
  */
+/**
+ * Two-to-four word name for a rule, for places that RANK rules rather than
+ * explain one. The ranked list in a summary needs a label a human can scan, not
+ * a paragraph and not `per_tx_cap_exceeded:4200>1000`.
+ */
+export declare function ruleLabel(rule: string): string;
 export declare function explainRule(rule: string | undefined, payee?: string): string;
+/**
+ * Plain-language reading of an ENGINE failure, for the moment a call is refused.
+ *
+ * The hosted path used to surface `ASSESS 422: mandate_violation (payee_not_in_allowlist)`
+ * verbatim. That is a log line: it names a status code and an internal key, and
+ * leaves the operator to guess whether Fidacy is down, their key is wrong, or
+ * their own policy just did its job. Those three have completely different fixes,
+ * and only one of them is a problem with Fidacy.
+ *
+ * `reasons` are the engine's rejection keys, which map onto the same vocabulary
+ * explainRule already speaks, so a policy rejection reads the same whether it was
+ * decided locally or hosted.
+ */
+export declare function explainEngineError(action: "verdict" | "anchor" | "check", status: number, type: string, reasons?: {
+    key: string;
+}[]): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "author": "Fidacy (ZeepCode Group Technology LLC) <hello@fidacy.com> (https://fidacy.com)",
@@ -50,6 +50,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "node scripts/bundle.mjs",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "postinstall": "node -e \"try{require('fs').accessSync('dist/postinstall.js')}catch{process.exit(0)};import('./dist/postinstall.js')\" || exit 0"
+  },
   "engines": {
     "node": ">=18"
   },
@@ -58,23 +67,15 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@fidacy/firewall": "workspace:*",
     "@types/node": "^22.10.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^3.2.4",
-    "@fidacy/firewall": "0.1.1"
+    "vitest": "^3.2.4"
   },
   "mcpName": "com.fidacy/ai-agent-firewall",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lucaslubi/fidacy-mcp.git"
-  },
-  "scripts": {
-    "build": "node scripts/bundle.mjs",
-    "dev": "tsx watch src/index.ts",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "postinstall": "node -e \"try{require('fs').accessSync('dist/postinstall.js')}catch{process.exit(0)};import('./dist/postinstall.js')\" || exit 0"
   }
-}
+}