@agentwonderland/mcp 0.1.14 → 0.1.16

package/dist/core/config.d.ts

@@ -68,6 +68,10 @@ export declare function removeWallet(id: string): void;
  * Get card configuration.
  */
 export declare function getCardConfig(): CardConfig | null;
+/**
+ * Save card configuration after setup.
+ */
+export declare function setCardConfig(card: CardConfig | null): void;
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/dist/core/config.js

@@ -259,6 +259,12 @@ export function removeWallet(id) {
 export function getCardConfig() {
     return getConfig().card;
 }
+/**
+ * Save card configuration after setup.
+ */
+export function setCardConfig(card) {
+    saveConfig({ card });
+}
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/dist/tools/run.js

@@ -1,10 +1,34 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
 import { uploadLocalFiles } from "../core/file-upload.js";
-import { getConfiguredMethods, hasWalletConfigured } from "../core/payments.js";
+import { getConfiguredMethods, hasWalletConfigured, getWalletAddress } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
 import { storeFeedbackToken } from "./_token-cache.js";
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_MS = 120000; // 2 minutes
+async function pollJobUntilDone(jobId, agentName) {
+    const deadline = Date.now() + POLL_MAX_MS;
+    const walletAddress = await getWalletAddress();
+    const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        try {
+            const job = await apiGet(`/jobs/${jobId}${walletParam}`);
+            if (job.status === "completed") {
+                return { status: "completed", output: job.output };
+            }
+            if (job.status === "failed") {
+                return { status: "failed", output: job.output, error_code: job.error_code };
+            }
+            // Still processing — continue polling
+        }
+        catch {
+            // Ignore poll errors, keep trying until deadline
+        }
+    }
+    return { status: "failed", error_code: "POLL_TIMEOUT" };
+}
 function text(t) {
     return { content: [{ type: "text", text: t }] };
 }
@@ -99,6 +123,38 @@ export function registerRunTools(server) {
         }
         const actualCost = result.cost;
         const status = result.status;
+        // Async agent — poll until complete
+        if (status === "processing") {
+            const pollResult = await pollJobUntilDone(jobId, agentName);
+            if (pollResult.status === "completed") {
+                const asyncFormatted = formatRunResult({
+                    ...result,
+                    status: "success",
+                    output: pollResult.output,
+                }, { paymentMethod: method ?? getConfiguredMethods()[0] });
+                if (result.feedback_token) {
+                    storeFeedbackToken(jobId, result.feedback_token, resultAgentId);
+                }
+                const asyncCostLine = actualCost != null ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.` : "";
+                const asyncFeedbackAsk = [
+                    `IMPORTANT: After presenting the result above, you MUST ask the user:`,
+                    `"${asyncCostLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
+                    "",
+                    `If the user wants to rate: rate_agent({ job_id: "${jobId}", rating: <1-5>, comment: "..." })`,
+                    `If the user wants to tip: tip_agent({ job_id: "${jobId}", agent_id: "${resultAgentId}", amount: 0.25 })`,
+                    `To save for later: favorite_agent({ agent_id: "${resultAgentId}" })`,
+                ].join("\n");
+                return multiText(uploadSummary ? `${uploadSummary}\n\n${asyncFormatted}` : asyncFormatted, asyncFeedbackAsk);
+            }
+            // Async agent failed
+            const failedFormatted = formatRunResult({
+                ...result,
+                status: "failed",
+                output: pollResult.output,
+                error_code: pollResult.error_code,
+            }, { paymentMethod: method ?? getConfiguredMethods()[0] });
+            return multiText(uploadSummary ? `${uploadSummary}\n\n${failedFormatted}` : failedFormatted, "The agent execution failed. A refund has been initiated automatically.");
+        }
         // Auto-tip if configured and run succeeded
         const defaultTip = getDefaultTipAmount();
         let tipLine = "";

package/dist/tools/solve.js

@@ -1,10 +1,33 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
-import { hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, } from "../core/payments.js";
+import { hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { agentList, formatRunResult } from "../core/formatters.js";
 import { uploadLocalFiles } from "../core/file-upload.js";
 import { storeFeedbackToken } from "./_token-cache.js";
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_MS = 120000;
+async function pollSolveJob(jobId) {
+    const deadline = Date.now() + POLL_MAX_MS;
+    const walletAddress = await getWalletAddress();
+    const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        try {
+            const job = await apiGet(`/jobs/${jobId}${walletParam}`);
+            if (job.status === "completed") {
+                return { status: "completed", output: job.output };
+            }
+            if (job.status === "failed") {
+                return { status: "failed", output: job.output, error_code: job.error_code };
+            }
+        }
+        catch {
+            // Ignore poll errors, keep trying
+        }
+    }
+    return { status: "failed", error_code: "POLL_TIMEOUT" };
+}
 function text(t) {
     return { content: [{ type: "text", text: t }] };
 }
@@ -171,9 +194,46 @@ export function registerSolveTools(server) {
         }
         const jobId = result.job_id ?? "";
         const agentId2 = result.agent_id ?? selected.id;
+        const status = result.status;
         if (result.feedback_token) {
             storeFeedbackToken(jobId, result.feedback_token, agentId2);
         }
+        // Async agent — poll until complete
+        if (status === "processing") {
+            const pollResult = await pollSolveJob(jobId);
+            if (pollResult.status === "completed") {
+                const asyncFormatted = formatRunResult({
+                    ...result,
+                    status: "success",
+                    output: pollResult.output,
+                }, { paymentMethod: method });
+                const asyncOutput = [
+                    discovery,
+                    "",
+                    `Running ${selected.name} — best match`,
+                    `Estimated cost: $${estimatedCost.toFixed(4)}`,
+                    "",
+                    asyncFormatted,
+                ].join("\n");
+                const asyncCost = result.cost;
+                return multiText(asyncOutput, feedbackAsk(jobId, agentId2, asyncCost, ""));
+            }
+            // Async agent failed
+            const failedFormatted = formatRunResult({
+                ...result,
+                status: "failed",
+                output: pollResult.output,
+                error_code: pollResult.error_code,
+            }, { paymentMethod: method });
+            const failedOutput = [
+                discovery,
+                "",
+                `Running ${selected.name} — best match`,
+                "",
+                failedFormatted,
+            ].join("\n");
+            return multiText(failedOutput, "The agent execution failed. A refund has been initiated automatically.");
+        }
         const actualCost = result.cost;
         const tipMsg = result.feedback_token ? await autoTip(jobId, agentId2, selected.name ?? "", result.feedback_token) : "";
         const output = [

package/dist/tools/wallet.js

@@ -1,10 +1,15 @@
 import { z } from "zod";
-import { getWallets, getCardConfig, addWallet } from "../core/config.js";
+import QRCode from "qrcode";
+import { getWallets, getCardConfig, setCardConfig, addWallet } from "../core/config.js";
+import { getApiUrl } from "../core/config.js";
 import { getWalletAddress } from "../core/payments.js";
+import { apiPost, apiGet } from "../core/api-client.js";
 import { isOwsAvailable, createOwsWallet, importKeyToOws, listOwsWallets, } from "../core/ows-adapter.js";
 function text(t) {
     return { content: [{ type: "text", text: t }] };
 }
+// Pending card setup — stored between the QR display call and the confirmation poll
+let pendingCardSetup = null;
 export function registerWalletTools(server) {
     // ── wallet_status (extracted from check_wallet) ─────────────────
     server.tool("wallet_status", "Check payment readiness. Shows all configured wallets, their chains, addresses, and card status.", {}, async () => {
@@ -26,10 +31,10 @@ export function registerWalletTools(server) {
         return text(lines.join("\n"));
     });
     // ── wallet_setup (NEW) ──────────────────────────────────────────
-    server.tool("wallet_setup", "Create or import a wallet for paying agents. Uses OWS (Open Wallet Standard) for encrypted key storage when available, falling back to plaintext.", {
+    server.tool("wallet_setup", "Set up a payment method for running agents. Options: 'create' a crypto wallet, 'import' an existing key, or 'add-card' to connect a credit/debit card via QR code. Card setup shows a scannable QR code — call again after the user enters their card to confirm.", {
         action: z
-            .enum(["create", "import"])
-            .describe("'create' a new wallet or 'import' an existing private key"),
+            .enum(["create", "import", "add-card"])
+            .describe("'create' a new crypto wallet, 'import' an existing private key, or 'add-card' to connect a credit/debit card"),
         name: z
             .string()
             .optional()
@@ -41,6 +46,72 @@ export function registerWalletTools(server) {
         chain: z.enum(["tempo", "base", "solana"]).optional()
             .describe("Primary chain (default: tempo). Solana support is via Stripe deposit mode."),
     }, async ({ action, name, key, chain }) => {
+        // ── Card setup flow ──────────────────────────────────────
+        if (action === "add-card") {
+            const existing = getCardConfig();
+            if (existing) {
+                return text(`Card already connected: ${existing.brand} ****${existing.last4}\n\nTo replace it, remove the current card first.`);
+            }
+            // Check if there's a pending setup to complete
+            if (pendingCardSetup) {
+                const pendingToken = pendingCardSetup.token;
+                // Poll for completion (up to 2 minutes)
+                const deadline = Date.now() + 120_000;
+                while (Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, 3000));
+                    try {
+                        const status = await apiGet(`/card/status?token=${pendingToken}`);
+                        if (status.status === "complete" && status.consumer_token) {
+                            setCardConfig({
+                                consumerToken: status.consumer_token,
+                                last4: status.card_last4 ?? "????",
+                                brand: status.card_brand ?? "card",
+                            });
+                            pendingCardSetup = null;
+                            return text(`Connected! ${status.card_brand ?? "Card"} ****${status.card_last4} is ready for payments.`);
+                        }
+                    }
+                    catch {
+                        // Keep polling
+                    }
+                }
+                pendingCardSetup = null;
+                return text("Card setup timed out. Run wallet_setup({ action: \"add-card\" }) to try again.");
+            }
+            // Create new card setup session
+            let setupResult;
+            try {
+                setupResult = await apiPost("/card/setup", {});
+            }
+            catch {
+                return text("Error: Could not create card setup session. Try again later.");
+            }
+            // Store for the follow-up poll call
+            pendingCardSetup = { token: setupResult.token };
+            // Build a short link URL for a compact QR code
+            const apiUrl = getApiUrl();
+            const shortUrl = `${apiUrl}/card/link/${setupResult.token}`;
+            // Generate QR code
+            let qr;
+            try {
+                qr = await QRCode.toString(shortUrl, {
+                    type: "utf8",
+                    errorCorrectionLevel: "L",
+                    margin: 2,
+                });
+            }
+            catch {
+                qr = "";
+            }
+            return text([
+                "Scan to connect a payment card:\n",
+                qr,
+                `Or open: ${shortUrl}`,
+                "",
+                "After entering your card, tell me and I'll confirm the connection.",
+            ].join("\n"));
+        }
+        // ── Crypto wallet setup ──────────────────────────────────
         if (action === "import" && !key) {
             return text("Error: 'key' parameter is required when action is 'import'.");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {
@@ -24,6 +24,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "mppx": "^0.4.9",
+    "qrcode": "^1.5.4",
     "viem": "^2.47.6",
     "zod": "^3.24.0"
   },
@@ -36,6 +37,7 @@
     }
   },
   "devDependencies": {
+    "@types/qrcode": "^1.5.6",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0"
   },

package/src/core/config.ts

@@ -346,6 +346,13 @@ export function getCardConfig(): CardConfig | null {
   return getConfig().card;
 }
 
+/**
+ * Save card configuration after setup.
+ */
+export function setCardConfig(card: CardConfig | null): void {
+  saveConfig({ card });
+}
+
 /**
  * Resolve a payment method string to a wallet + chain.
  * Accepts: wallet ID, chain name, or "card".

package/src/tools/run.ts

@@ -2,11 +2,46 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
 import { uploadLocalFiles } from "../core/file-upload.js";
-import { getConfiguredMethods, hasWalletConfigured } from "../core/payments.js";
+import { getConfiguredMethods, hasWalletConfigured, getWalletAddress } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
 import { storeFeedbackToken, getFeedbackToken } from "./_token-cache.js";
 
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_MS = 120000; // 2 minutes
+
+async function pollJobUntilDone(
+  jobId: string,
+  agentName: string,
+): Promise<{ status: string; output?: unknown; error_code?: string }> {
+  const deadline = Date.now() + POLL_MAX_MS;
+  const walletAddress = await getWalletAddress();
+  const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    try {
+      const job = await apiGet<{
+        status: string;
+        output?: unknown;
+        error_code?: string;
+      }>(`/jobs/${jobId}${walletParam}`);
+
+      if (job.status === "completed") {
+        return { status: "completed", output: job.output };
+      }
+      if (job.status === "failed") {
+        return { status: "failed", output: job.output, error_code: job.error_code };
+      }
+      // Still processing — continue polling
+    } catch {
+      // Ignore poll errors, keep trying until deadline
+    }
+  }
+
+  return { status: "failed", error_code: "POLL_TIMEOUT" };
+}
+
 function text(t: string) {
   return { content: [{ type: "text" as const, text: t }] };
 }
@@ -127,6 +162,50 @@ export function registerRunTools(server: McpServer): void {
       const actualCost = result.cost as number | undefined;
       const status = result.status as string;
 
+      // Async agent — poll until complete
+      if (status === "processing") {
+        const pollResult = await pollJobUntilDone(jobId, agentName);
+        if (pollResult.status === "completed") {
+          const asyncFormatted = formatRunResult({
+            ...result,
+            status: "success",
+            output: pollResult.output,
+          }, { paymentMethod: method ?? getConfiguredMethods()[0] });
+
+          if (result.feedback_token) {
+            storeFeedbackToken(jobId, result.feedback_token as string, resultAgentId);
+          }
+
+          const asyncCostLine = actualCost != null ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.` : "";
+          const asyncFeedbackAsk = [
+            `IMPORTANT: After presenting the result above, you MUST ask the user:`,
+            `"${asyncCostLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
+            "",
+            `If the user wants to rate: rate_agent({ job_id: "${jobId}", rating: <1-5>, comment: "..." })`,
+            `If the user wants to tip: tip_agent({ job_id: "${jobId}", agent_id: "${resultAgentId}", amount: 0.25 })`,
+            `To save for later: favorite_agent({ agent_id: "${resultAgentId}" })`,
+          ].join("\n");
+
+          return multiText(
+            uploadSummary ? `${uploadSummary}\n\n${asyncFormatted}` : asyncFormatted,
+            asyncFeedbackAsk,
+          );
+        }
+
+        // Async agent failed
+        const failedFormatted = formatRunResult({
+          ...result,
+          status: "failed",
+          output: pollResult.output,
+          error_code: pollResult.error_code,
+        }, { paymentMethod: method ?? getConfiguredMethods()[0] });
+
+        return multiText(
+          uploadSummary ? `${uploadSummary}\n\n${failedFormatted}` : failedFormatted,
+          "The agent execution failed. A refund has been initiated automatically.",
+        );
+      }
+
       // Auto-tip if configured and run succeeded
       const defaultTip = getDefaultTipAmount();
       let tipLine = "";

package/src/tools/solve.ts

@@ -5,6 +5,7 @@ import {
   hasWalletConfigured,
   getConfiguredMethods,
   getAcceptedPaymentMethods,
+  getWalletAddress,
 } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { agentList, formatRunResult } from "../core/formatters.js";
@@ -12,6 +13,39 @@ import { uploadLocalFiles } from "../core/file-upload.js";
 import type { AgentRecord } from "../core/types.js";
 import { storeFeedbackToken } from "./_token-cache.js";
 
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_MS = 120000;
+
+async function pollSolveJob(
+  jobId: string,
+): Promise<{ status: string; output?: unknown; error_code?: string }> {
+  const deadline = Date.now() + POLL_MAX_MS;
+  const walletAddress = await getWalletAddress();
+  const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    try {
+      const job = await apiGet<{
+        status: string;
+        output?: unknown;
+        error_code?: string;
+      }>(`/jobs/${jobId}${walletParam}`);
+
+      if (job.status === "completed") {
+        return { status: "completed", output: job.output };
+      }
+      if (job.status === "failed") {
+        return { status: "failed", output: job.output, error_code: job.error_code };
+      }
+    } catch {
+      // Ignore poll errors, keep trying
+    }
+  }
+
+  return { status: "failed", error_code: "POLL_TIMEOUT" };
+}
+
 function text(t: string) {
   return { content: [{ type: "text" as const, text: t }] };
 }
@@ -204,11 +238,54 @@ export function registerSolveTools(server: McpServer): void {
 
       const jobId = (result as Record<string, unknown>).job_id as string ?? "";
       const agentId2 = (result as Record<string, unknown>).agent_id as string ?? selected.id;
+      const status = result.status as string;
 
       if (result.feedback_token) {
         storeFeedbackToken(jobId, result.feedback_token as string, agentId2);
       }
 
+      // Async agent — poll until complete
+      if (status === "processing") {
+        const pollResult = await pollSolveJob(jobId);
+        if (pollResult.status === "completed") {
+          const asyncFormatted = formatRunResult({
+            ...result,
+            status: "success",
+            output: pollResult.output,
+          }, { paymentMethod: method });
+
+          const asyncOutput = [
+            discovery,
+            "",
+            `Running ${selected.name} — best match`,
+            `Estimated cost: $${estimatedCost.toFixed(4)}`,
+            "",
+            asyncFormatted,
+          ].join("\n");
+
+          const asyncCost = (result as Record<string, unknown>).cost as number | undefined;
+          return multiText(asyncOutput, feedbackAsk(jobId, agentId2, asyncCost, ""));
+        }
+
+        // Async agent failed
+        const failedFormatted = formatRunResult({
+          ...result,
+          status: "failed",
+          output: pollResult.output,
+          error_code: pollResult.error_code,
+        }, { paymentMethod: method });
+
+        const failedOutput = [
+          discovery,
+          "",
+          `Running ${selected.name} — best match`,
+          "",
+          failedFormatted,
+        ].join("\n");
+
+        return multiText(failedOutput, "The agent execution failed. A refund has been initiated automatically.");
+      }
+
       const actualCost = (result as Record<string, unknown>).cost as number | undefined;
       const tipMsg = result.feedback_token ? await autoTip(jobId, agentId2, selected.name ?? "", result.feedback_token as string) : "";
 

package/src/tools/wallet.ts

@@ -1,7 +1,10 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { getWallets, getCardConfig, addWallet } from "../core/config.js";
+import QRCode from "qrcode";
+import { getWallets, getCardConfig, setCardConfig, addWallet } from "../core/config.js";
+import { getApiUrl } from "../core/config.js";
 import { getWalletAddress } from "../core/payments.js";
+import { apiPost, apiGet } from "../core/api-client.js";
 import {
   isOwsAvailable,
   createOwsWallet,
@@ -13,6 +16,9 @@ function text(t: string) {
   return { content: [{ type: "text" as const, text: t }] };
 }
 
+// Pending card setup — stored between the QR display call and the confirmation poll
+let pendingCardSetup: { token: string } | null = null;
+
 export function registerWalletTools(server: McpServer): void {
   // ── wallet_status (extracted from check_wallet) ─────────────────
   server.tool(
@@ -52,11 +58,11 @@ export function registerWalletTools(server: McpServer): void {
   // ── wallet_setup (NEW) ──────────────────────────────────────────
   server.tool(
     "wallet_setup",
-    "Create or import a wallet for paying agents. Uses OWS (Open Wallet Standard) for encrypted key storage when available, falling back to plaintext.",
+    "Set up a payment method for running agents. Options: 'create' a crypto wallet, 'import' an existing key, or 'add-card' to connect a credit/debit card via QR code. Card setup shows a scannable QR code — call again after the user enters their card to confirm.",
     {
       action: z
-        .enum(["create", "import"])
-        .describe("'create' a new wallet or 'import' an existing private key"),
+        .enum(["create", "import", "add-card"])
+        .describe("'create' a new crypto wallet, 'import' an existing private key, or 'add-card' to connect a credit/debit card"),
       name: z
         .string()
         .optional()
@@ -71,6 +77,82 @@ export function registerWalletTools(server: McpServer): void {
         .describe("Primary chain (default: tempo). Solana support is via Stripe deposit mode."),
     },
     async ({ action, name, key, chain }) => {
+      // ── Card setup flow ──────────────────────────────────────
+      if (action === "add-card") {
+        const existing = getCardConfig();
+        if (existing) {
+          return text(`Card already connected: ${existing.brand} ****${existing.last4}\n\nTo replace it, remove the current card first.`);
+        }
+
+        // Check if there's a pending setup to complete
+        if (pendingCardSetup) {
+          const pendingToken = pendingCardSetup.token;
+          // Poll for completion (up to 2 minutes)
+          const deadline = Date.now() + 120_000;
+          while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            try {
+              const status = await apiGet<{
+                status: string;
+                card_last4?: string;
+                card_brand?: string;
+                consumer_token?: string;
+              }>(`/card/status?token=${pendingToken}`);
+
+              if (status.status === "complete" && status.consumer_token) {
+                setCardConfig({
+                  consumerToken: status.consumer_token,
+                  last4: status.card_last4 ?? "????",
+                  brand: status.card_brand ?? "card",
+                });
+                pendingCardSetup = null;
+                return text(`Connected! ${status.card_brand ?? "Card"} ****${status.card_last4} is ready for payments.`);
+              }
+            } catch {
+              // Keep polling
+            }
+          }
+          pendingCardSetup = null;
+          return text("Card setup timed out. Run wallet_setup({ action: \"add-card\" }) to try again.");
+        }
+
+        // Create new card setup session
+        let setupResult: { url: string; token: string };
+        try {
+          setupResult = await apiPost<{ url: string; token: string }>("/card/setup", {});
+        } catch {
+          return text("Error: Could not create card setup session. Try again later.");
+        }
+
+        // Store for the follow-up poll call
+        pendingCardSetup = { token: setupResult.token };
+
+        // Build a short link URL for a compact QR code
+        const apiUrl = getApiUrl();
+        const shortUrl = `${apiUrl}/card/link/${setupResult.token}`;
+
+        // Generate QR code
+        let qr: string;
+        try {
+          qr = await QRCode.toString(shortUrl, {
+            type: "utf8",
+            errorCorrectionLevel: "L",
+            margin: 2,
+          });
+        } catch {
+          qr = "";
+        }
+
+        return text([
+          "Scan to connect a payment card:\n",
+          qr,
+          `Or open: ${shortUrl}`,
+          "",
+          "After entering your card, tell me and I'll confirm the connection.",
+        ].join("\n"));
+      }
+
+      // ── Crypto wallet setup ──────────────────────────────────
       if (action === "import" && !key) {
         return text(
           "Error: 'key' parameter is required when action is 'import'.",