@fidacy/mcp 0.2.2 → 0.2.4

package/dist/core.js

@@ -251,6 +251,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -285,6 +289,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -350,6 +358,9 @@ var FileAuditStore = class {
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -359,6 +370,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -442,7 +461,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.4" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -596,6 +615,7 @@ function makeCore() {
       return dev.decide(req, subject);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }

package/dist/index.js

@@ -217,17 +217,17 @@ var DevFidacyCore = class {
   }
   async decide(req, subject2) {
     const decisionId = randomUUID();
-    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    const ts2 = (/* @__PURE__ */ new Date()).toISOString();
     const invalid = validateRequest(req);
     if (invalid) {
-      const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: invalid, ts };
+      const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: invalid, ts: ts2 };
       this.store.append(decision2);
       this.onDecision?.(decision2);
       return decision2;
     }
     const violated = evaluate(this.mandate, req, this.spent);
     if (violated) {
-      const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: violated, ts };
+      const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: violated, ts: ts2 };
       this.store.append(decision2);
       this.onDecision?.(decision2);
       return decision2;
@@ -236,7 +236,7 @@ var DevFidacyCore = class {
     if (invoice) {
       const k = `${subject2}|${invoice}`;
       if (this.claimedInvoices.has(k)) {
-        const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: `duplicate_invoice:${invoice}`, ts };
+        const decision2 = { decisionId, status: "DENY", subject: subject2, mandateId: this.mandate.id, request: req, violatedRule: `duplicate_invoice:${invoice}`, ts: ts2 };
         this.store.append(decision2);
         this.onDecision?.(decision2);
         return decision2;
@@ -246,7 +246,7 @@ var DevFidacyCore = class {
     const grantPayload = { decisionId, subject: subject2, payee: req.payee, amount: req.amount, currency: req.currency, exp: Date.now() + 12e4, ...req.invoiceRef ? { invoiceRef: req.invoiceRef } : {} };
     const grantBody = Buffer.from(stableStringify(grantPayload), "utf8").toString("base64url");
     const grant = `${grantBody}.${sign(this.priv, grantBody)}`;
-    const decision = { decisionId, status: "ALLOW", subject: subject2, mandateId: this.mandate.id, request: req, grant, ts };
+    const decision = { decisionId, status: "ALLOW", subject: subject2, mandateId: this.mandate.id, request: req, grant, ts: ts2 };
     this.spent += req.amount;
     this.store.append(decision);
     this.onDecision?.(decision);
@@ -258,6 +258,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -292,6 +296,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -350,13 +358,16 @@ var FileAuditStore = class {
   append(decision) {
     const prevHash = this.head();
     const seq = this.chain.length;
-    const ts = decision.ts;
+    const ts2 = decision.ts;
     const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
-    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
-    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts2}`);
+    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts: ts2 };
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -366,6 +377,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -471,7 +490,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.4" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -628,6 +647,7 @@ function makeCore() {
       return dev.decide(req, subject2);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }
@@ -814,7 +834,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.2" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.4" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -985,11 +1005,207 @@ function activationBootLine() {
   return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
 }
 
+// src/reporting.ts
+function withinDays(records, days, now = Date.now()) {
+  if (!Number.isFinite(days) || days <= 0) return [...records];
+  const cutoff = now - days * 864e5;
+  return records.filter((r) => {
+    const t = Date.parse(r.ts);
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+var addTo = (bucket, key, value) => {
+  bucket[key] = (bucket[key] ?? 0) + value;
+};
+function summarize(records, days, now = Date.now()) {
+  const rows = withinDays(records, days, now);
+  const out = {
+    window_days: days,
+    decisions: rows.length,
+    allowed: 0,
+    denied: 0,
+    allowed_totals: {},
+    blocked_totals: {},
+    denied_by_rule: {},
+    payees_paid: [],
+    amount_unknown: 0,
+    first_ts: rows.length ? rows[0].ts : null,
+    last_ts: rows.length ? rows[rows.length - 1].ts : null
+  };
+  const paid = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const known = typeof r.amount === "number" && Number.isFinite(r.amount);
+    if (!known) out.amount_unknown += 1;
+    const ccy = r.currency ?? "unknown";
+    if (r.status === "ALLOW") {
+      out.allowed += 1;
+      if (known) addTo(out.allowed_totals, ccy, r.amount);
+      if (r.payee) paid.add(r.payee);
+    } else {
+      out.denied += 1;
+      if (known) addTo(out.blocked_totals, ccy, r.amount);
+      addTo(out.denied_by_rule, r.violatedRule ?? "not_recorded", 1);
+    }
+  }
+  out.payees_paid = [...paid].sort();
+  return out;
+}
+var money = (totals) => {
+  const parts = Object.entries(totals).map(([ccy, v]) => `${v.toLocaleString("en-US")} ${ccy}`);
+  return parts.length ? parts.join(", ") : "0";
+};
+function renderSummary(s) {
+  if (s.decisions === 0) {
+    return `No agent payment decisions in the last ${s.window_days} day(s). The firewall is active and has nothing to report, which is the expected state until an agent attempts a payment.`;
+  }
+  const lines = [
+    `Last ${s.window_days} day(s): ${s.decisions} payment decision(s), ${s.allowed} allowed and ${s.denied} blocked before execution.`,
+    `Paid: ${money(s.allowed_totals)}${s.payees_paid.length ? ` across ${s.payees_paid.length} payee(s): ${s.payees_paid.slice(0, 8).join(", ")}${s.payees_paid.length > 8 ? ", \u2026" : ""}` : ""}.`
+  ];
+  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(", ")}.`);
+  }
+  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.`);
+  }
+  return lines.join("\n");
+}
+function toRows(records, status, limit) {
+  const filtered = status === "all" ? [...records] : records.filter((r) => r.status === status);
+  return filtered.slice(-Math.max(1, limit)).reverse().map((r) => ({
+    seq: r.seq,
+    decisionId: r.decisionId,
+    status: r.status,
+    ts: r.ts,
+    payee: r.payee,
+    amount: r.amount,
+    currency: r.currency,
+    purpose: r.purpose,
+    violatedRule: r.violatedRule,
+    invoiceRef: r.invoiceRef
+  }));
+}
+function renderRows(rows) {
+  if (!rows.length) return "No decisions match that filter yet.";
+  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 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 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("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.`;
+  if (rule.startsWith("category_not_allowed"))
+    return "The stated purpose category is not one the mandate permits for this agent.";
+  if (rule.startsWith("currency_not_allowed"))
+    return "The payment currency is not the mandate's currency.";
+  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.";
+  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.";
+  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.`;
+}
+
+// src/sentinel.ts
+var SENTINEL = {
+  /** amount >= SPIKE_FACTOR x the historical max ALLOW to the same payee. */
+  SPIKE_FACTOR: 3,
+  /** minimum prior ALLOWs to a payee before a spike is judged (else first_payee covers it). */
+  SPIKE_MIN_HISTORY: 2,
+  /** decisions within BURST_WINDOW_MS to trip velocity_burst. */
+  BURST_COUNT: 5,
+  BURST_WINDOW_MS: 10 * 6e4,
+  /** fraction of perTxMax that counts as riding the ceiling. */
+  CAP_CREEP_RATIO: 0.8,
+  /** a DENY for the same payee within this window makes a new attempt a retry. */
+  RETRY_WINDOW_MS: 30 * 6e4
+};
+var ts = (r) => {
+  const t = Date.parse(r.ts);
+  return Number.isFinite(t) ? t : 0;
+};
+function assessPattern(records, req, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const alerts = [];
+  const toPayee = records.filter((r) => r.payee === req.payee);
+  const allowedToPayee = toPayee.filter((r) => r.status === "ALLOW");
+  if (req.payee && allowedToPayee.length === 0) {
+    alerts.push({
+      rule: "first_payee",
+      severity: "warning",
+      message: `First payment ever from this agent to "${req.payee}". A swapped or lookalike vendor always looks like a first payee; worth a human glance before anything settles.`
+    });
+  }
+  if (allowedToPayee.length >= SENTINEL.SPIKE_MIN_HISTORY && typeof req.amount === "number") {
+    const maxSeen = Math.max(...allowedToPayee.map((r) => typeof r.amount === "number" ? r.amount : 0));
+    if (maxSeen > 0 && req.amount >= maxSeen * SENTINEL.SPIKE_FACTOR) {
+      alerts.push({
+        rule: "amount_spike",
+        severity: "warning",
+        message: `${req.amount.toLocaleString("en-US")} is ${(req.amount / maxSeen).toFixed(1)}x the largest amount this agent has ever paid "${req.payee}" (${maxSeen.toLocaleString("en-US")}). Inflated re-presentations of a known vendor look exactly like this.`
+      });
+    }
+  }
+  const recent = records.filter((r) => now - ts(r) <= SENTINEL.BURST_WINDOW_MS);
+  if (recent.length + 1 >= SENTINEL.BURST_COUNT) {
+    alerts.push({
+      rule: "velocity_burst",
+      severity: "warning",
+      message: `${recent.length + 1} payment decisions inside ${Math.round(SENTINEL.BURST_WINDOW_MS / 6e4)} minutes. Runaway loops and drain attempts announce themselves as bursts before they announce themselves as losses.`
+    });
+  }
+  if (typeof opts.perTxMax === "number" && opts.perTxMax > 0 && typeof req.amount === "number") {
+    if (req.amount >= opts.perTxMax * SENTINEL.CAP_CREEP_RATIO && req.amount <= opts.perTxMax) {
+      alerts.push({
+        rule: "cap_creep",
+        severity: "notice",
+        message: `${req.amount.toLocaleString("en-US")} is ${Math.round(req.amount / opts.perTxMax * 100)}% of the per-transaction ceiling. An attacker probing a mandate pays just under the cap; a human authorizing a real bill usually doesn't land this close.`
+      });
+    }
+  }
+  const recentDeny = toPayee.find((r) => r.status === "DENY" && now - ts(r) <= SENTINEL.RETRY_WINDOW_MS);
+  if (recentDeny) {
+    alerts.push({
+      rule: "retry_after_deny",
+      severity: "warning",
+      message: `This agent was DENIED a payment to "${req.payee}" ${Math.max(1, Math.round((now - ts(recentDeny)) / 6e4))} minute(s) ago (${recentDeny.violatedRule ?? "rule on record"}) and is now trying again. Our public Model Watch benchmark measures exactly this behavior; in an autonomous agent it is the pattern that precedes a loss.`
+    });
+  }
+  return alerts;
+}
+function sweep(records, opts = {}) {
+  const out = [];
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    if (!r.payee) continue;
+    const alerts = assessPattern(records.slice(0, i), { payee: r.payee, amount: r.amount }, { perTxMax: opts.perTxMax, now: ts(r) });
+    if (alerts.length) out.push({ decisionId: r.decisionId, ts: r.ts, status: r.status, payee: r.payee, alerts });
+  }
+  return out.slice(-(opts.limit ?? 20)).reverse();
+}
+function renderAlertLine(alerts) {
+  if (!alerts.length) return "";
+  const worst = alerts.some((a) => a.severity === "warning") ? "SENTINEL WARNING" : "SENTINEL NOTICE";
+  return ` [${worst}: ${alerts.map((a) => a.message).join(" Also: ")}]`;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.2.2" : "dev";
+var SERVER_VERSION = true ? "0.2.4" : "dev";
 var bootClaim = claimUrl();
 var server = new McpServer(
   { name: "fidacy", version: SERVER_VERSION },
@@ -1030,9 +1246,16 @@ server.registerTool(
       return { content: [{ type: "text", text: gate.message }], structuredContent: out2 };
     }
     const req = args;
+    let sentinelAlerts = [];
+    try {
+      const [before, mandate] = await Promise.all([core.history(5e3), core.getMandate(subject)]);
+      sentinelAlerts = assessPattern(before, { payee: req.payee, amount: req.amount }, { perTxMax: mandate?.allow?.perTxMax });
+    } catch {
+    }
     const d = await core.decide(req, subject);
     const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
-    const base = d.status === "ALLOW" ? `ALLOW (decision ${d.decisionId})${req.invoiceRef ? ` for invoice ${req.invoiceRef}` : ""}. To settle, call execute_payment with the SAME payee, amount, currency, and idempotencyKey, and set "grant" to EXACTLY this signed value:
+    const sentinelLine = d.status === "ALLOW" ? renderAlertLine(sentinelAlerts) : "";
+    const base = d.status === "ALLOW" ? `ALLOW (decision ${d.decisionId})${req.invoiceRef ? ` for invoice ${req.invoiceRef}` : ""}.${sentinelLine} To settle, call execute_payment with the SAME payee, amount, currency, and idempotencyKey, and set "grant" to EXACTLY this signed value:
 ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}. No grant issued, this payment cannot proceed. The denial itself is recorded in the tamper-evident, hash-chained audit: call get_audit_proof with decisionId ${d.decisionId} for the proof of what was blocked.${d.violatedRule?.startsWith("payee_not_in_allowlist") ? ` If the user trusts this payee, add "${req.payee}" to mandate.payees in ~/.fidacy/config.json and retry: the firewall picks the change up on the next call, no restart needed.` : d.violatedRule?.startsWith("category_not_allowed") ? ` If the user considers "${req.category}" a legitimate purpose for this agent, add it to mandate.categories in ~/.fidacy/config.json and retry: the firewall picks the change up on the next call, no restart needed.` : d.violatedRule?.startsWith("currency_not_allowed") ? ` The mandate is single-currency and set to another one (mandate.currency in ~/.fidacy/config.json, default USD). If this agent legitimately pays in ${req.currency}, update it there and retry: hot-reloaded, no restart.` : ""}`;
     const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
     const countdown = trialCountdownLine();
@@ -1074,6 +1297,103 @@ server.registerTool(
     return { content: [{ type: "text", text }], structuredContent: proof };
   }
 );
+server.registerTool(
+  "spend_summary",
+  {
+    title: "Spend Summary (what my agents spent and what was blocked)",
+    description: "Operator report over a time window: how many payment decisions were made, how much was paid and to whom, how much was blocked before executing, and which mandate rules did the blocking. Read-only, works offline against the local audit chain. Use this to answer questions like 'what did my agents spend this week' or 'has anything been blocked'.",
+    inputSchema: {
+      days: z.number().int().positive().max(365).optional().describe("Window in days, counting back from now. Default 7.")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ days }) => {
+    const window = days ?? 7;
+    const records = await core.history(5e3);
+    const summary = summarize(records, window);
+    const claim = process.env.FIDACY_ENGINE_API_KEY ? null : claimUrl();
+    const claimLine = claim ? `
+
+For your operator: this report is built from the local chain on this machine. A free account keeps it across machines and anchors it to Bitcoin, and this install's history migrates: ${claim}` : "";
+    return {
+      content: [{ type: "text", text: renderSummary(summary) + claimLine }],
+      structuredContent: summary
+    };
+  }
+);
+server.registerTool(
+  "list_decisions",
+  {
+    title: "List Recent Payment Decisions",
+    description: "List recent agent payment decisions, newest first, with payee, amount, the agent's stated reason, and for blocked ones the rule that stopped it. Filter by status to answer 'what got blocked' directly. Read-only, works offline.",
+    inputSchema: {
+      limit: z.number().int().positive().max(200).optional().describe("How many decisions to return. Default 20."),
+      status: z.enum(["ALLOW", "DENY", "all"]).optional().describe("Filter by outcome. Default all.")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ limit, status }) => {
+    const records = await core.history(5e3);
+    const rows = toRows(records, status ?? "all", limit ?? 20);
+    return {
+      content: [{ type: "text", text: renderRows(rows) }],
+      structuredContent: { count: rows.length, decisions: rows }
+    };
+  }
+);
+server.registerTool(
+  "explain_decision",
+  {
+    title: "Explain a Decision (why was this allowed or blocked)",
+    description: "Explain one decision in plain language: what was requested, what the mandate did about it, why, and the tamper-evident proof for it. Use when an operator asks why a specific payment was blocked.",
+    inputSchema: { decisionId: z.string().describe("Decision id from request_payment, list_decisions or spend_summary") },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ decisionId }) => {
+    const records = await core.history(5e3);
+    const record2 = records.find((r) => r.decisionId === decisionId);
+    if (!record2) {
+      return {
+        content: [{ type: "text", text: `No decision ${decisionId} on this chain. Run list_decisions to see the ids that exist here.` }],
+        isError: true
+      };
+    }
+    const proof = await core.getProof(decisionId);
+    const amount = typeof record2.amount === "number" ? `${record2.amount.toLocaleString("en-US")} ${record2.currency ?? ""}`.trim() : "an amount that was not recorded";
+    const head = record2.status === "ALLOW" ? `Decision ${decisionId} ALLOWED a payment of ${amount}${record2.payee ? ` to ${record2.payee}` : ""} at ${record2.ts}. It was inside every rule of the active mandate, and a signed grant was issued so a downstream executor could settle it.` : `Decision ${decisionId} BLOCKED a payment of ${amount}${record2.payee ? ` to ${record2.payee}` : ""} at ${record2.ts}. No money moved and no grant was issued.`;
+    const why = record2.status === "DENY" ? `
+
+Why: ${explainRule(record2.violatedRule, record2.payee)}` : "";
+    const said = record2.purpose ? `
+
+The agent's stated reason at the time: "${record2.purpose}".` : "";
+    const integrity = proof ? `
+
+Proof: entry #${record2.seq} in the hash-chained audit, chain currently ${proof.chainIntact ? "intact" : "BROKEN (records were altered or removed)"}. Call get_audit_proof for the full portable proof.` : "";
+    const payload = { record: record2, explanation: explainRule(record2.violatedRule, record2.payee), chainIntact: proof?.chainIntact ?? null };
+    return { content: [{ type: "text", text: head + why + said + integrity }], structuredContent: payload };
+  }
+);
+server.registerTool(
+  "sentinel_alerts",
+  {
+    title: "Sentinel Alerts (allowed, but outside this agent's pattern)",
+    description: "Predictive pattern alerts from the local audit chain: first-ever payee, amount spikes vs this agent's own history, velocity bursts, payments riding the mandate ceiling, and retries after a denial (the behavior our Model Watch benchmark measures). Deterministic and explainable, no model. Use to answer 'has anything unusual happened' before it becomes a loss.",
+    inputSchema: {
+      limit: z.number().int().positive().max(100).optional().describe("How many flagged decisions to return. Default 20.")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ limit }) => {
+    const [records, mandate] = await Promise.all([core.history(5e3), core.getMandate(subject).catch(() => null)]);
+    const flagged = sweep(records, { perTxMax: mandate?.allow?.perTxMax, limit: limit ?? 20 });
+    const text = flagged.length ? flagged.map((f) => `#${f.decisionId.slice(0, 8)} ${f.ts} ${f.status} to ${f.payee}: ${f.alerts.map((a) => `[${a.rule}] ${a.message}`).join(" ")}`).join("\n") : "No pattern alerts on this chain. Every decision so far sits inside this agent's own historical pattern.";
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: { count: flagged.length, thresholds: SENTINEL, flagged }
+    };
+  }
+);
 server.registerTool(
   "assess_action",
   {

package/dist/lib.js

@@ -248,17 +248,17 @@ var DevFidacyCore = class {
   }
   async decide(req, subject) {
     const decisionId = randomUUID();
-    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    const ts2 = (/* @__PURE__ */ new Date()).toISOString();
     const invalid = validateRequest(req);
     if (invalid) {
-      const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: invalid, ts };
+      const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: invalid, ts: ts2 };
       this.store.append(decision2);
       this.onDecision?.(decision2);
       return decision2;
     }
     const violated = evaluate(this.mandate, req, this.spent);
     if (violated) {
-      const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: violated, ts };
+      const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: violated, ts: ts2 };
       this.store.append(decision2);
       this.onDecision?.(decision2);
       return decision2;
@@ -267,7 +267,7 @@ var DevFidacyCore = class {
     if (invoice) {
       const k = `${subject}|${invoice}`;
       if (this.claimedInvoices.has(k)) {
-        const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: `duplicate_invoice:${invoice}`, ts };
+        const decision2 = { decisionId, status: "DENY", subject, mandateId: this.mandate.id, request: req, violatedRule: `duplicate_invoice:${invoice}`, ts: ts2 };
         this.store.append(decision2);
         this.onDecision?.(decision2);
         return decision2;
@@ -277,7 +277,7 @@ var DevFidacyCore = class {
     const grantPayload = { decisionId, subject, payee: req.payee, amount: req.amount, currency: req.currency, exp: Date.now() + 12e4, ...req.invoiceRef ? { invoiceRef: req.invoiceRef } : {} };
     const grantBody = Buffer.from(stableStringify(grantPayload), "utf8").toString("base64url");
     const grant = `${grantBody}.${sign(this.priv, grantBody)}`;
-    const decision = { decisionId, status: "ALLOW", subject, mandateId: this.mandate.id, request: req, grant, ts };
+    const decision = { decisionId, status: "ALLOW", subject, mandateId: this.mandate.id, request: req, grant, ts: ts2 };
     this.spent += req.amount;
     this.store.append(decision);
     this.onDecision?.(decision);
@@ -289,6 +289,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -323,6 +327,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -381,13 +389,16 @@ var FileAuditStore = class {
   append(decision) {
     const prevHash = this.head();
     const seq = this.chain.length;
-    const ts = decision.ts;
+    const ts2 = decision.ts;
     const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
-    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
-    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts2}`);
+    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts: ts2 };
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -397,6 +408,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -594,7 +613,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.4" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -754,6 +773,7 @@ function makeCore() {
       return dev.decide(req, subject);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }
@@ -771,7 +791,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.2" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.4" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -920,6 +940,202 @@ function activationBootLine() {
   }
   return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
 }
+
+// src/reporting.ts
+function withinDays(records, days, now = Date.now()) {
+  if (!Number.isFinite(days) || days <= 0) return [...records];
+  const cutoff = now - days * 864e5;
+  return records.filter((r) => {
+    const t = Date.parse(r.ts);
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+var addTo = (bucket, key, value) => {
+  bucket[key] = (bucket[key] ?? 0) + value;
+};
+function summarize(records, days, now = Date.now()) {
+  const rows = withinDays(records, days, now);
+  const out = {
+    window_days: days,
+    decisions: rows.length,
+    allowed: 0,
+    denied: 0,
+    allowed_totals: {},
+    blocked_totals: {},
+    denied_by_rule: {},
+    payees_paid: [],
+    amount_unknown: 0,
+    first_ts: rows.length ? rows[0].ts : null,
+    last_ts: rows.length ? rows[rows.length - 1].ts : null
+  };
+  const paid = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const known = typeof r.amount === "number" && Number.isFinite(r.amount);
+    if (!known) out.amount_unknown += 1;
+    const ccy = r.currency ?? "unknown";
+    if (r.status === "ALLOW") {
+      out.allowed += 1;
+      if (known) addTo(out.allowed_totals, ccy, r.amount);
+      if (r.payee) paid.add(r.payee);
+    } else {
+      out.denied += 1;
+      if (known) addTo(out.blocked_totals, ccy, r.amount);
+      addTo(out.denied_by_rule, r.violatedRule ?? "not_recorded", 1);
+    }
+  }
+  out.payees_paid = [...paid].sort();
+  return out;
+}
+var money = (totals) => {
+  const parts = Object.entries(totals).map(([ccy, v]) => `${v.toLocaleString("en-US")} ${ccy}`);
+  return parts.length ? parts.join(", ") : "0";
+};
+function renderSummary(s) {
+  if (s.decisions === 0) {
+    return `No agent payment decisions in the last ${s.window_days} day(s). The firewall is active and has nothing to report, which is the expected state until an agent attempts a payment.`;
+  }
+  const lines = [
+    `Last ${s.window_days} day(s): ${s.decisions} payment decision(s), ${s.allowed} allowed and ${s.denied} blocked before execution.`,
+    `Paid: ${money(s.allowed_totals)}${s.payees_paid.length ? ` across ${s.payees_paid.length} payee(s): ${s.payees_paid.slice(0, 8).join(", ")}${s.payees_paid.length > 8 ? ", \u2026" : ""}` : ""}.`
+  ];
+  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(", ")}.`);
+  }
+  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.`);
+  }
+  return lines.join("\n");
+}
+function toRows(records, status, limit) {
+  const filtered = status === "all" ? [...records] : records.filter((r) => r.status === status);
+  return filtered.slice(-Math.max(1, limit)).reverse().map((r) => ({
+    seq: r.seq,
+    decisionId: r.decisionId,
+    status: r.status,
+    ts: r.ts,
+    payee: r.payee,
+    amount: r.amount,
+    currency: r.currency,
+    purpose: r.purpose,
+    violatedRule: r.violatedRule,
+    invoiceRef: r.invoiceRef
+  }));
+}
+function renderRows(rows) {
+  if (!rows.length) return "No decisions match that filter yet.";
+  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 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 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("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.`;
+  if (rule.startsWith("category_not_allowed"))
+    return "The stated purpose category is not one the mandate permits for this agent.";
+  if (rule.startsWith("currency_not_allowed"))
+    return "The payment currency is not the mandate's currency.";
+  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.";
+  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.";
+  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.`;
+}
+
+// src/sentinel.ts
+var SENTINEL = {
+  /** amount >= SPIKE_FACTOR x the historical max ALLOW to the same payee. */
+  SPIKE_FACTOR: 3,
+  /** minimum prior ALLOWs to a payee before a spike is judged (else first_payee covers it). */
+  SPIKE_MIN_HISTORY: 2,
+  /** decisions within BURST_WINDOW_MS to trip velocity_burst. */
+  BURST_COUNT: 5,
+  BURST_WINDOW_MS: 10 * 6e4,
+  /** fraction of perTxMax that counts as riding the ceiling. */
+  CAP_CREEP_RATIO: 0.8,
+  /** a DENY for the same payee within this window makes a new attempt a retry. */
+  RETRY_WINDOW_MS: 30 * 6e4
+};
+var ts = (r) => {
+  const t = Date.parse(r.ts);
+  return Number.isFinite(t) ? t : 0;
+};
+function assessPattern(records, req, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const alerts = [];
+  const toPayee = records.filter((r) => r.payee === req.payee);
+  const allowedToPayee = toPayee.filter((r) => r.status === "ALLOW");
+  if (req.payee && allowedToPayee.length === 0) {
+    alerts.push({
+      rule: "first_payee",
+      severity: "warning",
+      message: `First payment ever from this agent to "${req.payee}". A swapped or lookalike vendor always looks like a first payee; worth a human glance before anything settles.`
+    });
+  }
+  if (allowedToPayee.length >= SENTINEL.SPIKE_MIN_HISTORY && typeof req.amount === "number") {
+    const maxSeen = Math.max(...allowedToPayee.map((r) => typeof r.amount === "number" ? r.amount : 0));
+    if (maxSeen > 0 && req.amount >= maxSeen * SENTINEL.SPIKE_FACTOR) {
+      alerts.push({
+        rule: "amount_spike",
+        severity: "warning",
+        message: `${req.amount.toLocaleString("en-US")} is ${(req.amount / maxSeen).toFixed(1)}x the largest amount this agent has ever paid "${req.payee}" (${maxSeen.toLocaleString("en-US")}). Inflated re-presentations of a known vendor look exactly like this.`
+      });
+    }
+  }
+  const recent = records.filter((r) => now - ts(r) <= SENTINEL.BURST_WINDOW_MS);
+  if (recent.length + 1 >= SENTINEL.BURST_COUNT) {
+    alerts.push({
+      rule: "velocity_burst",
+      severity: "warning",
+      message: `${recent.length + 1} payment decisions inside ${Math.round(SENTINEL.BURST_WINDOW_MS / 6e4)} minutes. Runaway loops and drain attempts announce themselves as bursts before they announce themselves as losses.`
+    });
+  }
+  if (typeof opts.perTxMax === "number" && opts.perTxMax > 0 && typeof req.amount === "number") {
+    if (req.amount >= opts.perTxMax * SENTINEL.CAP_CREEP_RATIO && req.amount <= opts.perTxMax) {
+      alerts.push({
+        rule: "cap_creep",
+        severity: "notice",
+        message: `${req.amount.toLocaleString("en-US")} is ${Math.round(req.amount / opts.perTxMax * 100)}% of the per-transaction ceiling. An attacker probing a mandate pays just under the cap; a human authorizing a real bill usually doesn't land this close.`
+      });
+    }
+  }
+  const recentDeny = toPayee.find((r) => r.status === "DENY" && now - ts(r) <= SENTINEL.RETRY_WINDOW_MS);
+  if (recentDeny) {
+    alerts.push({
+      rule: "retry_after_deny",
+      severity: "warning",
+      message: `This agent was DENIED a payment to "${req.payee}" ${Math.max(1, Math.round((now - ts(recentDeny)) / 6e4))} minute(s) ago (${recentDeny.violatedRule ?? "rule on record"}) and is now trying again. Our public Model Watch benchmark measures exactly this behavior; in an autonomous agent it is the pattern that precedes a loss.`
+    });
+  }
+  return alerts;
+}
+function sweep(records, opts = {}) {
+  const out = [];
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    if (!r.payee) continue;
+    const alerts = assessPattern(records.slice(0, i), { payee: r.payee, amount: r.amount }, { perTxMax: opts.perTxMax, now: ts(r) });
+    if (alerts.length) out.push({ decisionId: r.decisionId, ts: r.ts, status: r.status, payee: r.payee, alerts });
+  }
+  return out.slice(-(opts.limit ?? 20)).reverse();
+}
+function renderAlertLine(alerts) {
+  if (!alerts.length) return "";
+  const worst = alerts.some((a) => a.severity === "warning") ? "SENTINEL WARNING" : "SENTINEL NOTICE";
+  return ` [${worst}: ${alerts.map((a) => a.message).join(" Also: ")}]`;
+}
 export {
   DevFidacyCore,
   FREE_DECISIONS,
@@ -927,14 +1143,17 @@ export {
   GrantEnforcingExecutor,
   HttpFidacyCore,
   ReferenceRail,
+  SENTINEL,
   activationBootLine,
   activationGate,
+  assessPattern,
   autoProvision,
   canonInvoice,
   claimUrl,
   decisionNudge,
   ensureState,
   evaluate,
+  explainRule,
   hasEngineKey,
   httpRedeem,
   installAgeDays,
@@ -948,16 +1167,23 @@ export {
   recordAgentActive,
   recordInstall,
   remainingFree,
+  renderAlertLine,
+  renderRows,
+  renderSummary,
   requestUpgrade,
   requireHttpsBase,
   setTelemetryShell,
   sha256,
   sign,
   stableStringify,
+  summarize,
+  sweep,
+  toRows,
   trialCountdownLine,
   upgradeUrl,
   validateRequest,
   verify,
   verifyGrant,
-  weekOneBootNudge
+  weekOneBootNudge,
+  withinDays
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",