@fidacy/mcp 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.5
+
+TypeScript declarations ship in the package. Every entrypoint (., ./assess,
+./core, ./lib) now resolves its own .d.ts through the exports map, with the
+internal engine types inlined under dist/firewall/ so the tarball typechecks
+with zero extra installs. No runtime changes.
+
 ## 0.2.0
 
 Activation gate: anonymous installs now get 20 free firewall decisions, then

package/dist/activation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ACTIVATION GATE — the anonymous trial that ends in a free API key.
+ *
+ * Doctrine: the local firewall is free forever, but ANONYMOUS is a trial, not a
+ * home. An install gets FREE_DECISIONS payment-gate decisions with no key; after
+ * that the firewall FAILS CLOSED (every request_payment is denied with
+ * `activation_required`) until the operator activates it with a free API key
+ * from the claim page. Fail-closed is the safe direction for a firewall — no
+ * money ever moves because a trial expired — and the deny message is the one
+ * surface an agent reliably relays to its human.
+ *
+ * Activation signal: FIDACY_ENGINE_API_KEY (env, or the plugin's engineApiKey
+ * config). Deliberately NOT config.json's auto-provisioned api_key — that one is
+ * granted silently in the background for attribution and proves nothing about a
+ * human ever visiting the dashboard. Setting the env var is exactly the wiring a
+ * real client needs anyway (it powers assess_action / anchor_artifact).
+ */
+export declare const FREE_DECISIONS = 20;
+/** True when the install carries an operator-set engine key (env or shell config). */
+export declare function hasEngineKey(keyOverride?: string): boolean;
+/**
+ * Payment-gate decisions taken so far on this install: the on-disk counter OR
+ * the in-process one, whichever is higher. The in-process floor is what keeps
+ * the gate fail-CLOSED when storage breaks: with an unreadable/corrupt
+ * config.json or a read-only disk the on-disk counter freezes at 0, and
+ * without the floor the trial would silently become unlimited.
+ */
+export declare function decisionsUsed(): number;
+/** Free anonymous decisions left before the gate closes. */
+export declare function remainingFree(): number;
+/**
+ * The gate check, to run BEFORE deciding a payment. Null ⇒ proceed normally.
+ * Non-null ⇒ do NOT decide; return the message as a DENY with violatedRule
+ * `activation_required`. Records upgrade_intent so every gate hit is measurable
+ * in the funnel (installs that reached the wall vs installs that claimed).
+ */
+export declare function activationGate(keyOverride?: string): {
+    message: string;
+} | null;
+/**
+ * Countdown line appended to normal decision responses while unactivated. Fires
+ * on EVERY decision once 5 or fewer remain (a fair wall is announced, not
+ * sprung), and marks the final free decision explicitly. Null when keyed, when
+ * plenty of trial remains, or when the count is unknowable (no persisted config
+ * means the counter never advances, so no wall is coming either).
+ */
+export declare function trialCountdownLine(keyOverride?: string): string | null;
+/** One boot-banner sentence describing trial state; null when keyed. */
+export declare function activationBootLine(): string | null;

package/dist/artifacts.d.ts

@@ -0,0 +1,44 @@
+export declare const ARTIFACT_KINDS: readonly ["contract", "invoice", "prescription", "claim", "document", "image", "audio", "video", "conversation", "custom"];
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+export interface AnchorResult {
+    artifactId: string;
+    kind: string;
+    sha256: string;
+    subject: string;
+    label: string | null;
+    ts: string;
+    digest: string;
+    audit: {
+        seq: number;
+        hash: string;
+    };
+    anchor: {
+        status: string;
+    };
+    receipt: string;
+    [k: string]: unknown;
+}
+/** SHA-256 (hex) of a file, streamed from disk. The content never leaves the machine. */
+export declare function hashFile(path: string): Promise<string>;
+/** Register a locally-computed hash on the anchored audit chain. */
+export declare function anchorArtifact(params: {
+    sha256: string;
+    kind: ArtifactKind;
+    label?: string;
+    subject?: string;
+}, cfg: {
+    engineUrl: string;
+    apiKey: string;
+}): Promise<AnchorResult>;
+/** Look up whether a hash was anchored by this org, newest first. */
+export declare function findArtifacts(sha256: string, cfg: {
+    engineUrl: string;
+    apiKey: string;
+}): Promise<{
+    artifacts: Array<Record<string, unknown>>;
+}>;
+/** Fetch one artifact with its chain record and covering Bitcoin checkpoint. */
+export declare function getArtifact(id: string, cfg: {
+    engineUrl: string;
+    apiKey: string;
+}): Promise<Record<string, unknown>>;

package/dist/assess.d.ts

@@ -0,0 +1,86 @@
+export type AssessKind = "ap2_payment" | "message_send" | "voice_call" | "custom" | "claim_document";
+export interface AssessParams {
+    /** Action kind. Defaults to `ap2_payment`. */
+    kind?: AssessKind;
+    /** The action/mandate object for this kind. */
+    mandate: unknown;
+    /** Optional explicit mandate type. The engine derives it otherwise. */
+    mandateType?: string;
+    /** Optional A2A correlation block. Adds the `A2A-Version` header when present. */
+    a2a?: {
+        task_id: string;
+    };
+    /** Optional spending mandate. Sent as snake_case `spending_mandate`. */
+    spendingMandate?: unknown;
+    /** Optional idempotency key. Sent as snake_case `idempotency_key`. Enables retry. */
+    idempotencyKey?: string;
+}
+export interface AssessResult {
+    decision: "approve" | "review" | "deny";
+    score: number;
+    assessmentId: string;
+    mandateId: string;
+    riskPayloadJws: string;
+    riskPayload: Record<string, unknown>;
+    signingKeyId: string;
+    signals: Record<string, unknown>;
+    mandate: Record<string, unknown>;
+    outcome: Record<string, unknown>;
+    billing?: Record<string, unknown>;
+    spend_guard?: Record<string, unknown>;
+    a2a?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface RejectionReason {
+    key: string;
+    category?: string;
+    message?: string;
+    description?: string;
+}
+/**
+ * Typed error from the engine. `message` is STATIC and never contains the key or
+ * request body. `type` is the stable engine error code (or a client code), and
+ * `status` is the HTTP status (0 for network/timeout).
+ */
+export declare class AssessError extends Error {
+    readonly type: string;
+    readonly status: number;
+    readonly details?: unknown;
+    readonly rejection_reasons?: RejectionReason[];
+    constructor(opts: {
+        type: string;
+        status: number;
+        details?: unknown;
+        rejection_reasons?: RejectionReason[];
+    });
+}
+export interface AssessConfig {
+    /** Base URL of the engine, e.g. `https://api.fidacy.com`. Trailing slashes stripped. */
+    engineUrl: string;
+    /** API key (`fky_live_…`/`fky_test_…`) with scope `assess:write`. Never logged. */
+    apiKey: string;
+    /** Custom fetch (tests, edge runtimes). Default: `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Max retries on transient failures (only when an idempotency key is set). Default 2. */
+    maxRetries?: number;
+    /** Backoff (ms) for attempt n. Default exponential base 200ms cap 2000ms. */
+    backoffMs?: (n: number) => number;
+}
+/**
+ * Validate the engine base URL BEFORE any key-bearing request is sent to it.
+ * Requires https:// (the only safe transport for a Bearer token), allowing
+ * http://localhost / 127.0.0.1 only for local development. A non-parseable,
+ * non-https, or non-local-http URL is rejected — this is the guard against a
+ * hostile FIDACY_ENGINE_URL exfiltrating the API key. Returns the trimmed origin+path.
+ */
+export declare function requireSafeBaseUrl(raw: string): string;
+/**
+ * Call the live engine's POST /v1/assess and return the signed trust verdict.
+ *
+ * Retries ONLY when an idempotency key was supplied, on 5xx/429/network/timeout,
+ * with small exponential backoff and a per-request AbortController timeout. This
+ * mirrors the @fidacy/sdk request() behavior. Self-contained; no sdk import.
+ */
+export declare function assessAction(params: AssessParams, cfg: AssessConfig): Promise<AssessResult>;

package/dist/config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Local-first config for @fidacy/mcp (Zero-Friction Onboarding, Fase 1).
+ *
+ * The free tier decides ALLOW/DENY entirely on the client, with NO network on the
+ * critical path. This module resolves the on-disk state so the firewall can start
+ * protecting the instant the process boots:
+ *
+ *   1. read ~/.fidacy/config.json (0600) if present,
+ *   2. otherwise create a free-local config immediately (anon_id, tier=free, no key)
+ *      WITHOUT blocking on the network — auto-provisioning (a server key) is a later
+ *      phase and always happens in the background, never gating startup.
+ *
+ * Precedence for the local mandate/rules is: env vars > config.json > safe default
+ * (deny-unknown payee + a per-tx cap). See resolveMandateRules().
+ */
+/** Optional user-authored rules stored in config.json under `mandate`. */
+export interface MandateRules {
+    payees?: string[];
+    categories?: string[];
+    currency?: string;
+    perTxMax?: number;
+    maxTotal?: number;
+}
+export interface FidacyConfig {
+    /** Anonymous, non-PII install identifier. Also the telemetry key (later phase). */
+    anon_id: string;
+    /** Which layer decides. `free` = local-only; `paid` = server-backed (later). */
+    tier: "free" | "paid";
+    /** Server key. null on the free local tier until provisioning/upgrade sets it. */
+    api_key: string | null;
+    /** Optional local rules. Absent ⇒ safe default (deny-unknown payee + cap). */
+    mandate?: MandateRules;
+    /** First-run timestamp (ISO). Powers time-based nudges; absent on old installs. */
+    created_at?: string;
+    /** Upgrade micro-triggers already shown — each fires ONCE per install, ever. */
+    nudges?: Partial<Record<string, boolean>>;
+    /** Payment-gate decisions taken on this install (milestone nudges). */
+    decisions_count?: number;
+}
+/** Config dir: FIDACY_CONFIG_DIR override, else ~/.fidacy (XDG-friendly enough). */
+export declare function configDir(): string;
+export declare function configPath(): string;
+/** Audit lives under the config dir by default; FIDACY_AUDIT_PATH overrides. */
+export declare function auditLogPath(): string;
+/** Read config.json. Never throws: returns null if absent OR malformed. */
+export declare function readConfig(): FidacyConfig | null;
+/** Persist config.json with restrictive perms (dir 0700, file 0600). Best-effort. */
+export declare function writeConfig(cfg: FidacyConfig): void;
+/**
+ * Resolve on-disk state at boot WITHOUT touching the network.
+ * Existing valid config ⇒ use it. Otherwise create a free-local config now
+ * (so protection is live immediately) and mark firstRun so the caller can kick
+ * off background auto-provisioning in a later phase.
+ */
+export declare function ensureState(): {
+    config: FidacyConfig;
+    firstRun: boolean;
+};
+/**
+ * Resolve the effective local mandate rules with precedence env > config > default.
+ * DEFAULT IS DENY-UNKNOWN: an empty payee allowlist means every payee is denied
+ * offline out of the box (the BEC case), with a per-tx cap. Categories default to
+ * "*" so the only zero-config gates are payee-allowlist + caps. Users add trusted
+ * payees via config.json (or env) to allow real payments.
+ */
+export declare function resolveMandateRules(cfg: FidacyConfig | null): Required<MandateRules>;

package/dist/core.d.ts

@@ -0,0 +1,10 @@
+import type { FidacyCore, Mandate } from "./firewall/index.js";
+import { DevFidacyCore } from "./firewall/index.js";
+export { DevFidacyCore };
+export type { Mandate };
+/**
+ * Wire the shared engine to this shell: the local reference core (free tier) or the
+ * HTTP-backed core (paid). Telemetry is injected as a per-decision hook, so the
+ * engine stays fully decoupled from the shell's config/telemetry.
+ */
+export declare function makeCore(): FidacyCore;

package/dist/core.js

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

package/dist/firewall/audit-store.d.ts

@@ -0,0 +1,13 @@
+import { AuditRecord, Decision } from "./types.js";
+export declare class FileAuditStore {
+    private path;
+    private chain;
+    constructor(path: string);
+    private load;
+    private head;
+    append(decision: Decision): AuditRecord;
+    find(decisionId: string): AuditRecord | undefined;
+    /** The full loaded chain, oldest first. Read-only; used to rehydrate core state at boot. */
+    records(): readonly AuditRecord[];
+    intact(): boolean;
+}

package/dist/firewall/core.d.ts

@@ -0,0 +1,79 @@
+import { Mandate, PaymentRequest, Decision, AuditProof, AuditRecord } from "./types.js";
+/**
+ * Canonicalize an invoice reference so the "one payment per invoice" (BEC) guard
+ * cannot be bypassed by case, surrounding/zero-width whitespace, or Unicode form.
+ * Returns "" for absent/blank refs (no dedup possible without an identity).
+ */
+export declare function canonInvoice(ref: unknown): string;
+/** Reject structurally-abusive payment requests before any cap math. Returns a
+ * violation code, or null when the request is well-formed. */
+export declare function validateRequest(req: PaymentRequest): string | null;
+/** Enforce a trusted transport for a base URL that will carry a Bearer key: https
+ * only, or http://localhost for dev. Throws on anything else. */
+export declare function requireHttpsBase(raw: string): string;
+export interface FidacyCore {
+    getMandate(subject: string): Promise<Mandate>;
+    decide(req: PaymentRequest, subject: string): Promise<Decision>;
+    getProof(decisionId: string): Promise<AuditProof | null>;
+    publicKey(): string;
+    /**
+     * Recent decisions from the audit chain, oldest first, capped at `limit`.
+     * Read-only and never gated: an operator asking what their agents did is not
+     * a money-moving action, so it must answer even when the firewall would deny
+     * a payment. This is what turns the audit chain from a forensic artifact into
+     * something a human can ask about in plain language.
+     */
+    history(limit?: number): Promise<readonly AuditRecord[]>;
+}
+export interface DevFidacyCoreOptions {
+    mandate: Mandate;
+    auditLogPath?: string;
+    /** Called after each decision is recorded. Best-effort; must never throw. */
+    onDecision?: (decision: Decision) => void;
+}
+export declare class DevFidacyCore implements FidacyCore {
+    private priv;
+    private pubPem;
+    private mandate;
+    private store;
+    private spent;
+    private claimedInvoices;
+    private onDecision?;
+    constructor(opts: DevFidacyCoreOptions);
+    /**
+     * Rebuild the in-memory decision state from the persisted audit log, so a process
+     * restart cannot re-open a claimed invoice (BEC dedup) or reset the maxTotal
+     * counter. One O(records) pass at boot over the already-loaded chain:
+     *   - claimedInvoices: every ALLOW that carried an invoiceRef, regardless of age —
+     *     a paid invoice stays paid.
+     *   - spent: ALLOW amounts whose timestamp falls inside the CURRENT mandate window
+     *     and whose currency matches the mandate (the cap is defined per window/currency).
+     * Records from older versions lack the rehydration fields and are skipped.
+     */
+    private rehydrate;
+    /**
+     * Swap the active mandate (shell config hot-reload: edit config.json, the next
+     * call picks it up, no host restart). Decision state is REBUILT from the audit
+     * log under the new window/currency, so a reload can never reset the BEC
+     * invoice dedup or undercount spend: a paid invoice stays paid, spent is
+     * recomputed.
+     */
+    setMandate(m: Mandate): void;
+    getMandate(): Promise<Mandate>;
+    decide(req: PaymentRequest, subject: string): Promise<Decision>;
+    getProof(decisionId: string): Promise<AuditProof | null>;
+    history(limit?: number): Promise<readonly AuditRecord[]>;
+    publicKey(): string;
+}
+export declare class HttpFidacyCore implements FidacyCore {
+    private apiKey;
+    private subjectPub;
+    private baseUrl;
+    constructor(baseUrl: string, apiKey: string, subjectPub?: string);
+    private call;
+    getMandate(subject: string): Promise<Mandate>;
+    decide(req: PaymentRequest, subject: string): Promise<Decision>;
+    getProof(decisionId: string): Promise<AuditProof | null>;
+    history(limit?: number): Promise<readonly AuditRecord[]>;
+    publicKey(): string;
+}

package/dist/firewall/evaluate.d.ts

@@ -0,0 +1,10 @@
+import { Mandate, PaymentRequest } from "./types.js";
+/**
+ * Is `payee` a lookalike of one of the `allowed` payees (an impersonation attempt),
+ * without being an exact allow-listed match? Returns the impersonated approved
+ * payee, or null. Two signals: an identical homoglyph fold (the classic digit-swap),
+ * or a tiny edit distance on the fold (insert/delete/transpose a char). Gated on a
+ * min length so short, genuinely-distinct payees don't false-positive.
+ */
+export declare function lookalikePayee(payee: string, allowed: string[]): string | null;
+export declare function evaluate(mandate: Mandate, req: PaymentRequest, spentSoFar: number): string | null;

package/dist/firewall/executor.d.ts

@@ -0,0 +1,49 @@
+import { PaymentRequest } from "./types.js";
+export interface Rail {
+    execute(req: PaymentRequest): Promise<{
+        railRef: string;
+    }>;
+}
+export declare class ReferenceRail implements Rail {
+    settlements: Array<PaymentRequest & {
+        railRef: string;
+        at: string;
+    }>;
+    execute(req: PaymentRequest): Promise<{
+        railRef: string;
+    }>;
+}
+export type ExecResult = {
+    status: "EXECUTED";
+    railRef: string;
+    decisionId: string;
+} | {
+    status: "REFUSED";
+    reason: string;
+};
+/**
+ * Durable single-use claim. Returns true if this is the FIRST redemption of the
+ * grant's decisionId, false on any replay. `httpRedeem` binds it to the hosted
+ * core's POST /v1/grant/redeem so single-use survives a serverless multi-instance
+ * deployment (the in-memory Set does not — C2).
+ */
+export type RedeemFn = (grant: string) => Promise<boolean>;
+export declare function httpRedeem(coreUrl: string, apiKey: string): RedeemFn;
+export declare class GrantEnforcingExecutor {
+    private rail;
+    private used;
+    private pub;
+    private redeem?;
+    constructor(publicKeyPem: string, rail: Rail, opts?: {
+        redeem?: RedeemFn;
+        /**
+         * Escape hatch for genuinely single-process deployments (a local CLI, a
+         * single long-lived worker) where the in-memory Set IS authoritative. Must
+         * be set EXPLICITLY to run without a durable `redeem` in production —
+         * otherwise the constructor throws, because on serverless/multi-instance the
+         * in-memory Set does not stop a replayed grant from double-settling.
+         */
+        allowUnsafeInMemorySingleUse?: boolean;
+    });
+    execute(req: PaymentRequest, grant: string | undefined): Promise<ExecResult>;
+}

package/dist/firewall/grant.d.ts

@@ -0,0 +1,20 @@
+export interface GrantPayload {
+    decisionId: string;
+    subject: string;
+    payee: string;
+    amount: number;
+    currency: string;
+    exp: number;
+    invoiceRef?: string;
+}
+export interface GrantCheck {
+    valid: boolean;
+    reason?: string;
+    payload?: GrantPayload;
+}
+export declare function verifyGrant(publicKeyPem: string, grant: string, expected: {
+    payee: string;
+    amount: number;
+    currency: string;
+    invoiceRef?: string;
+}): GrantCheck;

package/dist/firewall/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./util.js";
+export * from "./signing.js";
+export * from "./grant.js";
+export * from "./audit-store.js";
+export * from "./executor.js";
+export * from "./evaluate.js";
+export * from "./core.js";

package/dist/firewall/signing.d.ts

@@ -0,0 +1,10 @@
+import { KeyObject } from "node:crypto";
+export declare function loadOrGenerateKeyPair(): {
+    privateKey: KeyObject;
+    publicKey: KeyObject;
+    ephemeral: boolean;
+};
+export declare function publicKeyPem(publicKey: KeyObject): string;
+export declare function sign(privateKey: KeyObject, message: string): string;
+export declare function verify(publicKey: KeyObject, message: string, signatureB64url: string): boolean;
+export declare function sha256(input: string): string;

package/dist/firewall/types.d.ts

@@ -0,0 +1,58 @@
+export type Mandate = {
+    id: string;
+    subject: string;
+    version: string;
+    allow: {
+        payees: string[];
+        categories: string[];
+        currency: string;
+        maxTotal: number;
+        perTxMax: number;
+    };
+    window: {
+        notBefore: string;
+        notAfter: string;
+    };
+    revoked: boolean;
+};
+export type PaymentRequest = {
+    payee: string;
+    amount: number;
+    currency: string;
+    purpose: string;
+    category: string;
+    idempotencyKey: string;
+    invoiceRef?: string;
+};
+export type DecisionStatus = "ALLOW" | "DENY";
+export type Decision = {
+    decisionId: string;
+    status: DecisionStatus;
+    subject: string;
+    mandateId: string;
+    request: PaymentRequest;
+    violatedRule?: string;
+    grant?: string;
+    ts: string;
+};
+export type AuditRecord = {
+    seq: number;
+    decisionId: string;
+    status: DecisionStatus;
+    subject: string;
+    digest: string;
+    prevHash: string;
+    hash: string;
+    ts: string;
+    amount?: number;
+    currency?: string;
+    invoiceRef?: string;
+    purpose?: string;
+    payee?: string;
+    violatedRule?: string;
+};
+export type AuditProof = {
+    record: AuditRecord;
+    chainIntact: boolean;
+    verifiedAgainstPublicKey: string;
+};

package/dist/firewall/util.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(obj: unknown): string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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);
@@ -358,10 +358,10 @@ 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);
     }
@@ -490,7 +490,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.3" : "dev";
+var CLIENT_VERSION = true ? "0.2.5" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -834,7 +834,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.3" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.5" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -1118,11 +1118,94 @@ function explainRule(rule, payee) {
   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.3" : "dev";
+var SERVER_VERSION = true ? "0.2.5" : "dev";
 var bootClaim = claimUrl();
 var server = new McpServer(
   { name: "fidacy", version: SERVER_VERSION },
@@ -1163,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();
@@ -1284,6 +1374,26 @@ Proof: entry #${record2.seq} in the hash-chained audit, chain currently ${proof.
     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.d.ts

@@ -0,0 +1,13 @@
+export * from "./firewall/index.js";
+export { makeCore } from "./core.js";
+export { ensureState, readConfig } from "./config.js";
+export { requestUpgrade, upgradeUrl } from "./upgrade.js";
+export { autoProvision } from "./provision.js";
+export { recordInstall, recordAgentActive, setTelemetryShell } 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 { summarize, renderSummary, toRows, renderRows, explainRule, withinDays } from "./reporting.js";
+export type { SpendSummary, DecisionRow } from "./reporting.js";
+export { assessPattern, sweep, renderAlertLine, SENTINEL } from "./sentinel.js";
+export type { SentinelAlert } from "./sentinel.js";
+export type { TelemetryShell } from "./telemetry.js";

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);
@@ -389,10 +389,10 @@ 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);
     }
@@ -613,7 +613,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.3" : "dev";
+var CLIENT_VERSION = true ? "0.2.5" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -791,7 +791,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.3" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.5" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -1053,6 +1053,89 @@ function explainRule(rule, payee) {
     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,
@@ -1060,8 +1143,10 @@ export {
   GrantEnforcingExecutor,
   HttpFidacyCore,
   ReferenceRail,
+  SENTINEL,
   activationBootLine,
   activationGate,
+  assessPattern,
   autoProvision,
   canonInvoice,
   claimUrl,
@@ -1082,6 +1167,7 @@ export {
   recordAgentActive,
   recordInstall,
   remainingFree,
+  renderAlertLine,
   renderRows,
   renderSummary,
   requestUpgrade,
@@ -1091,6 +1177,7 @@ export {
   sign,
   stableStringify,
   summarize,
+  sweep,
   toRows,
   trialCountdownLine,
   upgradeUrl,

package/dist/nudges.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Micro-triggers (upgrade funnel, elegant by doctrine):
+ *
+ *  1. A trigger fires ONLY at a value-proven moment — right after the firewall
+ *     did something for the user (a block, a milestone, a proof).
+ *  2. Each dynamic trigger fires ONCE per install, ever (flags persisted in
+ *     ~/.fidacy/config.json). Elegance = never nag twice; the free tier stays
+ *     fully usable in silence.
+ *  3. Every trigger routes through the shell's upgrade tool, so intent is
+ *     recorded (upgrade_intent telemetry) and the anon binding travels along.
+ *
+ * All writes are best-effort: a read-only disk silences nudges, never the firewall.
+ */
+export type NudgeKey = "first_deny" | "first_allow" | "bec_catch" | "milestone_10" | "week_1" | "proof_teaser" | "hosted_wall";
+/**
+ * The claim URL for THIS install: fidacy.com/claim?ref=<anon_id> shows the
+ * operator what the firewall already blocked here and starts a free account
+ * that inherits this history. Directed at the HUMAN reading the transcript —
+ * the tool-call path (upgrade) measured agents, and agents never buy.
+ * Null when there is no persisted config (no anon id ⇒ nothing to claim).
+ */
+export declare function claimUrl(): string | null;
+/** True the FIRST time this key is claimed for this install; false forever after. */
+export declare function nudgeOnce(key: NudgeKey): boolean;
+/** Decisions counted in this process (storage-independent). */
+export declare function sessionDecisionCount(): number;
+/** Increment and return the per-install decision counter (payment gate calls). */
+export declare function bumpDecisionCount(): number;
+/** Days since first run (0 when unknown — installs that predate created_at). */
+export declare function installAgeDays(): number;
+/**
+ * The one nudge line for a payment-gate decision, or null for silence.
+ * Call once per decision; pass the shell's upgrade tool name for correct copy.
+ */
+export declare function decisionNudge(status: "ALLOW" | "DENY", violatedRule: string | undefined, upgradeToolName: string): string | null;
+/**
+ * The CTA for hitting the free-tier wall on a HOSTED value action — a server-
+ * signed verdict (assess_action) or a Bitcoin-anchored proof (anchor_artifact).
+ * This is Option C: the local firewall stays free forever, but the moment the
+ * agent reaches for the verifiable/anchored proof (the highest-value feature) and
+ * the free allowance is spent, the operator gets an elegant route to a free
+ * account instead of a raw `402 payment_required`. Rich copy once per install
+ * (nudge doctrine: never nag twice), a terse line every time after — the wall is
+ * a direct answer to the agent's request, so it always says SOMETHING actionable.
+ */
+export declare function hostedWallCta(feature: "verdict" | "anchor"): string;
+/** The no-key CTA for a hosted tool: route the human to a free account. */
+export declare function noKeyCta(): string;
+/** One-time boot line after a week of real protection; null otherwise. */
+export declare function weekOneBootNudge(upgradeToolName: string): string | null;

package/dist/provision.d.ts

@@ -0,0 +1,6 @@
+export declare function provisionEnabled(): boolean;
+/**
+ * Best-effort background provisioning. Returns the outcome (useful for tests/logs);
+ * callers should NOT await it on the startup path — fire and forget.
+ */
+export declare function autoProvision(): Promise<"provisioned" | "skipped" | "rate_limited" | "failed">;

package/dist/reporting.d.ts

@@ -0,0 +1,59 @@
+import type { AuditRecord } from "./firewall/index.js";
+/**
+ * OPERATOR REPORTING — the read half of the firewall.
+ *
+ * The write tools (request_payment et al.) answer the agent. These answer the
+ * HUMAN, in the same conversation the agent already lives in: "what did my
+ * agents spend this week", "what got blocked and why", "explain this one".
+ * Before this, an operator only ever heard from Fidacy at the moment something
+ * was denied, which is the worst possible time to meet a product.
+ *
+ * Everything here is derived from the local hash-chained audit (or the hosted
+ * chain in http mode), so it is agent-agnostic by construction: any MCP host,
+ * any agent framework, no dashboard, no account required.
+ *
+ * Pure functions, no I/O: the shell fetches records and passes them in.
+ */
+/** A record is "in window" when its ISO ts is within `days` of now. */
+export declare function withinDays(records: readonly AuditRecord[], days: number, now?: number): AuditRecord[];
+export type SpendSummary = {
+    window_days: number;
+    decisions: number;
+    allowed: number;
+    denied: number;
+    /** Totals per ISO currency. Records from older versions may lack an amount. */
+    allowed_totals: Record<string, number>;
+    blocked_totals: Record<string, number>;
+    /** Denial counts per violated rule, most frequent first. */
+    denied_by_rule: Record<string, number>;
+    /** Distinct payees actually paid in the window. */
+    payees_paid: string[];
+    /** Records in the window whose amount was never persisted (pre-0.2.3 writes). */
+    amount_unknown: number;
+    first_ts: string | null;
+    last_ts: string | null;
+};
+export declare function summarize(records: readonly AuditRecord[], days: number, now?: number): SpendSummary;
+/** The summary as a sentence an operator reads without decoding JSON. */
+export declare function renderSummary(s: SpendSummary): string;
+export interface DecisionRow {
+    seq: number;
+    decisionId: string;
+    status: string;
+    ts: string;
+    payee?: string;
+    amount?: number;
+    currency?: string;
+    purpose?: string;
+    violatedRule?: string;
+    invoiceRef?: string;
+}
+/** Newest first, which is the order a human asking "what just happened" wants. */
+export declare function toRows(records: readonly AuditRecord[], status: "ALLOW" | "DENY" | "all", limit: number): DecisionRow[];
+export declare function renderRows(rows: DecisionRow[]): string;
+/**
+ * Plain-language reading of one decision. The point is that an operator gets the
+ * "why" without reading a rule name: a violated rule is a policy sentence, and
+ * the mandate that produced it is the thing they can actually change.
+ */
+export declare function explainRule(rule: string | undefined, payee?: string): string;

package/dist/sentinel.d.ts

@@ -0,0 +1,69 @@
+import type { AuditRecord } from "./firewall/index.js";
+/**
+ * SENTINEL — predictive alerts before the mistake.
+ *
+ * The mandate answers "is this allowed". Sentinel answers the question that
+ * arrives one step later in every real incident: "it was allowed, but is it
+ * NORMAL for this agent?" A prompt-injected agent's first move is usually a
+ * payment that clears every rule while breaking every pattern: a payee it has
+ * never paid, an amount far above its history, a burst of requests, or the
+ * signature move our own Model Watch benchmark measured, retrying what was
+ * just denied.
+ *
+ * Doctrine:
+ *  - DETERMINISTIC and explainable. Every alert names its rule and its
+ *    numbers. No model, no score, no black box: this ships in the same
+ *    product whose whole thesis is that judgments must be re-derivable.
+ *  - ADVISORY. Sentinel never changes a decision; the mandate remains the only
+ *    gate. An alert on an ALLOW is a heads-up that arrives BEFORE settlement,
+ *    which is the last moment a human can still act cheaply.
+ *  - LOCAL. Pure functions over the same hash-chained audit the shell already
+ *    holds. Works offline, both shells, no account, agent-agnostic.
+ */
+export type SentinelAlert = {
+    rule: "first_payee" | "amount_spike" | "velocity_burst" | "cap_creep" | "retry_after_deny";
+    severity: "notice" | "warning";
+    message: string;
+};
+/** Tunables, exported so shells and tests can show/pin them. */
+export declare const SENTINEL: {
+    /** amount >= SPIKE_FACTOR x the historical max ALLOW to the same payee. */
+    readonly SPIKE_FACTOR: 3;
+    /** minimum prior ALLOWs to a payee before a spike is judged (else first_payee covers it). */
+    readonly SPIKE_MIN_HISTORY: 2;
+    /** decisions within BURST_WINDOW_MS to trip velocity_burst. */
+    readonly BURST_COUNT: 5;
+    readonly BURST_WINDOW_MS: number;
+    /** fraction of perTxMax that counts as riding the ceiling. */
+    readonly CAP_CREEP_RATIO: 0.8;
+    /** a DENY for the same payee within this window makes a new attempt a retry. */
+    readonly RETRY_WINDOW_MS: number;
+};
+/**
+ * Judge one incoming request against this agent's own recorded pattern.
+ * `records` is the chain BEFORE this request (order preserved, oldest first).
+ */
+export declare function assessPattern(records: readonly AuditRecord[], req: {
+    payee: string;
+    amount?: number;
+}, opts?: {
+    perTxMax?: number;
+    now?: number;
+}): SentinelAlert[];
+/**
+ * Retrospective sweep for the `sentinel_alerts` tool: replay the chain and
+ * report which decisions tripped which patterns, newest first. Deterministic:
+ * each decision is judged only against the records before it.
+ */
+export declare function sweep(records: readonly AuditRecord[], opts?: {
+    perTxMax?: number;
+    limit?: number;
+}): {
+    decisionId: string;
+    ts: string;
+    status: string;
+    payee?: string;
+    alerts: SentinelAlert[];
+}[];
+/** One compact line for decision responses; empty string when nothing fired. */
+export declare function renderAlertLine(alerts: SentinelAlert[]): string;

package/dist/telemetry.d.ts

@@ -0,0 +1,27 @@
+export type TelemetryEventType = "install" | "agent_active" | "decision" | "upgrade_intent";
+export type DecisionResult = "allow" | "deny_cap" | "deny_payee" | "deny_scope" | "deny_lookalike" | "deny_duplicate" | "deny_window" | "deny_invalid";
+/** Which shell this engine is embedded in. An ENUM mirrored by the ingest allowlist
+ *  and the DB CHECK — never a free-form string, so it can't become a PII channel. */
+export type TelemetryShell = "mcp" | "openclaw-plugin" | "crabtrap" | "sdk";
+/** Order-of-magnitude bucket of the requested amount (mandate currency). An
+ *  ENUM: the amount itself NEVER leaves the install, only its magnitude class,
+ *  which is what turns the frequency corpus into a loss-distribution shape. */
+export type AmountBand = "lt10" | "10_99" | "100_999" | "1k_10k" | "10k_100k" | "gte100k";
+/** How far a denied amount sat above the per-transaction cap. Dimensionless. */
+export type CapRatioBand = "1_2x" | "2_5x" | "5_10x" | "gt10x";
+export declare function bandOf(amount: unknown): AmountBand | undefined;
+export declare function capRatioOf(amount: unknown, perTxMax: unknown): CapRatioBand | undefined;
+/** Set by non-MCP shells (e.g. the native OpenClaw plugin) BEFORE the first
+ *  recorded event, so traction can be attributed to the acquisition channel. */
+export declare function setTelemetryShell(shell: TelemetryShell): void;
+export declare function telemetryEnabled(): boolean;
+/** Map a firewall violatedRule to the coarse, PII-free decision result enum. */
+export declare function resultOf(status: "ALLOW" | "DENY", violatedRule?: string): DecisionResult;
+/** Buffer an event (sync, never blocks, never throws). Auto-flushes shortly after. */
+export declare function record(type: TelemetryEventType, result?: DecisionResult, band?: AmountBand, capRatio?: CapRatioBand): void;
+export declare const recordInstall: () => void;
+export declare const recordAgentActive: () => void;
+export declare const recordDecision: (status: "ALLOW" | "DENY", violatedRule?: string, amount?: number, perTxMax?: number) => void;
+export declare const recordUpgradeIntent: () => void;
+/** Send the buffered batch fire-and-forget. Swallows all errors. Best-effort. */
+export declare function flush(): Promise<void>;

package/dist/upgrade.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Upgrade (Zero-Friction Onboarding, Fase 4 / Componente 5).
+ *
+ * The free tier is local-first with an anonymous identity. Upgrading opens the
+ * real-account flow (e-mail/billing) in the dashboard; the anon_id travels in the
+ * link so the engine can bind past usage to the new tenant on completion. The MCP
+ * side is deliberately thin: record the funnel signal and hand back the link — no
+ * account/billing logic lives in the shell.
+ */
+export declare function upgradeUrl(): string;
+/** Emit the upgrade_intent telemetry signal (top of the conversion funnel) and
+ *  return the URL to open. Best-effort telemetry; never throws. */
+export declare function requestUpgrade(): {
+    url: string;
+    anonId: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",
@@ -21,11 +21,24 @@
     "fidacy-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/index.js",
-    "./assess": "./dist/assess.js",
-    "./core": "./dist/core.js",
-    "./lib": "./dist/lib.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./assess": {
+      "types": "./dist/assess.d.ts",
+      "default": "./dist/assess.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
+    },
+    "./lib": {
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.js"
+    }
   },
   "files": [
     "dist",