@quackai/q402-mcp 0.8.14 → 0.8.16

package/README.md

@@ -290,7 +290,7 @@ Single transfers and multi-recipient batches ship today. The next layer — recu
 
 ## Hooks — programmable payment policies
 
-Q402 Hooks 1.0 is a policy engine that attaches rules to the payment lifecycle: OFAC compliance screening, spend caps + recipient allowlists, ERC-8004 reputation gating, Chainlink-oracle conditional settlement ("only when BTC ≥ $80k"), and automatic multi-payee splits — plus human-in-the-loop approval holds. Uniswap v4 brought programmable hooks to DEX liquidity; Q402 brings them to AI-agent payments.
+Q402 Hooks 1.0 is a policy engine that attaches rules to the payment lifecycle: OFAC compliance screening, spend caps + recipient allowlists, ERC-8004 reputation gating, Chainlink-oracle conditional settlement ("only when BTC ≥ $80k"), and automatic multi-payee splits — plus an approval-required soft block for large payments (returns 202 `approval_required`; the caller re-submits out of band, no stored hold in v1). Uniswap v4 brought programmable hooks to DEX liquidity; Q402 brings them to AI-agent payments.
 
 **Developer reference: [docs/HOOKS.md](docs/HOOKS.md)** — lifecycle, the Hook contract, every shipped hook with config + examples.
 

package/dist/index.js

@@ -211,7 +211,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.8.14";
+var PACKAGE_VERSION = "0.8.15";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -1092,6 +1092,53 @@ async function runPay(input) {
     }
     const data = await resp.json().catch(() => ({}));
     const txHash = data.txHash ?? "";
+    const isSplit = data.split === true || Array.isArray(data.legs);
+    if (isSplit) {
+      const legs = Array.isArray(data.legs) ? data.legs : [];
+      const status = data.status;
+      const replayed = data.replayed === true;
+      const settledCount = typeof data.settled === "number" ? data.settled : legs.filter((l) => typeof l.txHash === "string" && l.txHash.length > 0).length;
+      const failedCount = typeof data.failed === "number" ? data.failed : legs.filter((l) => !l.txHash).length;
+      const isComplete = status === "complete" && failedCount === 0;
+      const isPartial = status === "partial" || resp.status === 207;
+      const success2 = isComplete;
+      const message2 = "message" in data ? data.message : "error" in data ? data.error : void 0;
+      return {
+        result: {
+          success: success2,
+          sandbox: false,
+          // Top-level txHash mirrors the server's (first settled leg). Per-leg
+          // hashes in `legs` remain authoritative.
+          txHash,
+          tokenAmount: input.amount,
+          token: input.token,
+          chain: chain.key,
+          method: "eip7702",
+          split: true,
+          legs,
+          settledLegs: settledCount,
+          failedLegs: failedCount,
+          ...isPartial && !isComplete ? { partial: true } : {},
+          ...replayed ? { replayed: true } : {},
+          explorerUrl: txHash ? void 0 : null
+        },
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          "settlement=split",
+          `split_settled=${settledCount}`,
+          `split_failed=${failedCount}`,
+          `split_status=${status ?? "unknown"}`,
+          ...replayed ? ["replayed=true"] : [],
+          ...message2 ? [`server_message=${message2}`] : []
+        ],
+        senderWallet,
+        ...isPartial && !isComplete ? {
+          setupHint: `Split PARTIALLY settled: ${settledCount} leg(s) landed on-chain, ${failedCount} did NOT. The settled legs already moved funds \u2014 do NOT blindly retry the whole payment (a retry replays only the unsettled intent, it will not double-pay the settled legs). Inspect legs[] for which recipients received funds and which still need handling.`
+        } : {}
+      };
+    }
     const isPending = resp.status === 202 || data.pending === true || data.status === "processing";
     if (isPending) {
       const retryAfter = typeof data.retryAfterSec === "number" ? data.retryAfterSec : 5;
@@ -1241,7 +1288,7 @@ var PAY_TOOL = {
       confirm: {
         type: "boolean",
         const: true,
-        description: "MUST be true and only set after the user has confirmed recipient + amount in chat."
+        description: "MUST be true and only set after the user has confirmed this exact payment in chat. When hookParams is set, confirm what it does to the money too: the split RECIPIENTS and shares (funds go there, not `to`) and any oracle condition gating settlement \u2014 not just the top-level recipient + amount."
       },
       hookParams: {
         type: "object",
@@ -2950,7 +2997,10 @@ var BridgeSendInputSchema = z11.object({
   walletId: z11.string().optional().describe("Agentic Wallet ID (from q402_agentic_info). Optional \u2014 defaults to the owner's default Agent Wallet."),
   feeToken: z11.enum(["LINK", "native"]).optional().describe("Fee token. Defaults to LINK (~10% cheaper than native)."),
   sandbox: z11.boolean().optional().describe("Sandbox mode (default true). Set to false for a live on-chain bridge."),
-  maxFeeRaw: z11.string().regex(/^\d+$/).optional().describe("Optional client-side fee cap in raw 18-dec wei. Server still clamps to its 10% slippage ceiling; clients may LOWER but not RAISE.")
+  maxFeeRaw: z11.string().regex(/^\d+$/).optional().describe("Optional client-side fee cap in raw 18-dec wei. Server still clamps to its 10% slippage ceiling; clients may LOWER but not RAISE."),
+  confirm: z11.boolean().optional().describe(
+    "MUST be true to fire a LIVE bridge (ignored in sandbox). Set this only after the user has explicitly approved this exact bridge (src, dst, amount, feeToken) in the conversation. When omitted or false on a live call the tool previews the action and does NOT move any funds. Never set confirm:true on the user's behalf without approval."
+  )
 }).refine((d) => d.src !== d.dst, {
   // Local Zod rejection saves a network round-trip + a Q402 backend log
   // entry. The bridge route also rejects same-chain bridges but the
@@ -2960,7 +3010,7 @@ var BridgeSendInputSchema = z11.object({
 });
 var BRIDGE_SEND_TOOL = {
   name: "q402_bridge_send",
-  description: "Execute a Chainlink CCIP USDC bridge across the 3-chain triangle (eth/avax/arbitrum) on behalf of the user's server-managed Agentic Wallet (Mode C). Sandbox-by-default \u2014 returns a synthetic messageId unless `sandbox: false` is passed AND Q402_ENABLE_REAL_PAYMENTS=1 AND a live Multichain API key is configured. The server signs ccipSend with the Agent Wallet's encrypted PK, auto-funds source-chain gas from the user's Gas Tank, and debits both the auto- fund cost and the CCIP fee per the bridge's settled receipt. Recommended flow: q402_bridge_quote first \u2192 confirm cost with the user \u2192 q402_bridge_send with sandbox: false. Live mode needs a Multichain subscription; trial keys are rejected. If the bridge returns AGENT_WALLET_DELEGATED, run q402_clear_delegation on the source chain first.",
+  description: "Execute a Chainlink CCIP USDC bridge across the 3-chain triangle (eth/avax/arbitrum) on behalf of the user's server-managed Agentic Wallet (Mode C). Sandbox-by-default \u2014 returns a synthetic messageId unless `sandbox: false` is passed AND Q402_ENABLE_REAL_PAYMENTS=1 AND a live Multichain API key is configured. The server signs ccipSend with the Agent Wallet's encrypted PK, auto-funds source-chain gas from the user's Gas Tank, and debits both the auto- fund cost and the CCIP fee per the bridge's settled receipt. REQUIRES CONFIRMATION \u2014 like q402_pay and q402_yield_deposit, a LIVE bridge (sandbox: false) refuses to execute unless confirm: true is set. Call it first WITHOUT confirm to get a one-line preview (src, dst, amount, fee token); show that to the user, get explicit approval, THEN re-call with sandbox: false AND confirm: true. Never set confirm: true on the user's behalf. Recommended flow: q402_bridge_quote first \u2192 preview + confirm cost with the user \u2192 q402_bridge_send with sandbox: false, confirm: true. Live mode needs a Multichain subscription; trial keys are rejected. If the bridge returns AGENT_WALLET_DELEGATED, run q402_clear_delegation on the source chain first.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2996,6 +3046,10 @@ var BRIDGE_SEND_TOOL = {
         type: "string",
         pattern: "^[0-9]+$",
         description: "Optional client-side fee cap in raw 18-dec wei."
+      },
+      confirm: {
+        type: "boolean",
+        description: "MUST be true to fire a LIVE bridge (ignored in sandbox) \u2014 set only after the user explicitly approved this exact bridge in chat. Omit (or false) on a live call to preview without moving funds."
       }
     },
     required: ["src", "dst", "amount"]
@@ -3025,6 +3079,16 @@ async function runBridgeSend(input) {
       }]
     };
   }
+  if (input.confirm !== true) {
+    const walletDesc = typeof input.walletId === "string" && input.walletId.length > 0 ? `wallet ${input.walletId.toLowerCase()}` : "your default Agent Wallet";
+    const fee = input.feeToken === "native" ? "native" : "LINK";
+    return {
+      content: [{
+        type: "text",
+        text: `Will bridge ${input.amount} raw USDC units from ${input.src} \u2192 ${input.dst} via Chainlink CCIP from ${walletDesc} (fee paid in ${fee}). This MOVES FUNDS on-chain. Re-call with confirm:true to execute.`
+      }]
+    };
+  }
   const resolved = resolveApiKey(input.src, "multichain");
   if (!resolved.apiKey) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [