@fidacy/mcp 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.2
+
+### Patch Changes
+
+- Critical for Claude Code users: the firewall's messages now actually reach the model. MCP hosts disagree about which half of a tool result the model sees. Some surface only the text content — which is why the signed grant has always been printed there — but Claude Code surfaces ONLY `structuredContent` when a tool declares an output schema. Verified against a live Claude Code agent: on a DENY, the model received `{"status":"DENY",...}` and none of the text — no attribution, no trial countdown, no activation wall, no protection warnings. Every human-directed message now travels in both halves (`message` in the structured output mirrors the text), so the agent can relay it regardless of which half its host shows.
+
 ## 0.4.1
 
 ### Patch Changes

package/dist/config.d.ts

@@ -43,6 +43,10 @@ export interface FidacyConfig {
      * Cleared as soon as a hosted call succeeds again.
      */
     hosted_lapsed_at?: string;
+    /** Operator-provided email (opt-in). Consent to be contacted; never scraped. */
+    operator_email?: string;
+    /** The email last successfully registered, so we don't re-send every boot. */
+    registered_email?: string;
 }
 /**
  * True when the install carries an operator-set engine key (env, or the plugin's

package/dist/core.js

@@ -455,7 +455,9 @@ function readConfig() {
       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,
-      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0,
+      operator_email: typeof raw.operator_email === "string" ? raw.operator_email : void 0,
+      registered_email: typeof raw.registered_email === "string" ? raw.registered_email : void 0
     };
   } catch {
     return null;
@@ -486,7 +488,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.4.1" : "dev";
+var CLIENT_VERSION = true ? "0.5.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

@@ -466,7 +466,9 @@ function readConfig() {
       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,
-      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0,
+      operator_email: typeof raw.operator_email === "string" ? raw.operator_email : void 0,
+      registered_email: typeof raw.registered_email === "string" ? raw.registered_email : void 0
     };
   } catch {
     return null;
@@ -518,7 +520,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.4.1" : "dev";
+var CLIENT_VERSION = true ? "0.5.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -880,7 +882,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.4.1" : "dev";
+var CLIENT_VERSION2 = true ? "0.5.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -916,6 +918,46 @@ async function autoProvision() {
   }
 }
 
+// src/register.ts
+var CLIENT_VERSION3 = true ? "0.5.0" : "dev";
+function endpoint3() {
+  const base = (process.env.FIDACY_ENGINE_URL ?? "https://api.fidacy.com").replace(/\/$/, "");
+  return `${base}/v1/register`;
+}
+function looksLikeEmail(s) {
+  return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(s);
+}
+function operatorEmail(override) {
+  const raw = (override ?? process.env.FIDACY_OPERATOR_EMAIL ?? readConfig()?.operator_email ?? "").trim();
+  return raw && looksLikeEmail(raw) ? raw : null;
+}
+async function registerEmail(email, shell = "mcp") {
+  const cfg = readConfig();
+  if (!cfg) return "skipped";
+  const clean = email.trim();
+  if (!looksLikeEmail(clean)) return "skipped";
+  if (cfg.registered_email && cfg.registered_email.toLowerCase() === clean.toLowerCase()) return "skipped";
+  try {
+    const res = await fetch(endpoint3(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ anon_id: cfg.anon_id, email: clean, client_version: CLIENT_VERSION3, shell })
+    });
+    if (res.status === 429) return "rate_limited";
+    if (!res.ok) return "failed";
+    const fresh = readConfig() ?? cfg;
+    writeConfig({ ...fresh, operator_email: clean, registered_email: clean });
+    return "registered";
+  } catch {
+    return "failed";
+  }
+}
+async function autoRegister(shell = "mcp") {
+  const email = operatorEmail();
+  if (!email) return "skipped";
+  return registerEmail(email, shell);
+}
+
 // src/upgrade.ts
 function upgradeUrl() {
   const base = (process.env.FIDACY_WEB_URL ?? "https://fidacy.com").replace(/\/$/, "");
@@ -1381,7 +1423,7 @@ function renderAlertLine(alerts) {
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.4.1" : "dev";
+var SERVER_VERSION = true ? "0.5.0" : "dev";
 var bootClaim = claimUrl();
 var server = new McpServer(
   // The commercial identity. `name` is the stable slug hosts key on; `title` is
@@ -1415,15 +1457,30 @@ server.registerTool(
       status: z.enum(["ALLOW", "DENY"]),
       decisionId: z.string(),
       grant: z.string().optional(),
-      violatedRule: z.string().optional()
+      violatedRule: z.string().optional(),
+      /**
+       * The full human-directed message, duplicated from the text content ON
+       * PURPOSE. Hosts disagree about which half of a tool result the model
+       * sees: some surface only the text (which is why the grant is printed
+       * there), and Claude Code surfaces ONLY structuredContent when an
+       * outputSchema is declared — verified live 2026-07-25, where the model
+       * received exactly {"status":"DENY",...} and none of the text. Anything
+       * that must reach the model must therefore travel in BOTH halves.
+       */
+      message: z.string()
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
   },
   async (args) => {
     const gate = activationGate();
     if (gate) {
-      const out2 = { status: "DENY", decisionId: "activation_required", violatedRule: "activation_required" };
       const halted = protectionWarning(decisionsUsed()) ?? gate.message;
+      const out2 = {
+        status: "DENY",
+        decisionId: "activation_required",
+        violatedRule: "activation_required",
+        message: halted
+      };
       return { content: [{ type: "text", text: halted }], structuredContent: out2 };
     }
     const req = args;
@@ -1434,7 +1491,6 @@ server.registerTool(
     } catch {
     }
     const d = await core.decide(req, subject);
-    const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
     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.` : ""}`;
@@ -1443,6 +1499,7 @@ ${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}
     const countdown = trialCountdownLine();
     const lapse = isHostedLapsed() ? protectionWarning(decisionsUsed()) : "";
     const human = [badge, base, nudge, countdown, lapse].filter(Boolean).join(" ");
+    const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule, message: human };
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -1764,6 +1821,22 @@ Your local protection keeps working meanwhile; your usage history migrates to th
     };
   }
 );
+server.registerTool(
+  "register_email",
+  {
+    title: "Register operator email (opt-in)",
+    description: "Register the operator's email so their agent's protection history can attach to a real Fidacy account and Fidacy can reach them. ONLY call this when the human operator has explicitly given their email and agreed to be contacted \u2014 it is consent-based. Does not create an account or move money.",
+    inputSchema: { email: z.string().describe("The operator's email, exactly as they gave it.") },
+    outputSchema: { registered: z.boolean(), message: z.string() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async ({ email }) => {
+    const outcome = await registerEmail(String(email ?? ""), "mcp");
+    const ok = outcome === "registered" || outcome === "skipped";
+    const message = outcome === "registered" ? `Registered ${email}. This install's protection history is now tied to that email; Fidacy may contact the operator. To finish creating the free account, the operator can open fidacy.com/claim.` : outcome === "skipped" ? `Already registered, or the email was empty/malformed \u2014 nothing to do.` : outcome === "rate_limited" ? `Too many registrations from this network right now; try again shortly.` : `Could not reach Fidacy to register; the install keeps working locally. Try again later.`;
+    return { content: [{ type: "text", text: message }], structuredContent: { registered: ok, message } };
+  }
+);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -1773,6 +1846,7 @@ async function main() {
     void flush();
   });
   void autoProvision();
+  void autoRegister("mcp");
   console.error(
     renderBanner({
       version: SERVER_VERSION,

package/dist/lib.d.ts

@@ -4,8 +4,9 @@ export { ensureState, readConfig } from "./config.js";
 export { requestUpgrade, upgradeUrl } from "./upgrade.js";
 export { autoProvision } from "./provision.js";
 export { recordInstall, recordAgentActive, setTelemetryShell, flush as flushTelemetry } from "./telemetry.js";
-export { decisionNudge, weekOneBootNudge, nudgeOnce, installAgeDays, claimUrl, noKeyCta } from "./nudges.js";
-export { FREE_DECISIONS, activationGate, activationBootLine, trialCountdownLine, hasEngineKey, remainingFree } from "./activation.js";
+export { decisionNudge, weekOneBootNudge, nudgeOnce, installAgeDays, claimUrl, noKeyCta, hostedWallCta } from "./nudges.js";
+export { FREE_DECISIONS, activationGate, activationBootLine, trialCountdownLine, hasEngineKey, remainingFree, decisionsUsed } from "./activation.js";
+export { BRAND, protectionBadge, protectionWarning, protectionBootLine, protectionState, markHostedLapsed, clearHostedLapsed, isHostedLapsed, } from "./protection.js";
 export { summarize, renderSummary, toRows, renderRows, explainRule, withinDays } from "./reporting.js";
 export type { SpendSummary, DecisionRow } from "./reporting.js";
 export { assessPattern, sweep, renderAlertLine, SENTINEL } from "./sentinel.js";

package/dist/lib.js

@@ -589,7 +589,9 @@ function readConfig() {
       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,
-      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0
+      hosted_lapsed_at: typeof raw.hosted_lapsed_at === "string" ? raw.hosted_lapsed_at : void 0,
+      operator_email: typeof raw.operator_email === "string" ? raw.operator_email : void 0,
+      registered_email: typeof raw.registered_email === "string" ? raw.registered_email : void 0
     };
   } catch {
     return null;
@@ -641,7 +643,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.4.1" : "dev";
+var CLIENT_VERSION = true ? "0.5.0" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -829,7 +831,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.4.1" : "dev";
+var CLIENT_VERSION2 = true ? "0.5.0" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -924,6 +926,20 @@ function decisionNudge(status, violatedRule, upgradeToolName) {
   }
   return null;
 }
+function hostedWallCta(feature, billing) {
+  const noun = feature === "anchor" ? "Bitcoin-anchored proofs" : "server-signed verdicts";
+  if (hasEngineKey()) {
+    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 ${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`;
+  if (nudgeOnce("hosted_wall")) {
+    return `You've used this install's free allowance for ${noun} \u2014 the proofs anyone can re-verify at fidacy.com/verify, court-grade, not a local-only check. Keep them flowing: for your operator, ${cta}.`;
+  }
+  return `Free allowance for ${noun} reached. For your operator: ${cta}.`;
+}
 function noKeyCta() {
   const url = claimUrl();
   return url ? `free in ~1 min for your operator: open ${url} (this install's history migrates), or set FIDACY_ENGINE_API_KEY if you already have one` : `free in ~1 min: call the upgrade tool (your history migrates), or set FIDACY_ENGINE_API_KEY if you already have one`;
@@ -977,6 +993,74 @@ function activationBootLine() {
   return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free 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 state = protectionState(decisionsUsed2, keyOverride);
+  const left = Math.max(0, FREE_DECISIONS - decisionsUsed2);
+  switch (state) {
+    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, then this agent's payments STOP DEAD. Every payment it attempts after that is refused \u2014 invoices unpaid, workflows broken, at 3am with nobody watching. And the operators who "fix" it by ripping the firewall out end up with an agent nobody is checking at all, which is how a prompt-injected agent wires money to a stranger. Keep it alive, free, in ~2 minutes: ${where()} \u2014 no card, this install's block history moves with you, plus ${FREE_MONTHLY_VERDICTS} verified payments every month.`;
+    case "halted":
+      return `\u26D4 ${BRAND} IS NOT ACTIVATED \u2014 YOUR AGENT CAN NO LONGER PAY ANYTHING. Every payment it attempts is being refused right now: invoices go unpaid, subscriptions lapse, jobs fail silently. The firewall failed closed after ${FREE_DECISIONS} free decisions, which is the safe direction \u2014 but it is YOUR agent that is stopped until you act. And do not "fix" it by removing the firewall: an agent with nothing checking it is exactly how a stolen key or an injected instruction moves real money you never get back. Activate free in ~2 minutes at ${where()}: no card, your block history moves with you, ${FREE_MONTHLY_VERDICTS} verified payments every month.`;
+    case "unproven":
+      return `\u26D4 ${BRAND}: YOUR AGENT IS EXPOSED RIGHT NOW. The monthly allowance is spent, so the checks that ask WHO is spending are OFF: agent identity is no longer verified, a revoked or stolen agent key is no longer detected, and behavioural anomalies are no longer caught. Local rules still block the wrong payee and the over-cap amount \u2014 but a compromised or prompt-injected agent that stays inside your own allowlist and under your own cap now pays out unchallenged. That is real money, irreversible, with no signed evidence to recover it or hand an insurer. Turn the checks back on: https://app.fidacy.com/billing \u2014 pay-as-you-go, no plan, from $0.04 per payment checked. One prevented payment pays for years of it.`;
+    case "protected_keyed":
+      return null;
+  }
+}
+function protectionBootLine(decisionsUsed2) {
+  const state = protectionState(decisionsUsed2);
+  switch (state) {
+    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 ` \u26D4 EXPOSED \u2014 identity, revocation and anomaly checks are OFF (allowance spent). A stolen or hijacked agent inside your caps now pays out unchallenged: 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];
@@ -1173,6 +1257,7 @@ function renderAlertLine(alerts) {
   return ` [${worst}: ${alerts.map((a) => a.message).join(" Also: ")}]`;
 }
 export {
+  BRAND,
   DevFidacyCore,
   FREE_DECISIONS,
   FileAuditStore,
@@ -1186,19 +1271,28 @@ export {
   autoProvision,
   canonInvoice,
   claimUrl,
+  clearHostedLapsed,
   decisionNudge,
+  decisionsUsed,
   ensureState,
   evaluate,
   explainRule,
   flush as flushTelemetry,
   hasEngineKey,
+  hostedWallCta,
   httpRedeem,
   installAgeDays,
+  isHostedLapsed,
   loadOrGenerateKeyPair,
   lookalikePayee,
   makeCore,
+  markHostedLapsed,
   noKeyCta,
   nudgeOnce,
+  protectionBadge,
+  protectionBootLine,
+  protectionState,
+  protectionWarning,
   publicKeyPem,
   readConfig,
   recordAgentActive,

package/dist/register.d.ts

@@ -0,0 +1,14 @@
+/** The email the operator explicitly provided, if any (env wins over config). */
+export declare function operatorEmail(override?: string): string | null;
+/**
+ * Register the operator's email against this install. Explicit — call it only
+ * when the operator SUPPLIED the email. Persists `registered_email` on success so
+ * we do not re-send every boot. Returns the outcome for tests/logs.
+ */
+export declare function registerEmail(email: string, shell?: string): Promise<"registered" | "skipped" | "rate_limited" | "failed">;
+/**
+ * Boot-time auto-register: if the operator set FIDACY_OPERATOR_EMAIL (or the
+ * config field) and we have not sent it yet, register in the background. NEVER
+ * awaited on the startup path — fire and forget, exactly like autoProvision.
+ */
+export declare function autoRegister(shell?: string): Promise<"registered" | "skipped" | "rate_limited" | "failed">;

package/package.json

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