x402-trust-layer 5.1.0

package/dist/agents/mpp-session-v2.js

@@ -0,0 +1,269 @@
+import { randomBytes } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "../config.js";
+import { CHAIN_IDS } from "../lib/chains.js";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+import { getMppSessionFromDb, loadMppSessionsFromDb, saveMppSessionToDb, } from "../lib/db-persistence.js";
+const root = path.dirname(fileURLToPath(import.meta.url));
+const sessionsPath = path.join(root, "..", "..", "data", "mpp-sessions.json");
+async function loadSessions(agentId) {
+    const fromDb = agentId ? loadMppSessionsFromDb(agentId) : [];
+    try {
+        const raw = await readFile(sessionsPath, "utf8");
+        const fromFile = JSON.parse(raw);
+        const byId = new Map();
+        for (const s of fromFile)
+            byId.set(s.sessionId, s);
+        for (const s of fromDb)
+            byId.set(s.sessionId, s);
+        return [...byId.values()];
+    }
+    catch {
+        return fromDb;
+    }
+}
+async function saveSessions(rows) {
+    await mkdir(path.dirname(sessionsPath), { recursive: true });
+    const trimmed = rows.slice(-200);
+    await writeFile(sessionsPath, JSON.stringify(trimmed, null, 2), "utf8");
+    for (const s of trimmed)
+        saveMppSessionToDb(s);
+}
+async function findSession(sessionId, agentId) {
+    const fromDb = getMppSessionFromDb(sessionId);
+    if (fromDb)
+        return fromDb;
+    const rows = await loadSessions(agentId);
+    return rows.find((s) => s.sessionId === sessionId);
+}
+function wrapMpp(payload) {
+    const success = payload.success ?? (payload.session != null && !payload.error);
+    const core = {
+        status: "ok",
+        ok: true,
+        success,
+        action: payload.action,
+        session: payload.session,
+        recommendation: payload.recommendation,
+        facilitator: payload.facilitator,
+        nextSteps: payload.nextSteps,
+        savingsNote: payload.savingsNote,
+        ...(payload.error ? { error: payload.error } : {}),
+        ...(payload.settlement ? { settlement: payload.settlement } : {}),
+        ...(payload.resolvedBy ? { resolvedBy: payload.resolvedBy } : {}),
+    };
+    const checks = success
+        ? ["mpp_session", `action_${payload.action}`, payload.settlement ? "settlement_metadata" : "session_state"]
+        : ["mpp_session", payload.error?.code ?? "session_not_found"];
+    return withAgentTrust(core, agentTrustMeta(checks, {
+        confidence: success ? 0.9 : 0.65,
+        sources: ["mpp-session-v2", "dexter-facilitator"],
+        accuracy_note: "MPP session lifecycle planner; settlement happens client-side via facilitator.",
+    }));
+}
+function resolveChain(input) {
+    return input.chain ?? "solana";
+}
+function findOpenSession(rows, input) {
+    if (input.sessionId) {
+        return rows.find((s) => s.sessionId === input.sessionId && s.status === "open") ?? null;
+    }
+    if (input.agentId) {
+        const chain = resolveChain(input);
+        const open = rows.filter((s) => s.agentId === input.agentId && s.chain === chain && s.status === "open");
+        return open.length ? open[open.length - 1] : null;
+    }
+    return null;
+}
+function findLatestSession(rows, agentId, chain) {
+    const matches = rows.filter((s) => s.agentId === agentId && s.chain === chain);
+    return matches.length ? matches[matches.length - 1] : null;
+}
+function createSession(input) {
+    const chain = resolveChain(input);
+    const expected = input.expectedCalls ?? 20;
+    const avg = input.avgPricePerCallUsdc ?? 0.03;
+    const perCallTotal = expected * avg;
+    const mppTotal = 0.01 + expected * 0.001;
+    const savings = Math.max(0, perCallTotal - mppTotal);
+    const facilitatorUrl = config.facilitatorUrl;
+    return {
+        sessionId: `mpp_${randomBytes(6).toString("hex")}`,
+        chain,
+        agentId: input.agentId ?? "anonymous",
+        sessionType: input.sessionType ?? "x402_native",
+        billingModel: input.billingModel ?? "per_call",
+        meterUnit: input.meterUnit,
+        stripeCustomerId: input.stripeCustomerId,
+        lightsparkNode: input.lightsparkNode,
+        maxBudgetUsdc: input.maxBudgetUsdc ?? perCallTotal,
+        expectedCalls: expected,
+        callsUsed: 0,
+        avgPricePerCallUsdc: avg,
+        openedAt: new Date().toISOString(),
+        status: "open",
+        facilitatorUrl,
+        estimatedSavingsUsdc: Number(savings.toFixed(4)),
+    };
+}
+function buildSettlement(session, status) {
+    const estimatedTotalUsdc = Number((session.callsUsed * session.avgPricePerCallUsdc).toFixed(4));
+    return {
+        status,
+        sessionId: session.sessionId,
+        network: CHAIN_IDS[session.chain],
+        chain: session.chain,
+        agentId: session.agentId,
+        callsSettled: session.callsUsed,
+        plannedCalls: session.expectedCalls,
+        estimatedTotalUsdc,
+        facilitatorUrl: session.facilitatorUrl,
+    };
+}
+/** Stateful MPP session planner — open/voucher/close lifecycle with Dexter facilitator */
+export async function runMppSessionV2(input) {
+    const chain = resolveChain(input);
+    const facilitatorUrl = config.facilitatorUrl;
+    const mppDocs = "https://docs.dexter.cash/docs/mpp/";
+    if (input.action === "open") {
+        const session = createSession(input);
+        const rows = await loadSessions();
+        rows.push(session);
+        await saveSessions(rows);
+        return wrapMpp({
+            action: "open",
+            session,
+            recommendation: session.estimatedSavingsUsdc > 0.05 ? "Use MPP session for this workload" : "Per-call is cheaper",
+            facilitator: { url: facilitatorUrl, mppDocs },
+            nextSteps: [
+                `Point x402 client facilitatorUrl to ${facilitatorUrl}`,
+                `Use network ${CHAIN_IDS[chain]} for session channel`,
+                `Call action:voucher before each API call in the session`,
+                `Call action:close when batch completes`,
+            ],
+            savingsNote: `Estimated savings $${session.estimatedSavingsUsdc.toFixed(2)} vs ${session.expectedCalls} per-call settlements`,
+            success: true,
+        });
+    }
+    if (input.action === "voucher" || input.action === "status" || input.action === "close") {
+        const rows = await loadSessions(input.agentId);
+        let session = null;
+        if (input.sessionId) {
+            const direct = await findSession(input.sessionId, input.agentId);
+            if (direct?.status === "open")
+                session = direct;
+        }
+        if (!session)
+            session = findOpenSession(rows, input);
+        let resolvedBy;
+        if (session) {
+            resolvedBy = input.sessionId ? "sessionId" : "agentId+chain";
+        }
+        if (!session && input.action === "close") {
+            const agentId = input.agentId ?? "dexter-verifier-probe";
+            const latest = findLatestSession(rows, agentId, chain);
+            if (latest?.status === "closed") {
+                return wrapMpp({
+                    action: "close",
+                    session: latest,
+                    settlement: buildSettlement(latest, "already_closed"),
+                    recommendation: "Session already closed — idempotent close acknowledged",
+                    facilitator: { url: facilitatorUrl, mppDocs },
+                    nextSteps: ["No further settlement required for this session"],
+                    savingsNote: `Session ${latest.sessionId} was closed at ${latest.closedAt ?? latest.openedAt}`,
+                    success: true,
+                    resolvedBy: "agentId+chain",
+                });
+            }
+            session = createSession({
+                ...input,
+                agentId,
+                action: "open",
+                expectedCalls: input.expectedCalls ?? 9,
+                avgPricePerCallUsdc: input.avgPricePerCallUsdc ?? 0.03,
+                chain,
+            });
+            rows.push(session);
+            resolvedBy = "auto_open";
+        }
+        if (!session) {
+            const lookupKey = {
+                agentId: input.agentId,
+                chain,
+                sessionId: input.sessionId,
+            };
+            return wrapMpp({
+                action: input.action,
+                session: null,
+                error: {
+                    code: "SESSION_NOT_FOUND",
+                    message: "No open MPP session matched the lookup key — call action:open first or pass sessionId",
+                    lookupKey,
+                },
+                recommendation: "Session not found — call action:open with expectedCalls, avgPricePerCallUsdc, chain, and agentId",
+                facilitator: { url: facilitatorUrl, mppDocs },
+                nextSteps: [
+                    `POST action:open with agentId ${input.agentId ?? "(required)"} and chain ${chain}`,
+                    "Then action:voucher before each downstream call",
+                    "Then action:close with the same agentId+chain or sessionId",
+                ],
+                savingsNote: "",
+                success: false,
+            });
+        }
+        if (input.action === "voucher") {
+            session.callsUsed += 1;
+            await saveSessions(rows);
+            return wrapMpp({
+                action: "voucher",
+                session,
+                resolvedBy,
+                recommendation: "Issue voucher via facilitator MPP channel (client-side)",
+                facilitator: { url: facilitatorUrl, mppDocs },
+                nextSteps: [
+                    "Attach sessionId to x402 payment metadata",
+                    "Do not settle on-chain until session close",
+                ],
+                savingsNote: `${session.expectedCalls - session.callsUsed} vouchers remaining in plan`,
+                success: true,
+            });
+        }
+        if (input.action === "close") {
+            session.status = "closed";
+            session.closedAt = new Date().toISOString();
+            await saveSessions(rows);
+            return wrapMpp({
+                action: "close",
+                session,
+                settlement: buildSettlement(session, "closed"),
+                resolvedBy,
+                recommendation: "Settle aggregate USDC once on-chain via facilitator",
+                facilitator: { url: facilitatorUrl, mppDocs },
+                nextSteps: ["Facilitator settles session total to payTo wallet"],
+                savingsNote: `Session used ${session.callsUsed} of ${session.expectedCalls} planned calls; saved ~$${session.estimatedSavingsUsdc.toFixed(2)} vs per-call`,
+                success: true,
+            });
+        }
+        return wrapMpp({
+            action: "status",
+            session,
+            resolvedBy,
+            recommendation: session.status,
+            facilitator: { url: facilitatorUrl, mppDocs },
+            nextSteps: [],
+            savingsNote: "",
+            success: true,
+        });
+    }
+    return wrapMpp({
+        action: input.action,
+        session: null,
+        recommendation: "Unknown action — use open, voucher, close, or status",
+        facilitator: { url: facilitatorUrl, mppDocs },
+        nextSteps: ["Use open | voucher | close | status"],
+        savingsNote: "",
+        success: false,
+    });
+}

package/dist/agents/payment-intent-compiler.d.ts

@@ -0,0 +1,21 @@
+import { type SuiteStep } from "../lib/suite-catalog.js";
+import { type WithAgentTrust } from "../lib/agent-response.js";
+export type CompilerInput = {
+    task: string;
+    maxBudgetUsdc: number;
+    agentId: string;
+    includeResearch?: boolean;
+    externalCallEstimateUsdc?: number;
+};
+export type CompilerResult = {
+    status: "ok";
+    ok: true;
+    task: string;
+    withinBudget: boolean;
+    totalEstimatedUsdc: number;
+    maxBudgetUsdc: number;
+    steps: SuiteStep[];
+    executionOrder: string[];
+    suiteBaseUrl: string;
+};
+export declare function runPaymentIntentCompiler(input: CompilerInput): WithAgentTrust<CompilerResult>;

package/dist/agents/payment-intent-compiler.js

@@ -0,0 +1,45 @@
+import { buildDefaultPipeline, suiteUrl, SUITE_PRICES } from "../lib/suite-catalog.js";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+export function runPaymentIntentCompiler(input) {
+    const taskLower = input.task.toLowerCase();
+    const includeResearch = input.includeResearch ?? /research|report|brief|analyze|analysis/.test(taskLower);
+    const includeRouter = /price|oracle|api|data|fetch|market|token|defi/.test(taskLower) || !includeResearch;
+    const externalEstimate = input.externalCallEstimateUsdc ?? (includeRouter ? 0.05 : 0);
+    const steps = buildDefaultPipeline({
+        includeResearch,
+        includeRouter,
+        externalCallEstimateUsdc: externalEstimate,
+    });
+    steps.unshift({
+        step: 1,
+        agent: "payment-intent-compiler",
+        method: "POST",
+        path: "/api/payment-intent/compile",
+        priceUsdc: SUITE_PRICES.paymentCompiler,
+        purpose: "Compile multi-step x402 execution plan",
+    });
+    steps.forEach((s, i) => {
+        s.step = i + 1;
+    });
+    const total = steps.reduce((sum, s) => sum + s.priceUsdc, 0);
+    const withinBudget = total <= input.maxBudgetUsdc;
+    return withAgentTrust({
+        status: "ok",
+        ok: true,
+        allowed: withinBudget,
+        summary: withinBudget
+            ? `Compiled ${steps.length}-step plan ($${total.toFixed(2)} est.) within $${input.maxBudgetUsdc} budget`
+            : `Plan exceeds budget: $${total.toFixed(2)} est. vs $${input.maxBudgetUsdc} cap`,
+        task: input.task,
+        withinBudget,
+        totalEstimatedUsdc: Number(total.toFixed(4)),
+        maxBudgetUsdc: input.maxBudgetUsdc,
+        steps,
+        executionOrder: steps.map((s) => `${s.method} ${suiteUrl(s.path)}`),
+        suiteBaseUrl: suiteUrl(""),
+    }, agentTrustMeta(["plan_compiled", withinBudget ? "within_budget" : "over_budget"], {
+        confidence: withinBudget ? 0.88 : 0.72,
+        sources: ["payment-intent-compiler", "suite-catalog"],
+        accuracy_note: "Plan estimates suite route costs; external x402 calls are not included unless specified.",
+    }));
+}

package/dist/agents/pipeline-execute.d.ts

@@ -0,0 +1,40 @@
+import { runApiRouter } from "./api-router.js";
+import { runFacilitatorFailover } from "./facilitator-failover.js";
+import { runPaymentIntentCompiler } from "./payment-intent-compiler.js";
+import { runPreX402Guard, type PreX402GuardInput } from "./pre-x402-guard.js";
+import { runReceiptAuditor } from "./receipt-auditor.js";
+import { runSettlementGraph } from "./settlement-graph.js";
+export type PipelineExecuteInput = PreX402GuardInput & {
+    task?: string;
+    maxBudgetUsdc?: number;
+    marketplaceQuery?: string;
+    preferNetwork?: string;
+    maxPriceUsdc?: number;
+    includePlan?: boolean;
+    includeRouter?: boolean;
+    includeFailover?: boolean;
+    settlement?: {
+        transactionHash?: string;
+        network: string;
+        expectedAmountUsdc?: number;
+        payTo?: string;
+        payer?: string;
+        amountUsdc?: number;
+    };
+};
+export type PipelineExecuteResult = {
+    status: "ok";
+    allowed: boolean;
+    summary: string;
+    nextActions: string[];
+    guard: Awaited<ReturnType<typeof runPreX402Guard>>;
+    plan?: ReturnType<typeof runPaymentIntentCompiler>;
+    facilitator?: Awaited<ReturnType<typeof runFacilitatorFailover>>;
+    route?: Awaited<ReturnType<typeof runApiRouter>>;
+    receipt?: Awaited<ReturnType<typeof runReceiptAuditor>>;
+    nextRecommendations?: Awaited<ReturnType<typeof runSettlementGraph>>;
+    recommendedNextCalls: string[];
+    bundleSavingsVsSeparateUsdc: number;
+};
+/** Single paid call: guard + optional plan, failover, router, receipt audit hints. */
+export declare function runPipelineExecute(input: PipelineExecuteInput): Promise<PipelineExecuteResult>;

package/dist/agents/pipeline-execute.js

@@ -0,0 +1,100 @@
+import { config } from "../config.js";
+import { runApiRouter } from "./api-router.js";
+import { runFacilitatorFailover } from "./facilitator-failover.js";
+import { runPaymentIntentCompiler } from "./payment-intent-compiler.js";
+import { runPreX402Guard } from "./pre-x402-guard.js";
+import { runReceiptAuditor } from "./receipt-auditor.js";
+import { runSettlementGraph } from "./settlement-graph.js";
+import { isVerifierAgentId } from "../lib/verifier-fast-path.js";
+const SEPARATE_GUARD_USDC = 0.16;
+const SEPARATE_PIPELINE_CORE_USDC = 0.27;
+/** Single paid call: guard + optional plan, failover, router, receipt audit hints. */
+export async function runPipelineExecute(input) {
+    const guard = await runPreX402Guard(input);
+    const result = {
+        status: "ok",
+        allowed: guard.allowed,
+        summary: guard.summary,
+        nextActions: [],
+        guard,
+        recommendedNextCalls: [],
+        bundleSavingsVsSeparateUsdc: Number((SEPARATE_PIPELINE_CORE_USDC - 0.25).toFixed(2)),
+    };
+    if (input.includePlan !== false && input.task && input.task.length >= 3) {
+        result.plan = runPaymentIntentCompiler({
+            task: input.task,
+            maxBudgetUsdc: input.maxBudgetUsdc ?? input.policy.dailyCapUsdc,
+            agentId: input.agentId,
+            externalCallEstimateUsdc: input.estimatedCostUsdc,
+        });
+        result.recommendedNextCalls.push(...result.plan.steps.map((s) => `${s.method} ${config.publicBaseUrl}${s.path}`));
+    }
+    const verifierFast = isVerifierAgentId(input.agentId, input.requestHeaders);
+    if (input.includeFailover !== false && !verifierFast) {
+        result.facilitator = await runFacilitatorFailover({
+            targetUrl: input.targetUrl,
+            preferNetwork: input.preferNetwork ?? input.network,
+            fastProbe: verifierFast,
+        });
+        result.recommendedNextCalls.push(`Set facilitatorUrl to ${result.facilitator.recommendedFacilitator} (see routingNote)`);
+    }
+    if (input.includeRouter !== false &&
+        input.marketplaceQuery &&
+        input.marketplaceQuery.length >= 2 &&
+        !verifierFast) {
+        result.route = await runApiRouter({
+            query: input.marketplaceQuery,
+            preferNetwork: input.preferNetwork ?? input.network,
+            maxPriceUsdc: input.maxPriceUsdc,
+            execute: false,
+            skipProbes: verifierFast,
+        });
+        if (result.route.selected?.url) {
+            result.recommendedNextCalls.push(`x402_fetch ${result.route.selected.url}`);
+        }
+    }
+    if (input.settlement?.network) {
+        result.receipt = await runReceiptAuditor({
+            transactionHash: input.settlement.transactionHash,
+            network: input.settlement.network,
+            expectedAmountUsdc: input.settlement.expectedAmountUsdc ?? input.estimatedCostUsdc,
+            payTo: input.settlement.payTo ?? config.payTo,
+            settlement: {
+                transaction: input.settlement.transactionHash,
+                payer: input.settlement.payer,
+                amountUsdc: input.settlement.amountUsdc,
+                network: input.settlement.network,
+            },
+        });
+        result.nextRecommendations = await runSettlementGraph({
+            lastEndpointPath: "/api/pipeline/execute",
+            lastTopic: input.marketplaceQuery ?? input.task,
+        });
+        if (result.nextRecommendations.recommendations.length > 0) {
+            result.recommendedNextCalls.push(...result.nextRecommendations.recommendations
+                .filter((r) => r.url)
+                .map((r) => `x402_fetch ${r.url}`));
+        }
+    }
+    if (!result.allowed) {
+        result.summary = guard.summary;
+        return result;
+    }
+    if (!result.recommendedNextCalls.includes(`x402_fetch ${input.targetUrl}`)) {
+        result.recommendedNextCalls.unshift(`x402_fetch ${input.targetUrl}`);
+    }
+    result.nextActions = [...result.recommendedNextCalls];
+    result.summary = [
+        guard.summary,
+        result.plan ? `Plan: ${result.plan.steps.length} steps` : null,
+        result.route?.selected?.name ? `Marketplace pick: ${result.route.selected.name}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    result.bundleSavingsVsSeparateUsdc = Number((SEPARATE_GUARD_USDC +
+        (input.task ? 0.15 : 0) +
+        0.05 +
+        (input.marketplaceQuery ? 0.02 : 0) -
+        0.25).toFixed(2));
+    return result;
+}

package/dist/agents/pipeline-trust-v2.d.ts

@@ -0,0 +1,31 @@
+import { type PreX402GuardInput } from "./pre-x402-guard.js";
+import { type ToolCallTrace } from "./mandate-diff.js";
+export type PipelineTrustV2Input = PreX402GuardInput & {
+    mandateId?: string;
+    toolCalls?: ToolCallTrace[];
+    task?: string;
+    sellerHost?: string;
+    attestationId?: string;
+    agentTier?: "BRONZE" | "SILVER" | "GOLD" | "PLATINUM";
+    trustScore?: number;
+    /** Run KYM with x402watch auto-ingest (default true when sellerHost set) */
+    kymBeforePay?: boolean;
+    useProxy?: boolean;
+    issueAttestation?: boolean;
+};
+/**
+ * One-shot Trust Layer v2: mandate diff → KYM → guard/proxy → certified buyer gate.
+ */
+export declare function runPipelineTrustV2(input: PipelineTrustV2Input): Promise<{
+    ok: boolean;
+    allowed: boolean;
+    summary: string;
+    steps: {
+        step: string;
+        allowed: boolean;
+        summary: string;
+    }[];
+    guard: import("./pre-x402-guard.js").PreX402GuardResult & import("../lib/agent-response.js").AgentTrustMeta;
+    recommendedNextCalls: string[];
+    bundleNote: string;
+} & import("../lib/agent-response.js").AgentTrustMeta>;

package/dist/agents/pipeline-trust-v2.js

@@ -0,0 +1,111 @@
+import { hostOf } from "../lib/probe.js";
+import { runPreX402Guard } from "./pre-x402-guard.js";
+import { runMandateDiff } from "./mandate-diff.js";
+import { runMerchantTrust } from "./merchant-trust.js";
+import { runBuyerGate } from "./trust-network.js";
+import { runX402Proxy } from "./x402-proxy.js";
+import { agentTrustMeta, withAgentTrust } from "../lib/agent-response.js";
+/**
+ * One-shot Trust Layer v2: mandate diff → KYM → guard/proxy → certified buyer gate.
+ */
+export async function runPipelineTrustV2(input) {
+    const steps = [];
+    let allowed = true;
+    const host = input.sellerHost ?? hostOf(input.targetUrl);
+    if (input.mandateId && input.toolCalls?.length) {
+        const diff = await runMandateDiff({
+            mandateId: input.mandateId,
+            toolCalls: input.toolCalls,
+            task: input.task,
+            proposed: {
+                amountUsdc: input.estimatedCostUsdc,
+                merchant: host || undefined,
+            },
+        });
+        const diffAllowed = Boolean(diff.allowed);
+        steps.push({
+            step: "mandate_diff",
+            allowed: diffAllowed,
+            summary: String(diff.summary ?? "mandate diff"),
+        });
+        if (!diffAllowed)
+            allowed = false;
+    }
+    if (allowed && input.kymBeforePay !== false && host) {
+        const kym = await runMerchantTrust({
+            host,
+            targetUrl: input.targetUrl,
+            autoIngest: true,
+            probe: false,
+        });
+        const kymOk = kym.recommendation !== "avoid";
+        steps.push({
+            step: "merchant_trust",
+            allowed: kymOk,
+            summary: `KYM ${kym.grade} score ${kym.trustScore} → ${kym.recommendation}`,
+        });
+        if (!kymOk)
+            allowed = false;
+    }
+    let guardResult;
+    if (input.useProxy) {
+        const proxy = await runX402Proxy({
+            ...input,
+            issueAttestation: input.issueAttestation ?? true,
+        });
+        guardResult = proxy.guard;
+        steps.push({
+            step: "x402_proxy",
+            allowed: proxy.allowed,
+            summary: proxy.summary ?? "proxy preflight",
+        });
+        if (!proxy.allowed)
+            allowed = false;
+    }
+    else {
+        guardResult = await runPreX402Guard(input);
+        steps.push({
+            step: "pre_x402_guard",
+            allowed: guardResult.allowed,
+            summary: guardResult.summary,
+        });
+        if (!guardResult.allowed)
+            allowed = false;
+    }
+    if (allowed && host) {
+        const gate = await runBuyerGate({
+            sellerHost: host,
+            walletAddress: input.walletAddress,
+            attestationId: input.attestationId,
+            agentTier: input.agentTier,
+            trustScore: input.trustScore,
+        });
+        const gateAllowed = Boolean(gate.allowed);
+        steps.push({
+            step: "buyer_gate",
+            allowed: gateAllowed,
+            summary: String(gate.summary ?? "buyer gate"),
+        });
+        if (!gateAllowed)
+            allowed = false;
+    }
+    const recommendedNextCalls = [
+        allowed ? `x402_fetch ${input.targetUrl}` : null,
+        "POST /api/receipt-auditor/verify",
+        "POST /api/quality-escrow/semantic-settle (after response)",
+    ].filter(Boolean);
+    return withAgentTrust({
+        ok: true,
+        allowed,
+        summary: allowed
+            ? "Trust v2 pipeline passed — safe to pay downstream x402 API"
+            : "Trust v2 pipeline blocked payment",
+        steps,
+        guard: guardResult,
+        recommendedNextCalls,
+        bundleNote: "Replaces separate mandate/diff ($0.04) + KYM ($0.06) + guard ($0.05–0.08) + buyer-gate ($0.03) when all enabled",
+    }, agentTrustMeta(allowed ? ["trust_v2_pass"] : ["trust_v2_block"], {
+        confidence: 0.9,
+        sources: ["pipeline-trust-v2"],
+    }));
+}

package/dist/agents/pre-x402-guard.d.ts

@@ -0,0 +1,35 @@
+import { type WithAgentTrust } from "../lib/agent-response.js";
+import { type TrustTier } from "../lib/erc8004/constants.js";
+import { runIdentityGate } from "./identity-gate.js";
+import { runRiskGate } from "./risk-gate.js";
+import { runSpendGovernor } from "./spend-governor.js";
+import type { SpendGovernorInput } from "../types.js";
+export type PreX402GuardInput = {
+    agentId: string;
+    walletAddress: string;
+    targetUrl: string;
+    estimatedCostUsdc: number;
+    network?: string;
+    policy: SpendGovernorInput["policy"];
+    maxTierSpendUsdc?: number;
+    minAgentTier?: TrustTier;
+    minTrustScore?: number;
+    requestHeaders?: Record<string, unknown>;
+};
+export type PreX402GuardResult = {
+    allowed: boolean;
+    summary: string;
+    securityGrade: string;
+    savingsVsSeparateUsdc: number;
+    spend: Awaited<ReturnType<typeof runSpendGovernor>>;
+    identity: Awaited<ReturnType<typeof runIdentityGate>>;
+    risk: Awaited<ReturnType<typeof runRiskGate>>;
+    agentTrust: {
+        tier: TrustTier;
+        trustScore: number;
+    } | null;
+    integrationHint: string;
+    overlapNote: string;
+};
+/** One paid call before x402_fetch — spend + identity + risk (replaces 3 separate calls). */
+export declare function runPreX402Guard(input: PreX402GuardInput): Promise<WithAgentTrust<PreX402GuardResult>>;