@aibtc/mcp-server 1.77.0 → 1.79.0

package/README.md

@@ -118,7 +118,7 @@ npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet
 
 ### Tool Profiles
 
-Every tool definition is loaded into the model's context, so `--install` writes `AIBTC_TOOLS=core`: a lean core of 24 tools: wallet (including `wallet_rotate_password`; `wallet_export` is in the `wallet` group so the mnemonic isn't one call away), balances, STX/BTC/sBTC transfers, x402 (`list_x402_endpoints`, `probe_x402_endpoint`, `execute_x402_endpoint`) and earning (`earning_opportunities`, `bounty_list/get/submit`, `identity_register`).
+Every tool definition is loaded into the model's context, so `--install` writes `AIBTC_TOOLS=core`: a lean core of 26 tools: wallet (including `wallet_rotate_password`; `wallet_export` is in the `wallet` group so the mnemonic isn't one call away), balances, STX/BTC/sBTC transfers, x402 (`list_x402_endpoints`, `probe_x402_endpoint`, `execute_x402_endpoint`) earning (`earning_opportunities`, `bounty_list/get/submit`, `identity_register`) and inbox auto-reply (`inbox_auto_reply`, `inbox_auto_reply_configure`).
 
 Add groups with `AIBTC_TOOLS=core,defi,ordinals` in the server's `env` (the core is always included), or load everything with `AIBTC_TOOLS=all` / `--profile full`. If `AIBTC_TOOLS` is not set at all, every tool is loaded, so configs written by earlier versions keep all their tools:
 
@@ -538,6 +538,8 @@ Read-only discovery of onchain agent work on [TaskMarket](https://taskmarket.dev
 | Tool | Description |
 |------|-------------|
 | `send_inbox_message_direct` | Send a paid x402 message to another agent's inbox (sBTC cost; STX gas is sponsored when the inbox offers it) |
+| `inbox_auto_reply` | Answer paid, unanswered inbox messages with an Inference Marketplace model (x402, sBTC), sign and post the replies; daily cap, no double replies |
+| `inbox_auto_reply_configure` | Set the auto-reply system prompt, model, daily cap and on/off switch |
 
 ## Usage Examples
 

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

@@ -0,0 +1,188 @@
+/**
+ * Inbox auto-reply: answer paid aibtc.com inbox messages with a reply written
+ * by a model on the AIBTC Inference Marketplace, paid per request via x402.
+ *
+ * Loop safety is structural, not a filter: a reply is posted to the replier's
+ * outbox and never lands in anyone's inbox, and every inbox message is a paid
+ * 100-sat send. Two auto-repliers cannot bounce messages at each other without
+ * someone paying for each round. The inbox exposes no "is a reply" field, so
+ * there is nothing to filter on; eligibility is "paid, settled, unanswered".
+ *
+ * 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 type { Account } from "../transactions/builder.js";
+export declare const INBOX_API = "https://aibtc.com/api";
+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 {
+    messageId: string;
+    fromAddress: string;
+    toBtcAddress: string;
+    toStxAddress?: string;
+    content: string;
+    paymentTxid?: string;
+    paymentSatoshis?: number;
+    paymentStatus?: string;
+    recoveredViaTxid?: boolean;
+    sentAt: string;
+    repliedAt?: string;
+    direction?: string;
+    peerBtcAddress?: string;
+    peerDisplayName?: string;
+}
+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>;
+    /**
+     * messageId -> reply text that was paid for but not posted (the outbox
+     * failed). The next run posts it instead of paying for a new one.
+     */
+    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;
+export declare function readAddressLedger(btcAddress: string): Promise<AddressLedger>;
+export declare class DailyCapError extends Error {
+    readonly spent: number;
+    readonly cap: number;
+    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
+ * is paid when it carries a payment txid and sats. It is settled when the
+ * relay confirmed it, it was recovered from a confirmed txid, or it has no
+ * `paymentStatus` at all: messages from before the field existed were only
+ * delivered once their payment settled. Any other status (`pending`, ...) is
+ * a staged payment that may still fail.
+ */
+export declare function skipReason(message: InboxMessage, self: {
+    btcAddress: string;
+    stxAddress: string;
+}, ledger: AddressLedger): SkipReason | null;
+export interface GeneratedReply {
+    text: string;
+    /** Sats paid for the generation (0 when the source is free). */
+    inferenceCostSats: number;
+    txid?: string;
+    provider?: string;
+}
+/**
+ * Where reply text comes from. The marketplace is the only source today (every
+ * auto-reply is metered marketplace usage); another source, such as the
+ * 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;
+        /** Throw from here to refuse the price before anything is signed. */
+        beforePay: (priceSats: number) => Promise<void>;
+    }): Promise<GeneratedReply>;
+}
+/** 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[]>;
+export declare function replySigningMessage(messageId: string, reply: string): string;
+/** BIP-322 over the outbox message with the wallet's native SegWit key. */
+export declare function signReply(account: Account, messageId: string, reply: string): string;
+export type PostReplyResult = {
+    status: "posted";
+    repliedAt?: string;
+} | {
+    status: "already_replied";
+} | {
+    status: "rate_limited";
+    retryAfter?: number;
+};
+export declare function postReply(account: Account, btcAddress: string, messageId: string, reply: string): Promise<PostReplyResult>;
+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: 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?: StopReason;
+    inferenceSatsSpent: number;
+    inferenceSatsSpentToday: number;
+    inferenceCapRemainingSats: number;
+}
+export declare function runAutoReply(opts: AutoReplyRunOptions): Promise<AutoReplyRunSummary>;
+export {};
+//# sourceMappingURL=inbox-auto-reply.service.d.ts.map