@fidacy/mcp 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -85,3 +85,13 @@ semantic versioning.
 - Onboarding: first-run `~/.fidacy/config.json` now writes the mandate template
   explicitly (payees/categories/currency/caps) — adding a trusted payee is a
   visible one-line edit; friendlier first-boot message (no more "dev mode" scare).
+
+## 0.1.11 — 2026-07-02
+
+- Upgrade micro-triggers, elegant by doctrine: fire only at value-proven moments
+  (first block, first duplicate-invoice/BEC catch, 10th gated action, one week
+  protected), each ONCE per install ever (persisted in config.json) — the free
+  tier stays fully usable in silence. The 0.1.10 every-DENY nudge is replaced.
+- verify_mandate/get_audit_proof gain one informational closing line each;
+  assess_action's missing-key error now offers the free-key path.
+- config.json gains created_at + nudge/decision state (preserved on read).

package/dist/core.js

@@ -337,7 +337,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // 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
     };
   } catch {
     return null;
@@ -357,7 +362,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();

package/dist/index.js

@@ -345,7 +345,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // 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
     };
   } catch {
     return null;
@@ -363,7 +368,8 @@ function ensureState() {
     anon_id: randomUUID2(),
     tier: "free",
     api_key: null,
-    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 }
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
     writeConfig(config);
@@ -385,7 +391,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -609,7 +615,7 @@ async function postOnce(fetchImpl, url, headers, payload, timeoutMs) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.10" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.11" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -656,6 +662,55 @@ function requestUpgrade() {
   return { url: upgradeUrl(), anonId: anonId2 };
 }
 
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
@@ -689,8 +744,10 @@ server.registerTool(
     const req = args;
     const d = await core.decide(req, subject);
     const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
-    const human = 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:
-${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. Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the upgrade tool.`;
+    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:
+${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.`;
+    const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
+    const human = nudge ? `${base} ${nudge}` : base;
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -705,7 +762,8 @@ server.registerTool(
   async () => {
     const m = await core.getMandate(subject);
     const payload = { mandate: m, fidacyPublicKey: core.publicKey() };
-    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload };
+    const text = JSON.stringify(payload, null, 2) + "\n\nThis mandate is local (free tier). Hosted mandates add team governance and server-signed verdicts \u2014 the upgrade tool starts a free account.";
+    return { content: [{ type: "text", text }], structuredContent: payload };
   }
 );
 server.registerTool(
@@ -719,7 +777,8 @@ server.registerTool(
   async ({ decisionId }) => {
     const proof = await core.getProof(decisionId);
     if (!proof) return { content: [{ type: "text", text: `No proof found for ${decisionId}` }], isError: true };
-    return { content: [{ type: "text", text: JSON.stringify(proof, null, 2) }], structuredContent: proof };
+    const text = JSON.stringify(proof, null, 2) + "\n\nThis proof lives on this machine. On a free hosted account the chain is anchored to Bitcoin \u2014 verifiable by anyone, forever, even against Fidacy (the upgrade tool starts it).";
+    return { content: [{ type: "text", text }], structuredContent: proof };
   }
 );
 server.registerTool(
@@ -745,7 +804,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "assess_action requires FIDACY_ENGINE_API_KEY (an fky_live_/fky_test_ key with assess:write). Set it to enable signed verdicts."
+            text: "assess_action needs an engine key \u2014 free in about a minute: call the upgrade tool (your usage history migrates), or set FIDACY_ENGINE_API_KEY if you already have one."
           }
         ],
         isError: true
@@ -805,7 +864,8 @@ async function main() {
   void autoProvision();
   const verdictHint = process.env.FIDACY_ENGINE_API_KEY ? "" : " Set FIDACY_ENGINE_API_KEY to enable verdicts (assess_action).";
   const tierHint = state.firstRun ? " First run: free local tier active (deny-unknown payee + cap). Add trusted payees in ~/.fidacy/config.json." : ` Tier: ${state.config.tier} (local-first).`;
-  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint);
+  const weekNudge = weekOneBootNudge("upgrade") ?? "";
+  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint + weekNudge);
 }
 main().catch((e) => {
   console.error("[fidacy] fatal:", e);

package/dist/lib.js

@@ -464,7 +464,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // 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
     };
   } catch {
     return null;
@@ -482,7 +487,8 @@ function ensureState() {
     anon_id: randomUUID3(),
     tier: "free",
     api_key: null,
-    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 }
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
     writeConfig(config);
@@ -504,7 +510,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.11" : "dev";
 var currentShell = "mcp";
 function setTelemetryShell(shell) {
   currentShell = shell;
@@ -627,7 +633,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.10" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.11" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -661,6 +667,55 @@ async function autoProvision() {
     return "failed";
   }
 }
+
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
 export {
   DevFidacyCore,
   FileAuditStore,
@@ -669,12 +724,15 @@ export {
   ReferenceRail,
   autoProvision,
   canonInvoice,
+  decisionNudge,
   ensureState,
   evaluate,
   httpRedeem,
+  installAgeDays,
   loadOrGenerateKeyPair,
   lookalikePayee,
   makeCore,
+  nudgeOnce,
   publicKeyPem,
   readConfig,
   recordAgentActive,
@@ -688,5 +746,6 @@ export {
   upgradeUrl,
   validateRequest,
   verify,
-  verifyGrant
+  verifyGrant,
+  weekOneBootNudge
 };

package/package.json

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