@fidacy/mcp 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- Every block is now credited, and every gap is now felt. A denied payment answers with `🛡 Fidacy AI Agent Firewall blocked this payment. Your agent was protected.` — the product's most valuable moment, said in the operator's language, with no upsell attached to it. Around that, the install now reports one honest protection state at boot and on the responses that matter: covered, about to halt, halted, or blocking-but-no-longer-provable. Each state names the brand, states the consequence, and gives one route forward: the free rung (free key, 300 signed verdicts a month) before the paid one (pay-as-you-go from $0.04).
+
+  What it deliberately does NOT do is tell you your agent is unprotected while the local firewall is still denying payments. This product blocks or halts; it never quietly stops defending. When the anonymous trial runs out the copy says the true and more urgent thing — your agent cannot pay, it is frozen, not exposed — and when a paid allowance runs out it says that your blocks continue but stop being provable to an auditor, insurer or counterparty. A security tool that inflates its own alarm is the one thing we cannot ship.
+
+  An install that lapses and stays wired in keeps being told, across restarts, that its blocks are no longer provable and how to restore them.
+
 ## 0.3.4
 
 ### Patch Changes

package/dist/config.d.ts

@@ -36,6 +36,13 @@ export interface FidacyConfig {
     nudges?: Partial<Record<string, boolean>>;
     /** Payment-gate decisions taken on this install (milestone nudges). */
     decisions_count?: number;
+    /**
+     * ISO timestamp of when the hosted allowance last ran out. Persisted so the
+     * "your blocks are no longer provable" warning survives restarts: an install
+     * that lapsed but is still wired in is the highest-intent audience we have.
+     * Cleared as soon as a hosted call succeeds again.
+     */
+    hosted_lapsed_at?: string;
 }
 /**
  * True when the install carries an operator-set engine key (env, or the plugin's

package/dist/core.js

@@ -454,7 +454,8 @@ function readConfig() {
       // reset every once-per-install nudge into an every-time nag.
       created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
       nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
-      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0,
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
     };
   } catch {
     return null;
@@ -485,7 +486,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.3.4" : "dev";
+var CLIENT_VERSION = true ? "0.4.0" : "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

@@ -465,7 +465,8 @@ function readConfig() {
       // reset every once-per-install nudge into an every-time nag.
       created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
       nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
-      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0,
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
     };
   } catch {
     return null;
@@ -517,7 +518,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.3.4" : "dev";
+var CLIENT_VERSION = true ? "0.4.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -879,7 +880,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.3.4" : "dev";
+var CLIENT_VERSION2 = true ? "0.4.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -989,9 +990,9 @@ function decisionNudge(status, violatedRule, upgradeToolName) {
 function hostedWallCta(feature, billing) {
   const noun = feature === "anchor" ? "Bitcoin-anchored proofs" : "server-signed verdicts";
   if (hasEngineKey()) {
-    const where = billing?.billingUrl ?? "https://app.fidacy.com/billing";
+    const where2 = billing?.billingUrl ?? "https://app.fidacy.com/billing";
     const what = billing?.reason === "spending_cap_reached" ? `This account hit the monthly spending cap you set, so ${noun} are paused.` : billing?.detail ?? `This account's included ${noun} for the month are used up.`;
-    return `${what} The local firewall keeps deciding and blocking as normal \u2014 this only pauses ${noun}. For your operator: resolve it at ${where}. Pay-as-you-go needs no plan and starts at $0.04 per verdict, dropping to $0.025 past 50k and $0.015 past 250k; committed plans price below that curve.`;
+    return `${what} The local firewall keeps deciding and blocking as normal \u2014 this only pauses ${noun}. For your operator: resolve it at ${where2}. Pay-as-you-go needs no plan and starts at $0.04 per verdict, dropping to $0.025 past 50k and $0.015 past 250k; committed plans price below that curve.`;
   }
   const url = claimUrl();
   const cta = url ? `open ${url} \u2014 free account, this install's history migrates` : `call the upgrade tool \u2014 free account, your history migrates`;
@@ -1044,6 +1045,74 @@ function trialCountdownLine(keyOverride) {
   return ` [fidacy] ${left} free anonymous decision${left === 1 ? "" : "s"} left on this install before the firewall requires activation. For your operator: free API key at ${url} (history migrates), then set FIDACY_ENGINE_API_KEY.`;
 }
 
+// src/protection.ts
+var BRAND = "Fidacy AI Agent Firewall";
+var FREE_MONTHLY_VERDICTS = 300;
+function markHostedLapsed() {
+  const cfg = readConfig();
+  if (!cfg || cfg.hosted_lapsed_at) return;
+  cfg.hosted_lapsed_at = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+}
+function clearHostedLapsed() {
+  const cfg = readConfig();
+  if (!cfg?.hosted_lapsed_at) return;
+  delete cfg.hosted_lapsed_at;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+}
+function isHostedLapsed() {
+  return Boolean(readConfig()?.hosted_lapsed_at);
+}
+function protectionState(decisionsUsed2, keyOverride) {
+  if (hasEngineKey(keyOverride)) return isHostedLapsed() ? "unproven" : "protected_keyed";
+  if (decisionsUsed2 >= FREE_DECISIONS) return "halted";
+  return FREE_DECISIONS - decisionsUsed2 <= 5 ? "protected_low" : "protected_trial";
+}
+function where() {
+  return claimUrl() ?? "https://fidacy.com/claim";
+}
+function protectionBadge() {
+  return `\u{1F6E1} ${BRAND} blocked this payment. Your agent was protected.`;
+}
+function protectionWarning(decisionsUsed2, keyOverride) {
+  const state2 = protectionState(decisionsUsed2, keyOverride);
+  const left = Math.max(0, FREE_DECISIONS - decisionsUsed2);
+  switch (state2) {
+    case "protected_trial":
+      return null;
+    // working and nothing is expiring soon: silence is the respect.
+    case "protected_low":
+      return `\u26A0 ${BRAND}: ${left} free decision${left === 1 ? "" : "s"} left on this install. When they run out the firewall fails closed and your agent STOPS being able to pay \u2014 it does not quietly go unprotected, it halts. Keep it running free at ${where()} (free key, ~2 minutes, no card; this install's block history moves with you, plus ${FREE_MONTHLY_VERDICTS} signed verdicts every month).`;
+    case "halted":
+      return `\u26D4 ${BRAND} is NOT ACTIVATED and your agent can no longer pay. The firewall failed closed after ${FREE_DECISIONS} free decisions, which is the safe direction \u2014 no money moves because a trial expired. Your agent is frozen, not exposed. Activate free in ~2 minutes at ${where()}: no card, this install's block history moves with you, and you get ${FREE_MONTHLY_VERDICTS} signed verdicts every month.`;
+    case "unproven":
+      return `\u26A0 ${BRAND}: your agent is still being blocked locally, but its blocks are no longer PROVABLE \u2014 the monthly signed-verdict allowance is spent, so nothing new can be shown to an auditor, insurer or counterparty. Restore proof at https://app.fidacy.com/billing (pay-as-you-go, no plan, from $0.04 per verdict).`;
+    case "protected_keyed":
+      return null;
+  }
+}
+function protectionBootLine(decisionsUsed2) {
+  const state2 = protectionState(decisionsUsed2);
+  switch (state2) {
+    case "halted":
+      return ` \u26D4 NOT ACTIVATED \u2014 your agent cannot pay until you activate at ${where()} (free, no card).`;
+    case "protected_low":
+      return ` \u26A0 ${Math.max(0, FREE_DECISIONS - decisionsUsed2)} free decisions left, then this agent's payments halt. Free key: ${where()}`;
+    case "unproven":
+      return ` \u26A0 Blocking locally, but blocks are no longer provable \u2014 allowance spent. Restore at https://app.fidacy.com/billing`;
+    case "protected_trial":
+      return ` ${BRAND} active \u2014 ${decisionsUsed2}/${FREE_DECISIONS} free decisions used.`;
+    case "protected_keyed":
+      return ` ${BRAND} active and signing \u2014 blocks are provable to third parties.`;
+  }
+}
+
 // src/reporting.ts
 function withinDays(records, days, now = Date.now()) {
   if (!Number.isFinite(days) || days <= 0) return [...records];
@@ -1312,7 +1381,7 @@ function renderAlertLine(alerts) {
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.3.4" : "dev";
+var SERVER_VERSION = true ? "0.4.0" : "dev";
 var bootClaim = claimUrl();
 var server = new McpServer(
   // The commercial identity. `name` is the stable slug hosts key on; `title` is
@@ -1354,7 +1423,8 @@ server.registerTool(
     const gate = activationGate();
     if (gate) {
       const out2 = { status: "DENY", decisionId: "activation_required", violatedRule: "activation_required" };
-      return { content: [{ type: "text", text: gate.message }], structuredContent: out2 };
+      const halted = protectionWarning(decisionsUsed()) ?? gate.message;
+      return { content: [{ type: "text", text: halted }], structuredContent: out2 };
     }
     const req = args;
     let sentinelAlerts = [];
@@ -1368,9 +1438,11 @@ server.registerTool(
     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 badge = d.status === "DENY" ? protectionBadge() : "";
     const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
     const countdown = trialCountdownLine();
-    const human = [base, nudge, countdown].filter(Boolean).join(" ");
+    const lapse = isHostedLapsed() ? protectionWarning(decisionsUsed()) : "";
+    const human = [badge, base, nudge, countdown, lapse].filter(Boolean).join(" ");
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -1537,6 +1609,7 @@ server.registerTool(
         { kind, mandate, mandateType, idempotencyKey, spendingMandate, a2a },
         { engineUrl, apiKey }
       );
+      clearHostedLapsed();
       return {
         content: [{ type: "text", text: `${r.decision} (score ${r.score}) signed by ${r.signingKeyId}` }],
         structuredContent: r
@@ -1544,6 +1617,7 @@ server.registerTool(
     } catch (e) {
       if (e instanceof AssessError) {
         if (e.status === 402) {
+          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(",") + ")" : "";
@@ -1609,6 +1683,7 @@ server.registerTool(
     } catch (e) {
       if (e instanceof AssessError) {
         if (e.status === 402) {
+          markHostedLapsed();
           return { content: [{ type: "text", text: hostedWallCta("anchor", e.billing) }], isError: true };
         }
         return { content: [{ type: "text", text: `ANCHOR ${e.status}: ${e.type}` }], isError: true };
@@ -1704,7 +1779,11 @@ async function main() {
       tier: state.config.tier,
       firstRun: state.firstRun,
       claim: claimUrl(),
-      weekNudge: weekOneBootNudge("upgrade") ?? ""
+      // The protection state leads the banner nudge slot: an operator who reads
+      // one line of our output should learn whether this agent is covered, about
+      // to halt, or blocking without being able to prove it. The week-one note
+      // only shows when there is no protection gap worth naming.
+      weekNudge: protectionBootLine(decisionsUsed()) ?? weekOneBootNudge("upgrade") ?? ""
     })
   );
 }

package/dist/lib.js

@@ -588,7 +588,8 @@ function readConfig() {
       // reset every once-per-install nudge into an every-time nag.
       created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
       nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
-      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0,
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
     };
   } catch {
     return null;
@@ -640,7 +641,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.3.4" : "dev";
+var CLIENT_VERSION = true ? "0.4.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -828,7 +829,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.3.4" : "dev";
+var CLIENT_VERSION2 = true ? "0.4.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");

package/dist/protection.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PROTECTION STATE — the one place that decides what the operator is told about
+ * the state of their agent's defence, and the only place allowed to name the
+ * product to them.
+ *
+ * Doctrine (the commercial engine, 2026-07-24): every free thing is a lure to
+ * the paid thing, so every save must be ATTRIBUTED and every gap must be FELT.
+ * A block the operator never hears about buys us nothing; a lapse they never
+ * notice converts nobody.
+ *
+ * The one line we will not cross: this product never silently stops protecting.
+ * It either blocks the payment or it halts the agent. So we never claim "your
+ * agent is unprotected" while the local firewall is still denying — that would
+ * contradict the boot banner two lines above it, and a security vendor caught
+ * inflating its own alarm loses the only thing it sells. The states below are
+ * written to be maximally urgent AND literally true, which is also the version
+ * that survives a customer reading the source (ours is public).
+ *
+ *   protected_trial    local firewall on, anonymous, trial decisions remain
+ *   protected_low      same, but 5 or fewer left — the wall is announced
+ *   halted             anonymous trial spent: the firewall FAILS CLOSED, so the
+ *                      agent cannot pay at all until it is activated
+ *   protected_keyed    activated: local blocking + the monthly signed-verdict
+ *                      allowance
+ *   unproven           activated but the hosted allowance is gone: the agent is
+ *                      STILL blocked locally, and its blocks stopped being
+ *                      provable to anyone outside this machine
+ */
+/** The commercial name. Coined on every surface an operator can read. */
+export declare const BRAND = "Fidacy AI Agent Firewall";
+/** Free signed verdicts included every month on a (free) account. */
+export declare const FREE_MONTHLY_VERDICTS = 300;
+export type ProtectionState = "protected_trial" | "protected_low" | "halted" | "protected_keyed" | "unproven";
+/**
+ * Remember that the hosted allowance ran out, so the warning survives restarts.
+ * "Stopped paying but still installed" is precisely the state that must keep
+ * nagging — it is the highest-intent audience there is: they already wired us in.
+ */
+export declare function markHostedLapsed(): void;
+/** A hosted call succeeded again — the gap closed, so stop warning about it. */
+export declare function clearHostedLapsed(): void;
+export declare function isHostedLapsed(): boolean;
+export declare function protectionState(decisionsUsed: number, keyOverride?: string): ProtectionState;
+/**
+ * The attribution line that rides EVERY block. This is the product's single most
+ * valuable sentence: the moment it just earned its keep, said in the operator's
+ * language, with the name we want them to repeat. It is never a nag — a save is
+ * not the moment to sell, it is the moment to be credited.
+ */
+export declare function protectionBadge(): string;
+/**
+ * The gap warning, escalating by state. Null when there is nothing true to warn
+ * about (an activated install inside its allowance is simply working).
+ *
+ * Every branch names the brand, states the CONSEQUENCE in the operator's terms,
+ * and gives exactly one route forward — free first, paid second, in that order,
+ * because the free rung is what makes the paid rung legible.
+ */
+export declare function protectionWarning(decisionsUsed: number, keyOverride?: string): string | null;
+/**
+ * One line for the boot banner: what state this install is in, before anything
+ * happens. An operator who reads nothing else reads this.
+ */
+export declare function protectionBootLine(decisionsUsed: number): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "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)",