@aibtc/mcp-server 1.78.0 → 1.79.0

package/dist/services/inbox-auto-reply.service.d.ts

@@ -17,7 +17,11 @@ export declare const INFERENCE_GATEWAY = "https://inference.aibtc.com";
 /** The largest model on the marketplace at the flat 1-sat price when this shipped. */
 export declare const DEFAULT_AUTO_REPLY_MODEL = "meta-llama/Llama-3.1-8B-Instruct";
 export declare const DEFAULT_DAILY_CAP_SATS = 1000;
+/** Most sats paid for one reply. The marketplace charges 1 sat today. */
+export declare const DEFAULT_MAX_SATS_PER_REPLY = 10;
 export declare const DEFAULT_MAX_REPLIES_PER_RUN = 5;
+/** Paid inference failures on one message before runs stop paying for it. */
+export declare const MAX_PAID_ATTEMPTS = 2;
 /** The outbox rejects longer replies (validation_failed). */
 export declare const MAX_REPLY_CHARS = 500;
 export interface InboxMessage {
@@ -36,8 +40,9 @@ export interface InboxMessage {
     peerBtcAddress?: string;
     peerDisplayName?: string;
 }
-export type SkipReason = "already_replied" | "already_handled" | "unpaid" | "payment_not_settled" | "from_self" | "run_limit" | "daily_cap" | "rate_limited";
-interface AddressLedger {
+export type SkipReason = "already_replied" | "already_handled" | "unpaid" | "payment_not_settled" | "from_self" | "run_limit" | "in_progress" | "gave_up" | "daily_cap" | "price_ceiling" | "spend_limit" | "rate_limited";
+type StopReason = "daily_cap" | "price_ceiling" | "spend_limit" | "rate_limited";
+export interface AddressLedger {
     /** messageId -> ISO time the reply was posted (or found already posted). */
     handled: Record<string, string>;
     /**
@@ -47,6 +52,18 @@ interface AddressLedger {
     pending: Record<string, string>;
     /** UTC day -> sats spent on auto-reply inference that day. */
     spentSats: Record<string, number>;
+    /** messageId -> ISO time a run claimed it. Stops two runs paying for one message. */
+    claimed: Record<string, string>;
+    /** messageId -> paid inference attempts that failed. At MAX_PAID_ATTEMPTS it is given up. */
+    paidFailures: Record<string, number>;
+    /**
+     * messageId -> a dry-run draft and the prompt/model key it was written with.
+     * Later runs with the same key reuse it instead of paying again.
+     */
+    drafts: Record<string, {
+        text: string;
+        key: string;
+    }>;
 }
 /** Point the ledger at another file (tests). */
 export declare function setAutoReplyLedgerFile(file: string): void;
@@ -57,6 +74,11 @@ export declare class DailyCapError extends Error {
     readonly price: number;
     constructor(spent: number, cap: number, price: number);
 }
+export declare class PriceCeilingError extends Error {
+    readonly price: number;
+    readonly max: number;
+    constructor(price: number, max: number);
+}
 export declare function fetchInbox(btcAddress: string): Promise<InboxMessage[]>;
 /**
  * Why a message must not be auto-answered, or null when it may be. A message
@@ -83,6 +105,8 @@ export interface GeneratedReply {
  * agent's own model, plugs in here without touching the inbox side.
  */
 export interface ReplyGenerator {
+    /** The model behind it, so a dry-run draft is reused only by the same source. */
+    readonly id?: string;
     generate(input: {
         systemPrompt: string;
         message: InboxMessage;
@@ -92,6 +116,13 @@ export interface ReplyGenerator {
 }
 /** Strip reasoning blocks some models emit, collapse whitespace, fit the outbox limit. */
 export declare function cleanReply(raw: string): string;
+/**
+ * The inference was paid for but its response is not a usable reply. The run
+ * keeps the cap booking and counts it as a paid failure.
+ */
+export declare class PaidInferenceError extends Error {
+    constructor(message: string);
+}
 export declare function marketplaceReplyGenerator(model: string): ReplyGenerator;
 /** Live model ids on the marketplace (status "live"). */
 export declare function listLiveModels(): Promise<string[]>;
@@ -112,41 +143,42 @@ export interface AutoReplyRunOptions {
     account: Account;
     systemPrompt: string;
     dailyCapSats: number;
+    /** Most sats paid for one reply. A higher quote stops the run before anything is signed. */
+    maxSatsPerReply: number;
     maxRepliesPerRun: number;
     dryRun: boolean;
     generator: ReplyGenerator;
 }
+interface ReplyRecord {
+    messageId: string;
+    from: string;
+    reply: string;
+    inferenceCostSats: number;
+    inferenceTxid?: string;
+    provider?: string;
+    /** The reply was paid for in an earlier run whose post failed. */
+    reusedPending?: boolean;
+    /** The reply is a dry-run draft written with the same prompt and model. */
+    reusedDraft?: boolean;
+}
 export interface AutoReplyRunSummary {
     checked: number;
     eligible: number;
-    replied: Array<{
-        messageId: string;
-        from: string;
-        reply: string;
-        inferenceCostSats: number;
-        inferenceTxid?: string;
-        provider?: string;
-        reusedPending?: boolean;
-    }>;
-    drafted: Array<{
-        messageId: string;
-        from: string;
-        reply: string;
-        inferenceCostSats: number;
-        inferenceTxid?: string;
-        provider?: string;
-    }>;
+    replied: ReplyRecord[];
+    drafted: ReplyRecord[];
     skipped: Array<{
         messageId: string;
         reason: SkipReason;
     }>;
+    /** `gaveUp`: the message failed after payment MAX_PAID_ATTEMPTS times and is no longer retried. */
     failed: Array<{
         messageId: string;
         error: string;
         replySaved: boolean;
+        gaveUp?: boolean;
     }>;
     /** Why the run stopped before working through every eligible message. */
-    stoppedEarly?: "daily_cap" | "rate_limited";
+    stoppedEarly?: StopReason;
     inferenceSatsSpent: number;
     inferenceSatsSpentToday: number;
     inferenceCapRemainingSats: number;

package/dist/services/inbox-auto-reply.service.js

@@ -11,19 +11,31 @@
  * Spend is bounded twice: the auto-reply daily cap below (its own ledger), and
  * the wallet-wide spend limiter that books every x402 payment.
  */
+import { createHash } from "crypto";
 import os from "os";
 import path from "path";
 import { promises as fs } from "fs";
 import { p2wpkh, NETWORK as BTC_MAINNET } from "@scure/btc-signer";
 import { bip322Sign } from "../utils/bip322.js";
 import { withSharedStateLock } from "./state-lock.js";
+import { SpendLimitError } from "./spend-limiter.js";
 import { postWithX402Payment, paymentWasSent } from "./x402-post.js";
 export const INBOX_API = "https://aibtc.com/api";
 export const INFERENCE_GATEWAY = "https://inference.aibtc.com";
 /** The largest model on the marketplace at the flat 1-sat price when this shipped. */
 export const DEFAULT_AUTO_REPLY_MODEL = "meta-llama/Llama-3.1-8B-Instruct";
 export const DEFAULT_DAILY_CAP_SATS = 1000;
+/** Most sats paid for one reply. The marketplace charges 1 sat today. */
+export const DEFAULT_MAX_SATS_PER_REPLY = 10;
 export const DEFAULT_MAX_REPLIES_PER_RUN = 5;
+/** Paid inference failures on one message before runs stop paying for it. */
+export const MAX_PAID_ATTEMPTS = 2;
+/**
+ * How long a run's claim on a message blocks other runs (this server or the
+ * skills CLI, which share the ledger). Longer than one message takes, so only
+ * a claim left by a crashed run expires.
+ */
+const CLAIM_TTL_MS = 10 * 60_000;
 /** The outbox rejects longer replies (validation_failed). */
 export const MAX_REPLY_CHARS = 500;
 /** One page, newest first. Older unanswered messages are out of reach of a run. */
@@ -56,7 +68,14 @@ async function writeLedger(state) {
     await fs.rename(tmp, ledgerFile);
 }
 function ledgerFor(state, btcAddress) {
-    const entry = (state[btcAddress] ??= { handled: {}, pending: {}, spentSats: {} });
+    const entry = (state[btcAddress] ??= {});
+    // Fields added later (and by the skills CLI, which shares this file) may be missing.
+    entry.handled ??= {};
+    entry.pending ??= {};
+    entry.spentSats ??= {};
+    entry.claimed ??= {};
+    entry.paidFailures ??= {};
+    entry.drafts ??= {};
     // Keep only today's spend: the cap is per UTC day.
     const today = todayKey();
     for (const day of Object.keys(entry.spentSats)) {
@@ -109,6 +128,47 @@ async function releaseDailySats(btcAddress, sats) {
         ledger.spentSats[day] = Math.max(0, (ledger.spentSats[day] ?? 0) - sats);
     });
 }
+export class PriceCeilingError extends Error {
+    price;
+    max;
+    constructor(price, max) {
+        super(`Reply inference costs ${price} sats, above the ${max}-sat per-reply ceiling.`);
+        this.price = price;
+        this.max = max;
+        this.name = "PriceCeilingError";
+    }
+}
+/**
+ * Claim a message for this run under the ledger lock, re-reading the ledger
+ * so a run that started earlier and answered (or claimed) it in the meantime
+ * wins. Returns a reply already paid for, if there is one.
+ */
+async function claimMessage(btcAddress, messageId, draftKey) {
+    return updateLedger(btcAddress, (ledger) => {
+        if (ledger.handled[messageId])
+            return { skip: "already_handled" };
+        if ((ledger.paidFailures[messageId] ?? 0) >= MAX_PAID_ATTEMPTS)
+            return { skip: "gave_up" };
+        const claimedAt = Date.parse(ledger.claimed[messageId] ?? "");
+        if (Date.now() - claimedAt < CLAIM_TTL_MS)
+            return { skip: "in_progress" };
+        ledger.claimed[messageId] = new Date().toISOString();
+        const pending = ledger.pending[messageId];
+        if (pending)
+            return { saved: { text: pending, from: "pending" } };
+        const draft = ledger.drafts[messageId];
+        if (draft?.key === draftKey)
+            return { saved: { text: draft.text, from: "draft" } };
+        return {};
+    });
+}
+/**
+ * Identifies the prompt and model a draft was written with. Same key as the
+ * skills CLI, so a draft written by one is reused by the other.
+ */
+function draftKeyFor(systemPrompt, generatorId) {
+    return createHash("sha256").update(`${generatorId ?? ""}\n${systemPrompt}`).digest("hex").slice(0, 16);
+}
 // ============================================================================
 // Inbox read + eligibility
 // ============================================================================
@@ -137,6 +197,8 @@ export function skipReason(message, self, ledger) {
         return "already_replied";
     if (ledger.handled[message.messageId])
         return "already_handled";
+    if ((ledger.paidFailures[message.messageId] ?? 0) >= MAX_PAID_ATTEMPTS)
+        return "gave_up";
     if (message.fromAddress === self.stxAddress || message.peerBtcAddress === self.btcAddress) {
         return "from_self";
     }
@@ -164,13 +226,32 @@ function userPrompt(message) {
 }
 /** Strip reasoning blocks some models emit, collapse whitespace, fit the outbox limit. */
 export function cleanReply(raw) {
-    const text = raw.replace(/<think>[\s\S]*?<\/think>/gi, "").replace(/\s+/g, " ").trim();
+    const text = raw
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .replace(/<think>[\s\S]*$/i, "") // unterminated block: the model ran out of tokens mid-thought
+        .replace(/\s+/g, " ")
+        .trim();
     if (text.length <= MAX_REPLY_CHARS)
         return text;
     return text.slice(0, MAX_REPLY_CHARS - 1).trimEnd() + "…";
 }
+/**
+ * The inference was paid for but its response is not a usable reply. The run
+ * keeps the cap booking and counts it as a paid failure.
+ */
+export class PaidInferenceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaidInferenceError";
+    }
+}
+/** Whether a failed generation had already paid for the inference. */
+function inferencePaid(error) {
+    return error instanceof PaidInferenceError || paymentWasSent(error);
+}
 export function marketplaceReplyGenerator(model) {
     return {
+        id: model,
         async generate({ systemPrompt, message, beforePay }) {
             let price = 0;
             const result = await postWithX402Payment({
@@ -196,14 +277,25 @@ export function marketplaceReplyGenerator(model) {
                 const detail = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
                 throw new Error(`Inference request failed (${res.status}): ${detail?.slice(0, 300)}`, { cause: error });
             });
-            const data = (result.paid ? result.response.data : JSON.parse(result.text));
-            const content = data.choices?.[0]?.message?.content;
+            // A bad body after payment was still paid for: say so, so the run keeps the booking.
+            const fail = (reason) => (result.paid ? new PaidInferenceError(reason) : new Error(reason));
+            let data = result.paid ? result.response.data : result.text;
+            if (typeof data === "string") {
+                try {
+                    data = JSON.parse(data);
+                }
+                catch {
+                    throw fail(`Inference response is not JSON: ${data.slice(0, 300)}`);
+                }
+            }
+            const content = data?.choices?.[0]?.message
+                ?.content;
             if (typeof content !== "string") {
-                throw new Error(`Inference response has no choices[0].message.content: ${JSON.stringify(data).slice(0, 300)}`);
+                throw fail(`Inference response has no choices[0].message.content: ${JSON.stringify(data)?.slice(0, 300)}`);
             }
             const text = cleanReply(content);
             if (!text)
-                throw new Error("Model returned an empty reply");
+                throw fail("Model returned an empty reply");
             const pricing = result.paid
                 ? result.accept.extra?.pricing
                 : undefined;
@@ -258,13 +350,22 @@ export async function postReply(account, btcAddress, messageId, reply) {
     }
     throw new Error(`Outbox reply failed (${res.status}): ${await res.text()}`);
 }
+function requireSats(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer number of sats, got ${value}`);
+    }
+}
 export async function runAutoReply(opts) {
-    const { account, systemPrompt, dailyCapSats, maxRepliesPerRun, dryRun, generator } = opts;
-    const btcAddress = account.btcAddress;
-    if (!btcAddress?.startsWith("bc1q")) {
-        throw new Error(`Auto-reply signs with the wallet's native SegWit (bc1q) key; this wallet's BTC address is ${btcAddress ?? "missing"}.`);
+    const { account, systemPrompt, dailyCapSats, maxSatsPerReply, maxRepliesPerRun, dryRun, generator } = opts;
+    // Without a number here `spent + price > cap` is always false: no cap at all.
+    requireSats("dailyCapSats", dailyCapSats);
+    requireSats("maxSatsPerReply", maxSatsPerReply);
+    if (!account.btcAddress?.startsWith("bc1q")) {
+        throw new Error(`Auto-reply signs with the wallet's native SegWit (bc1q) key; this wallet's BTC address is ${account.btcAddress ?? "missing"}.`);
     }
+    const btcAddress = account.btcAddress;
     const self = { btcAddress, stxAddress: account.address };
+    const draftKey = draftKeyFor(systemPrompt, generator.id);
     const messages = await fetchInbox(btcAddress);
     const ledger = await readAddressLedger(btcAddress);
     const summary = {
@@ -288,23 +389,13 @@ export async function runAutoReply(opts) {
             eligible.push(message);
     }
     summary.eligible = eligible.length;
-    let processed = 0;
-    for (const message of eligible) {
-        if (summary.stoppedEarly) {
-            summary.skipped.push({ messageId: message.messageId, reason: summary.stoppedEarly });
-            continue;
-        }
-        if (processed >= maxRepliesPerRun) {
-            summary.skipped.push({ messageId: message.messageId, reason: "run_limit" });
-            continue;
-        }
-        processed++;
+    async function answer(message, saved) {
+        const id = message.messageId;
         const from = message.peerBtcAddress ?? message.fromAddress;
-        // A reply paid for in an earlier run whose post failed: post it, don't pay again.
-        const saved = dryRun ? undefined : ledger.pending[message.messageId];
         let generated;
         if (saved) {
-            generated = { text: saved, inferenceCostSats: 0 };
+            // Paid for already (a failed post, or a dry-run draft): use it, don't pay again.
+            generated = { text: saved.text, inferenceCostSats: 0 };
         }
         else {
             let booked = 0;
@@ -313,66 +404,117 @@ export async function runAutoReply(opts) {
                     systemPrompt,
                     message,
                     beforePay: async (price) => {
+                        if (!Number.isInteger(price) || price < 0)
+                            throw new Error(`Refusing an invalid inference price: ${price}`);
+                        if (price > maxSatsPerReply)
+                            throw new PriceCeilingError(price, maxSatsPerReply);
                         await reserveDailySats(btcAddress, price, dailyCapSats);
                         booked = price;
                     },
                 });
             }
             catch (error) {
-                if (booked && !paymentWasSent(error))
+                const paid = inferencePaid(error);
+                if (booked && !paid)
                     await releaseDailySats(btcAddress, booked);
-                if (error instanceof DailyCapError) {
-                    summary.stoppedEarly = "daily_cap";
-                    summary.skipped.push({ messageId: message.messageId, reason: "daily_cap" });
-                    continue;
+                if (error instanceof DailyCapError || error instanceof PriceCeilingError || error instanceof SpendLimitError) {
+                    summary.stoppedEarly =
+                        error instanceof DailyCapError ? "daily_cap" : error instanceof PriceCeilingError ? "price_ceiling" : "spend_limit";
+                    summary.skipped.push({ messageId: id, reason: summary.stoppedEarly });
+                    return;
                 }
-                summary.failed.push({ messageId: message.messageId, error: errorText(error), replySaved: false });
-                continue;
+                let gaveUp = false;
+                if (paid) {
+                    summary.inferenceSatsSpent += booked;
+                    const attempts = await updateLedger(btcAddress, (l) => {
+                        l.paidFailures[id] = (l.paidFailures[id] ?? 0) + 1;
+                        return l.paidFailures[id];
+                    });
+                    gaveUp = attempts >= MAX_PAID_ATTEMPTS;
+                }
+                summary.failed.push({ messageId: id, error: errorText(error), replySaved: false, ...(gaveUp && { gaveUp }) });
+                return;
             }
             summary.inferenceSatsSpent += generated.inferenceCostSats;
         }
         const record = {
-            messageId: message.messageId,
+            messageId: id,
             from,
             reply: generated.text,
             inferenceCostSats: generated.inferenceCostSats,
             ...(generated.txid && { inferenceTxid: generated.txid }),
             ...(generated.provider && { provider: generated.provider }),
+            ...(saved?.from === "pending" && { reusedPending: true }),
+            ...(saved?.from === "draft" && { reusedDraft: true }),
         };
         if (dryRun) {
+            if (!saved) {
+                await updateLedger(btcAddress, (l) => {
+                    l.drafts[id] = { text: generated.text, key: draftKey };
+                });
+            }
             summary.drafted.push(record);
-            continue;
+            return;
         }
+        const savePending = () => updateLedger(btcAddress, (l) => {
+            l.pending[id] = generated.text;
+            delete l.drafts[id];
+        });
         try {
-            const posted = await postReply(account, btcAddress, message.messageId, generated.text);
+            const posted = await postReply(account, btcAddress, id, generated.text);
             if (posted.status === "rate_limited") {
-                await updateLedger(btcAddress, (l) => {
-                    l.pending[message.messageId] = generated.text;
-                });
+                await savePending();
                 summary.failed.push({
-                    messageId: message.messageId,
+                    messageId: id,
                     error: `Outbox rate limited${posted.retryAfter ? `; retry after ${posted.retryAfter}s` : ""}`,
                     replySaved: true,
                 });
                 summary.stoppedEarly = "rate_limited";
-                continue;
+                return;
             }
             await updateLedger(btcAddress, (l) => {
-                l.handled[message.messageId] = posted.status === "posted" ? (posted.repliedAt ?? new Date().toISOString()) : "already_replied";
-                delete l.pending[message.messageId];
+                l.handled[id] = posted.status === "posted" ? (posted.repliedAt ?? new Date().toISOString()) : "already_replied";
+                delete l.pending[id];
+                delete l.drafts[id];
+                delete l.paidFailures[id];
             });
             if (posted.status === "already_replied") {
-                summary.skipped.push({ messageId: message.messageId, reason: "already_replied" });
+                summary.skipped.push({ messageId: id, reason: "already_replied" });
             }
             else {
-                summary.replied.push({ ...record, ...(saved && { reusedPending: true }) });
+                summary.replied.push(record);
             }
         }
         catch (error) {
+            await savePending();
+            summary.failed.push({ messageId: id, error: errorText(error), replySaved: true });
+        }
+    }
+    let processed = 0;
+    for (const message of eligible) {
+        if (summary.stoppedEarly) {
+            summary.skipped.push({ messageId: message.messageId, reason: summary.stoppedEarly });
+            continue;
+        }
+        if (processed >= maxRepliesPerRun) {
+            summary.skipped.push({ messageId: message.messageId, reason: "run_limit" });
+            continue;
+        }
+        // Claim before paying: another run (this server or the skills CLI) may have
+        // answered or claimed it since the snapshot above.
+        const claim = await claimMessage(btcAddress, message.messageId, draftKey);
+        if (claim.skip) {
+            summary.skipped.push({ messageId: message.messageId, reason: claim.skip });
+            continue;
+        }
+        processed++;
+        try {
+            await answer(message, claim.saved);
+        }
+        finally {
             await updateLedger(btcAddress, (l) => {
-                l.pending[message.messageId] = generated.text;
+                delete l.claimed[message.messageId];
             });
-            summary.failed.push({ messageId: message.messageId, error: errorText(error), replySaved: true });
         }
     }
     const after = await readAddressLedger(btcAddress);

package/dist/services/x402-post.js

@@ -1,6 +1,6 @@
 import axios from "axios";
 import { wrapAxiosWithPayment, decodePaymentRequired, decodePaymentResponse, X402_HEADERS, } from "x402-stacks";
-import { createApiClient, getAccount, NETWORK } from "./x402.service.js";
+import { createApiClient, getAccount, isSponsoredRequirement, NETWORK } from "./x402.service.js";
 import { getSpendLimiter } from "./spend-limiter.js";
 /**
  * True when a failed x402-stacks request had already carried the signed
@@ -55,13 +55,13 @@ export async function postWithX402Payment(options) {
         throw new Error("402 response missing or empty payment-required header");
     }
     const accept = paymentRequired.accepts[0];
-    // The SDK signs a sponsored (fee 0) transfer exactly when the requirement
-    // names a fee payer — mirror its check.
-    const sponsored = typeof accept.extra?.feePayer === "string";
+    const sponsored = isSponsoredRequirement(accept.extra);
     if (beforePay)
         await beforePay(accept, sponsored);
     let response;
-    if (sponsored) {
+    // The SDK signs a sponsored (fee 0) transfer only when the requirement names
+    // a fee payer; `sponsored: true` without one is signed by createApiClient.
+    if (sponsored && typeof accept.extra?.feePayer === "string") {
         const account = await getAccount();
         // The amount is a signed sBTC spend: book it before signing.
         const spendLimiter = getSpendLimiter();
@@ -88,7 +88,8 @@ export async function postWithX402Payment(options) {
         }
     }
     else {
-        // Self-paid: createApiClient clamps the fee and meters the spend.
+        // createApiClient signs (self-paid with a clamped fee, or sponsored on
+        // `sponsored: true`) and meters the spend.
         const api = await createApiClient(baseUrl, { toolName, asset: accept.asset });
         response = await api.post(url, body, {
             headers: { "Content-Type": "application/json" },

package/dist/services/x402.service.d.ts

@@ -1,4 +1,4 @@
-import { type AxiosInstance } from "axios";
+import { type AxiosInstance, type AxiosRequestConfig } from "axios";
 import { type PaymentRequirementsV2 } from "../utils/x402-protocol.js";
 import { NETWORK, API_URL, type Network } from "../config/networks.js";
 import type { Account } from "../transactions/builder.js";
@@ -45,9 +45,29 @@ export interface PaymentRequirements {
     recipient: string;
     network: string;
     account: Account;
-    /** True when the endpoint advertised `extra.sponsored` — the relay pays the STX fee. */
+    /** True when the endpoint advertised `extra.feePayer` or `extra.sponsored` — the relay pays the STX fee. */
     sponsored: boolean;
 }
+/**
+ * Who pays STX gas for the payment the interceptor signed. Sponsored: fee 0,
+ * the endpoint's relay pays at settlement. Self-paid: the sender's own fee.
+ */
+export interface X402PaymentGas {
+    sponsored: boolean;
+    feeUstx: string;
+}
+declare module "axios" {
+    interface AxiosRequestConfig {
+        /** Set by the x402 interceptor on the paid retry; read with getPaymentGas. */
+        x402PaymentGas?: X402PaymentGas;
+    }
+}
+/**
+ * Read the gas decision the interceptor attached to a paid request's config
+ * (`response.config` on success, `error.config` on failure). Undefined when
+ * no payment was signed.
+ */
+export declare function getPaymentGas(config: AxiosRequestConfig | undefined): X402PaymentGas | undefined;
 /**
  * Options for createApiClient
  */
@@ -128,6 +148,14 @@ export type PaymentTokenType = 'STX' | 'sBTC' | 'unsupported';
  * @param asset - Full contract identifier or token name
  */
 export declare function detectTokenType(asset: string): PaymentTokenType;
+/**
+ * Whether an x402 payment requirement offers gas sponsorship (sign with fee 0,
+ * the relay co-signs and pays the STX fee). x402-stacks documents a non-empty
+ * `extra.feePayer` as the signal; `extra.sponsored === true` is also honored
+ * for endpoints that send only that, and an explicit `sponsored: false` wins.
+ * Shared by createApiClient and x402-post so both paths use one rule.
+ */
+export declare function isSponsoredRequirement(extra?: Record<string, unknown>): boolean;
 /**
  * Memo for an x402 payment from the server's `extra.payment_id`, cut to the
  * first 34 UTF-8 bytes (the Stacks memo limit) on a character boundary.

package/dist/services/x402.service.js

@@ -367,6 +367,14 @@ export async function mnemonicToAccount(mnemonic, network) {
         network,
     };
 }
+/**
+ * Read the gas decision the interceptor attached to a paid request's config
+ * (`response.config` on success, `error.config` on failure). Undefined when
+ * no payment was signed.
+ */
+export function getPaymentGas(config) {
+    return config?.x402PaymentGas;
+}
 /**
  * Build a canonical absolute URL for a request so that the L402 attempt
  * counter and macaroon cache are keyed by the actual endpoint, not the
@@ -662,7 +670,7 @@ export async function createApiClient(baseUrl, options) {
             }
             // The endpoint offers gas sponsorship: sign with `sponsored: true, fee: 0`
             // and its relay co-signs and pays the STX fee at settlement.
-            const sponsored = selectedOption.extra?.sponsored === true;
+            const sponsored = isSponsoredRequirement(selectedOption.extra);
             // Invoke pre-payment callback (e.g. balance check) before signing/broadcasting.
             // If the callback throws, the payment is aborted and the error propagates to the caller.
             if (options?.onBeforePayment) {
@@ -758,6 +766,7 @@ export async function createApiClient(baseUrl, options) {
             const originalRequest = error.config;
             originalRequest.headers = originalRequest.headers || {};
             originalRequest.headers[X402_HEADERS.PAYMENT_SIGNATURE] = encodedPayload;
+            originalRequest.x402PaymentGas = { sponsored, feeUstx: fee.toString() };
             return axiosInstance.request(originalRequest);
         }
         catch (paymentError) {
@@ -827,6 +836,18 @@ export function detectTokenType(asset) {
     }
     return 'unsupported';
 }
+/**
+ * Whether an x402 payment requirement offers gas sponsorship (sign with fee 0,
+ * the relay co-signs and pays the STX fee). x402-stacks documents a non-empty
+ * `extra.feePayer` as the signal; `extra.sponsored === true` is also honored
+ * for endpoints that send only that, and an explicit `sponsored: false` wins.
+ * Shared by createApiClient and x402-post so both paths use one rule.
+ */
+export function isSponsoredRequirement(extra) {
+    if (extra?.sponsored === false)
+        return false;
+    return (typeof extra?.feePayer === "string" && extra.feePayer !== "") || extra?.sponsored === true;
+}
 const STACKS_MEMO_MAX_BYTES = 34;
 /**
  * Memo for an x402 payment from the server's `extra.payment_id`, cut to the

package/dist/tools/endpoint.tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { createApiClient, API_URL, probeEndpoint, formatPaymentAmount, checkSufficientBalance, generateDedupKey, checkDedupCache, recordTransaction, X402_DEDUP_TTL_MS, NETWORK } from "../services/x402.service.js";
+import { createApiClient, API_URL, probeEndpoint, formatPaymentAmount, checkSufficientBalance, generateDedupKey, checkDedupCache, recordTransaction, X402_DEDUP_TTL_MS, NETWORK, getPaymentGas } from "../services/x402.service.js";
 import { STATIC_ENDPOINTS, formatEndpointsTable } from "../endpoints/registry.js";
 import { discoverOpenApiEndpoints, fetchDirectoryEntries, } from "../services/x402-discovery.service.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
@@ -127,6 +127,18 @@ function formatProbeResponse(result, method, fullUrl, callWithOptions, messagePr
         callWith: buildCallWith(callWithOptions),
     });
 }
+/**
+ * One line saying who pays STX gas for a payment that was signed but whose
+ * call failed, or "" when none was signed. The fee is only charged if the
+ * payment settles on chain, which a failed call does not tell us.
+ */
+function formatGasLine(gas) {
+    if (!gas)
+        return "";
+    return gas.sponsored
+        ? "\n\nGas: sponsored (the endpoint's relay pays the STX fee if the payment settles)."
+        : `\n\nGas: self-paid; the payment was signed with a ${gas.feeUstx} uSTX fee, charged only if it settles on chain.`;
+}
 export function registerEndpointTools(server) {
     // List x402 endpoints
     server.registerTool("list_x402_endpoints", {
@@ -273,6 +285,8 @@ Supported sources:
 
 Use list_x402_endpoints to discover available endpoints.
 
+A paid result includes txid and gas: {sponsored, feeUstx}. Sponsored means the endpoint's relay pays the STX fee (feeUstx "0"); otherwise this wallet paid feeUstx on top of the price.
+
 For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs a standard sBTC transfer and settles directly through the x402 facilitator.`,
         inputSchema: z.object({
             method: z
@@ -402,10 +416,13 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 : txid !== null
                     ? { txid }
                     : {};
+            // Who paid STX gas for the payment, as decided when it was signed.
+            const gas = getPaymentGas(response.config);
             return createJsonResponse({
                 endpoint: `${method} ${fullUrl}`,
                 response: response.data,
                 ...txidFields,
+                ...(gas && { gas }),
             });
         }
         catch (error) {
@@ -423,6 +440,9 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
             // Mirrors the success path, including the synthetic pending marker
             // used when the txid is not yet observable.
             const paymentSigHeader = axiosError.config?.headers?.[X402_HEADERS.PAYMENT_SIGNATURE];
+            // A signed payment may still settle after the call failed, so say who
+            // pays gas on every error path too.
+            const gasLine = formatGasLine(getPaymentGas(axiosError.config));
             if (paymentSigHeader && dedupKey) {
                 const broadcastTxid = extractTxidFromPaymentSignature(paymentSigHeader);
                 await recordTransaction(dedupKey, broadcastTxid ?? `pending:${dedupKey}`);
@@ -453,7 +473,7 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 }
                 return {
                     ...baseError,
-                    content: [{ type: "text", text }],
+                    content: [{ type: "text", text: text + gasLine }],
                 };
             }
             if (paymentSigHeader) {
@@ -480,11 +500,29 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                                     `Transaction recovery info:\n` +
                                     `  txid: ${confirmation.txid}\n` +
                                     `  status: ${confirmation.status}\n` +
-                                    `  explorer: ${confirmation.explorer}`,
+                                    `  explorer: ${confirmation.explorer}` +
+                                    gasLine,
                             },
                         ],
                     };
                 }
+                // No txid from the header: a sponsored payment (the relay assigns its
+                // txid when it sponsors) or one that didn't decode. It may still have
+                // settled, so point at where the real txid can be found.
+                const baseError = formatEndpointError(error, label);
+                return {
+                    ...baseError,
+                    content: [
+                        {
+                            type: "text",
+                            text: baseError.content[0].text +
+                                `\n\nA payment was signed, but its txid is not known here` +
+                                (fallbackPaymentId ? ` (paymentId: ${fallbackPaymentId})` : "") +
+                                `. It may have settled: query get_account_transactions for this wallet before paying again.` +
+                                gasLine,
+                        },
+                    ],
+                };
             }
             return formatEndpointError(error, label);
         }

package/dist/tools/inbox-auto-reply.tools.d.ts

@@ -1,8 +1,8 @@
 /**
  * Inbox auto-reply tools.
  *
- * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats
- *   in ~/.aibtc/config.json (no args = show the current settings)
+ * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats /
+ *   maxSatsPerReply in ~/.aibtc/config.json (no args = show the current settings)
  * - inbox_auto_reply: answer paid, unanswered inbox messages with a reply
  *   written by an AIBTC Inference Marketplace model (x402, sBTC), then sign and
  *   post it to the outbox. Built to be called from an agent's autonomy loop.

package/dist/tools/inbox-auto-reply.tools.js

@@ -1,8 +1,8 @@
 /**
  * Inbox auto-reply tools.
  *
- * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats
- *   in ~/.aibtc/config.json (no args = show the current settings)
+ * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats /
+ *   maxSatsPerReply in ~/.aibtc/config.json (no args = show the current settings)
  * - inbox_auto_reply: answer paid, unanswered inbox messages with a reply
  *   written by an AIBTC Inference Marketplace model (x402, sBTC), then sign and
  *   post it to the outbox. Built to be called from an agent's autonomy loop.
@@ -11,9 +11,29 @@
  */
 import { z } from "zod";
 import { getAccount, NETWORK } from "../services/x402.service.js";
-import { DEFAULT_AUTO_REPLY_MODEL, DEFAULT_DAILY_CAP_SATS, DEFAULT_MAX_REPLIES_PER_RUN, listLiveModels, marketplaceReplyGenerator, runAutoReply, } from "../services/inbox-auto-reply.service.js";
+import { DEFAULT_AUTO_REPLY_MODEL, DEFAULT_DAILY_CAP_SATS, DEFAULT_MAX_REPLIES_PER_RUN, DEFAULT_MAX_SATS_PER_REPLY, listLiveModels, marketplaceReplyGenerator, runAutoReply, } from "../services/inbox-auto-reply.service.js";
 import { readAppConfig, writeAppConfig } from "../utils/storage.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
+/**
+ * The stored sat limits, defaulted and checked. The config file is plain JSON
+ * (shared with the skills CLI), so a missing or hand-edited value must not
+ * turn into "no limit" at run time.
+ */
+function autoReplyLimits(config) {
+    const limit = (name, value, fallback) => {
+        if (value === undefined || value === null)
+            return fallback;
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+            throw new Error(`inboxAutoReply.${name} in ~/.aibtc/config.json must be a non-negative integer, got ${JSON.stringify(value)}. ` +
+                `Fix it with inbox_auto_reply_configure { ${name}: <sats> }.`);
+        }
+        return value;
+    };
+    return {
+        dailyCapSats: limit("dailyCapSats", config.dailyCapSats, DEFAULT_DAILY_CAP_SATS),
+        maxSatsPerReply: limit("maxSatsPerReply", config.maxSatsPerReply, DEFAULT_MAX_SATS_PER_REPLY),
+    };
+}
 function requireMainnet() {
     if (NETWORK !== "mainnet") {
         throw new Error("Inbox auto-reply is mainnet only: the aibtc.com inbox and the inference marketplace settle in mainnet sBTC. Set NETWORK=mainnet.");
@@ -25,7 +45,7 @@ export function registerInboxAutoReplyTools(server) {
             "settings. A systemPrompt (the agent's voice / personality / what it can help with) is required before " +
             "auto-reply can be enabled. The model must be live on inference.aibtc.com; it is checked against the " +
             "catalog when set. dailyCapSats caps sats spent on reply inference per UTC day, on top of the wallet-wide " +
-            "spending limit.",
+            "spending limit. maxSatsPerReply is the most one reply may cost; a higher quote stops the run unpaid.",
         inputSchema: z.object({
             enabled: z.boolean().optional().describe("Allow inbox_auto_reply to post replies. Dry runs work while disabled."),
             model: z
@@ -44,12 +64,22 @@ export function registerInboxAutoReplyTools(server) {
                 .min(0)
                 .optional()
                 .describe(`Most sats spent on reply inference per UTC day. Default ${DEFAULT_DAILY_CAP_SATS}.`),
+            maxSatsPerReply: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe(`Most sats paid for one reply. Default ${DEFAULT_MAX_SATS_PER_REPLY}.`),
         }),
-    }, async ({ enabled, model, systemPrompt, dailyCapSats }) => {
+    }, async ({ enabled, model, systemPrompt, dailyCapSats, maxSatsPerReply }) => {
         try {
             const config = await readAppConfig();
             const current = config.inboxAutoReply;
-            if (enabled === undefined && model === undefined && systemPrompt === undefined && dailyCapSats === undefined) {
+            if (enabled === undefined &&
+                model === undefined &&
+                systemPrompt === undefined &&
+                dailyCapSats === undefined &&
+                maxSatsPerReply === undefined) {
                 return createJsonResponse({
                     configured: Boolean(current),
                     settings: current ?? null,
@@ -69,6 +99,7 @@ export function registerInboxAutoReplyTools(server) {
                 model: model ?? current?.model ?? DEFAULT_AUTO_REPLY_MODEL,
                 systemPrompt: systemPrompt ?? current?.systemPrompt ?? "",
                 dailyCapSats: dailyCapSats ?? current?.dailyCapSats ?? DEFAULT_DAILY_CAP_SATS,
+                maxSatsPerReply: maxSatsPerReply ?? current?.maxSatsPerReply ?? DEFAULT_MAX_SATS_PER_REPLY,
             };
             if (next.enabled && !next.systemPrompt) {
                 throw new Error("Set a systemPrompt before enabling auto-reply.");
@@ -84,12 +115,14 @@ export function registerInboxAutoReplyTools(server) {
         description: "Answer this agent's paid aibtc.com inbox messages automatically. In one call: reads the inbox, picks paid, " +
             "settled, unanswered messages (oldest first), writes each reply with an AIBTC Inference Marketplace model " +
             "(paid per request in sBTC via x402, ~1 sat), signs it (BIP-322) and posts it to the outbox (free). " +
-            "Never answers a message twice, stops at the daily cap, and returns a summary: checked, replied, " +
+            "Never answers a message twice (overlapping runs skip a message another run is answering), stops at the " +
+            "daily cap or on a quote above maxSatsPerReply, gives up on a message after 2 paid failures, and returns a summary: checked, replied, " +
             "skipped (with reason), failed, inference sats spent and inference cap remaining.\n\n" +
             "Posting a reply is free; the only cost is the inference call that writes it. " +
             "Call it from the autonomy loop when the heartbeat or inbox shows unread messages. Configure first with " +
             "inbox_auto_reply_configure. dryRun writes (and pays for) replies without posting them, so the operator " +
-            "can review the voice. Requires an unlocked wallet with a bc1q address and a little sBTC. Mainnet only.",
+            "can review the voice; each draft is saved and reused by later dry runs and the real run while the " +
+            "systemPrompt and model are unchanged. Requires an unlocked wallet with a bc1q address and a little sBTC. Mainnet only.",
         inputSchema: z.object({
             maxRepliesPerRun: z
                 .number()
@@ -101,7 +134,8 @@ export function registerInboxAutoReplyTools(server) {
             dryRun: z
                 .boolean()
                 .optional()
-                .describe("Generate replies (inference is still paid) but do not post them or mark messages handled."),
+                .describe("Generate replies without posting them or marking messages handled. A new draft is paid for once; " +
+                "a saved draft with the same systemPrompt and model is reused free, here and by the real run."),
         }),
     }, async ({ maxRepliesPerRun, dryRun }) => {
         try {
@@ -114,11 +148,12 @@ export function registerInboxAutoReplyTools(server) {
             if (!config.enabled && !isDryRun) {
                 throw new Error("Inbox auto-reply is disabled. Enable it with inbox_auto_reply_configure { enabled: true }, or pass dryRun: true to preview replies.");
             }
+            const limits = autoReplyLimits(config);
             const account = await getAccount();
             const summary = await runAutoReply({
                 account,
                 systemPrompt: config.systemPrompt,
-                dailyCapSats: config.dailyCapSats,
+                ...limits,
                 maxRepliesPerRun: maxRepliesPerRun ?? DEFAULT_MAX_REPLIES_PER_RUN,
                 dryRun: isDryRun,
                 generator: marketplaceReplyGenerator(config.model),
@@ -131,7 +166,7 @@ export function registerInboxAutoReplyTools(server) {
                 repliedCount: summary.replied.length,
                 skippedCount: summary.skipped.length,
                 failedCount: summary.failed.length,
-                dailyCapSats: config.dailyCapSats,
+                ...limits,
             });
         }
         catch (error) {

package/dist/utils/storage.d.ts

@@ -45,6 +45,8 @@ export interface AppConfig {
         model: string;
         systemPrompt: string;
         dailyCapSats: number;
+        /** Most sats paid for one reply. Missing in configs written before it existed. */
+        maxSatsPerReply?: number;
     };
 }
 /**

package/dist/utils/x402-recovery.d.ts

@@ -14,7 +14,10 @@ import { type Network } from "../config/networks.js";
  * The payment-signature header is a base64-encoded JSON PaymentPayloadV2 object
  * whose payload.transaction field contains the signed transaction hex.
  *
- * Returns the txid string (64-char hex, no 0x prefix), or null if extraction fails.
+ * Returns the txid string (64-char hex, no 0x prefix), or null if extraction
+ * fails or the payment is sponsored. A sponsored transaction gets its txid only
+ * when the relay adds its sponsor signature and fee, so the txid of the signed
+ * payment in the header never appears on chain.
  */
 export declare function extractTxidFromPaymentSignature(paymentSignatureHeader: string): string | null;
 /**

package/dist/utils/x402-recovery.js

@@ -7,7 +7,7 @@
  * Used by inbox.tools.ts and endpoint.tools.ts as an operational fallback
  * when canonical paymentId polling is unavailable or inconclusive.
  */
-import { deserializeTransaction } from "@stacks/transactions";
+import { AuthType, deserializeTransaction } from "@stacks/transactions";
 import { getHiroApi } from "../services/hiro-api.js";
 import { getExplorerTxUrl } from "../config/networks.js";
 import { decodePaymentPayload } from "./x402-protocol.js";
@@ -20,7 +20,10 @@ import { decodePaymentPayload } from "./x402-protocol.js";
  * The payment-signature header is a base64-encoded JSON PaymentPayloadV2 object
  * whose payload.transaction field contains the signed transaction hex.
  *
- * Returns the txid string (64-char hex, no 0x prefix), or null if extraction fails.
+ * Returns the txid string (64-char hex, no 0x prefix), or null if extraction
+ * fails or the payment is sponsored. A sponsored transaction gets its txid only
+ * when the relay adds its sponsor signature and fee, so the txid of the signed
+ * payment in the header never appears on chain.
  */
 export function extractTxidFromPaymentSignature(paymentSignatureHeader) {
     try {
@@ -33,6 +36,9 @@ export function extractTxidFromPaymentSignature(paymentSignatureHeader) {
         const hexWithout0x = txHex.startsWith("0x") ? txHex.slice(2) : txHex;
         const txBytes = Buffer.from(hexWithout0x, "hex");
         const tx = deserializeTransaction(txBytes);
+        if (tx.auth.authType === AuthType.Sponsored) {
+            return null;
+        }
         return tx.txid();
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.78.0",
+  "version": "1.79.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.78.0 # x-release-please-version
+  version: 1.79.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -257,6 +257,7 @@ reply stays free; the only cost is the inference that writes it.
 | `systemPrompt` | — (required) | Your voice: who you are, what you offer, what you won't do |
 | `model` | `meta-llama/Llama-3.1-8B-Instruct` | Marketplace model id; must be live at `https://inference.aibtc.com/v1/models` |
 | `dailyCapSats` | 1000 | Most sats spent on reply inference per UTC day |
+| `maxSatsPerReply` | 10 | Most sats paid for one reply; a higher quote stops the run unpaid |
 | `enabled` | false | Must be true before replies are posted |
 
 ```
@@ -264,7 +265,8 @@ inbox_auto_reply_configure({ systemPrompt: "You are K9, a Stacks research agent.
 ```
 
 Check the voice first with a dry run: it writes the replies (and pays for the
-inference) but posts nothing:
+inference) but posts nothing. Drafts are saved, so a later dry run or the real
+run reuses them free while the system prompt and model are unchanged:
 
 ```
 inbox_auto_reply({ dryRun: true, maxRepliesPerRun: 2 })
@@ -282,7 +284,8 @@ works oldest first from the newest 100 messages.
 **Safety rules built in:**
 - **No double replies.** A message is skipped when the inbox shows `repliedAt`,
   when your local ledger (`~/.aibtc/inbox-auto-reply.json`) has it, or when the
-  outbox answers 409.
+  outbox answers 409. Overlapping runs skip a message another run is answering,
+  and a message that fails twice after payment is given up.
 - **No reply loops.** Replies go to the outbox and never land in an inbox; every
   inbox message is a paid send. One agent's auto-reply cannot trigger another's.
 - **Spend is capped twice.** The cap is checked before each inference is signed,
@@ -293,8 +296,9 @@ works oldest first from the newest 100 messages.
 
 **Reading the result:** `replied`, `skipped` (with `reason`: `already_replied`,
 `already_handled`, `unpaid`, `payment_not_settled`, `from_self`, `run_limit`,
-`daily_cap`, `rate_limited`) and `failed` (with `error`, and `replySaved` when
-a paid reply is waiting for the next run). Also returned: `inferenceSatsSpent`,
+`in_progress`, `gave_up`, `daily_cap`, `price_ceiling`, `spend_limit`,
+`rate_limited`) and `failed` (with `error`, `replySaved` when a paid reply is
+waiting for the next run, and `gaveUp` when it will not be retried). Also returned: `inferenceSatsSpent`,
 `inferenceSatsSpentToday` and `inferenceCapRemainingSats`. Each reply carries its `inferenceTxid`.
 When `stoppedEarly` is `daily_cap`, wait for the next UTC day or ask your
 operator to raise the cap. Don't raise it yourself.