@agentwonderland/mcp 0.1.50 → 0.1.52

package/dist/tools/__tests__/wallet.test.js

@@ -5,6 +5,7 @@ const state = vi.hoisted(() => ({
     card: null,
     link: null,
     pendingLinkSetup: null,
+    linkCooldown: null,
     pendingCardSetupToken: null,
     spendPolicies: {},
     defaultPaymentMethod: undefined,
@@ -53,6 +54,7 @@ vi.mock("../../core/config.js", () => ({
     },
     getCardConfig: () => state.card,
     getLinkConfig: () => state.link,
+    getLinkCooldown: () => state.linkCooldown,
     getPendingLinkSetup: () => state.pendingLinkSetup,
     getPendingCardSetupToken: () => state.pendingCardSetupToken,
     getSpendPolicy: (walletId) => state.spendPolicies[walletId] ?? null,
@@ -122,6 +124,7 @@ vi.mock("../../core/ows-adapter.js", () => ({
 }));
 vi.mock("../../core/principal.js", () => ({
     ensureConsumerPrincipal: async () => state.consumerPrincipal,
+    ensureConsumerPrincipalForMethod: async () => state.consumerPrincipal,
     getConsumerPrincipal: async () => state.consumerPrincipal,
 }));
 function resetState() {
@@ -130,6 +133,7 @@ function resetState() {
     state.card = null;
     state.link = null;
     state.pendingLinkSetup = null;
+    state.linkCooldown = null;
     state.pendingCardSetupToken = null;
     state.spendPolicies = {};
     state.defaultPaymentMethod = undefined;

package/dist/tools/index.d.ts

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/dist/tools/index.js

@@ -8,6 +8,7 @@ export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
 export { registerPassTools } from "./passes.js";
+export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";

package/dist/tools/observability.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerObservabilityTools(server: McpServer): void;

package/dist/tools/observability.js

@@ -0,0 +1,20 @@
+import { apiPost } from "../core/api-client.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+export function registerObservabilityTools(server) {
+    server.tool("open_observability_dashboard", "Generate a secure one-click sign-in URL for the Agent Wonderland web observability dashboard. The dashboard shows your agent runs, spend, rebates, and recent activity.", {}, async () => {
+        const result = await apiPost("/observability/link", {}, { ensureConsumerPrincipal: true });
+        const lines = [
+            "Your secure observability link is ready:",
+            result.url,
+            "",
+            `Expires: ${result.expires_at}`,
+        ];
+        if (result.consumer_principal) {
+            lines.push(`Consumer principal: ${result.consumer_principal}`);
+        }
+        lines.push("", "Open the link in your browser to view usage metrics, spend, rebates, and recent runs.");
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/rebates.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRebateTools(server: McpServer): void;

package/dist/tools/rebates.js

@@ -0,0 +1,51 @@
+import { apiGet } from "../core/api-client.js";
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+function money(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? `$${numeric.toFixed(4)}` : `$${value}`;
+}
+function sourceLabel(value) {
+    return value.replace(/_/g, " ");
+}
+export function registerRebateTools(server) {
+    server.tool("rebate_status", "Show your Agent Wonderland consumer rebate balance, payout threshold, blocked rebates, and recent payout transactions.", {}, async () => {
+        const status = await apiGet("/rebates/status", { ensureConsumerPrincipal: true });
+        const threshold = Number(status.auto_payout_threshold_usd);
+        const pending = Number(status.totals.pending_usd);
+        const remaining = Math.max(0, threshold - pending);
+        const lines = [
+            "Rebate status",
+            `Consumer principal: ${status.consumer_principal}`,
+            `Base payout address: ${status.payout_address ?? "not configured"}`,
+            "",
+            `Lifetime earned: ${money(status.totals.lifetime_earned_usd)} across ${status.totals.total_count} rebate(s)`,
+            `Paid out: ${money(status.totals.paid_usd)} across ${status.totals.paid_count} rebate(s)`,
+            `Pending: ${money(status.totals.pending_usd)} across ${status.totals.pending_count} rebate(s)`,
+            `Blocked: ${money(status.totals.blocked_usd)} across ${status.totals.blocked_count} rebate(s)`,
+        ];
+        if (Number.isFinite(threshold) && threshold > 0) {
+            lines.push(pending >= threshold
+                ? `Auto payout: eligible for the next processor run (threshold ${money(threshold)})`
+                : `Auto payout: ${money(remaining)} until the ${money(threshold)} threshold`);
+        }
+        if (status.by_source.length > 0) {
+            lines.push("", "By source:");
+            for (const row of status.by_source) {
+                lines.push(`  ${sourceLabel(row.source_type)} / ${row.status}: ${money(row.rebate_usd)} (${row.count})`);
+            }
+        }
+        if (status.recent_payouts.length > 0) {
+            lines.push("", "Recent payouts:");
+            for (const payout of status.recent_payouts.slice(0, 5)) {
+                const tx = payout.tx_hash ? ` tx=${payout.tx_hash}` : "";
+                lines.push(`  ${payout.status}: ${money(payout.amount_usd)} (${payout.earning_count})${tx}`);
+            }
+        }
+        if (!status.payout_address) {
+            lines.push("", "No Base payout address is configured, so new rebates may be blocked.");
+        }
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/wallet.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
-import { getWallets, getCardConfig, getLinkConfig, getPendingLinkSetup, setPendingLinkSetup, setLinkConfig, setCardConfig, addWallet, getPendingCardSetupToken, getSpendPolicy, setDefaultPaymentMethod, setSpendPolicy, } from "../core/config.js";
+import { getWallets, getCardConfig, getLinkConfig, getLinkCooldown, getPendingLinkSetup, setPendingLinkSetup, setLinkConfig, setCardConfig, addWallet, getPendingCardSetupToken, getSpendPolicy, setDefaultPaymentMethod, setSpendPolicy, } from "../core/config.js";
 import { getWalletAddress, isCardPaymentEnabled } from "../core/payments.js";
 import { fetchUsdcBalance } from "../core/balances.js";
 import { getSettings } from "../core/settings.js";
 import { getOrCreatePendingCardSetup, formatCardSetupBlocks, getCardCapabilities, pollCardSetup, } from "../core/card-setup.js";
 import { getLinkCliAuthStatus, listLinkPaymentMethods, openLinkPaymentMethodAdd, startLinkCliLogin, } from "../core/link-cli.js";
 import { isOwsAvailable, createOwsWallet, importKeyToOws, listOwsWallets, listOwsWalletsByChain, installOws, platformSupportsOws, } from "../core/ows-adapter.js";
-import { ensureConsumerPrincipal, getConsumerPrincipal } from "../core/principal.js";
+import { ensureConsumerPrincipal, ensureConsumerPrincipalForMethod, getConsumerPrincipal } from "../core/principal.js";
 import { MCP_PACKAGE_VERSION } from "../core/version.js";
 function text(t) {
     return { content: [{ type: "text", text: t }] };
@@ -110,6 +110,12 @@ export function registerWalletTools(server) {
             lines.push(auth.authenticated
                 ? "  Link CLI: authenticated"
                 : "  Link CLI: not authenticated — run npx @stripe/link-cli auth login");
+            const cooldown = getLinkCooldown();
+            const blockedUntil = cooldown ? Date.parse(cooldown.blockedUntil) : NaN;
+            if (cooldown && Number.isFinite(blockedUntil) && blockedUntil > Date.now()) {
+                lines.push(`  Link status: temporarily blocked by Stripe projected-spend cap until ${cooldown.blockedUntil}`);
+                lines.push("  Link note: reauthing or switching cards in the same Link account will not clear this cap.");
+            }
         }
         if (pendingCardSetupToken) {
             lines.push("  Card setup: pending confirmation");
@@ -215,7 +221,7 @@ export function registerWalletTools(server) {
                     paymentMethodId: selected.id,
                     label: name ?? selected.label,
                 });
-                const principal = await ensureConsumerPrincipal();
+                const principal = await ensureConsumerPrincipalForMethod("link");
                 return text([
                     "Link payment method connected.",
                     `  Payment method: ${selected.label ?? selected.id}${selected.label ? ` (${selected.id})` : ""}`,
@@ -248,7 +254,7 @@ export function registerWalletTools(server) {
                     paymentMethodId: method.id,
                     label: method.label,
                 });
-                const principal = await ensureConsumerPrincipal();
+                const principal = await ensureConsumerPrincipalForMethod("link");
                 return text([
                     "Link payment method connected.",
                     `  Payment method: ${method.id}${method.label ? ` (${method.label})` : ""}`,
@@ -287,7 +293,7 @@ export function registerWalletTools(server) {
             if (pendingToken) {
                 const result = await pollCardSetup(pendingToken, 250);
                 if (result) {
-                    const principal = await ensureConsumerPrincipal();
+                    const principal = await ensureConsumerPrincipalForMethod("card");
                     return text(`Connected! ${result.brand} ****${result.last4} is ready for payments.\n\n` +
                         `Consumer principal: ${principal}`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwonderland/mcp",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "type": "module",
   "description": "MCP server for the Agent Wonderland AI agent marketplace",
   "bin": {

package/src/core/__tests__/api-client.test.ts

@@ -1,10 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MCP_PACKAGE_VERSION } from "../version.js";
 
 const {
   mockGetApiUrl,
   mockGetApiKey,
   mockGetPaymentFetch,
   mockEnsureConsumerPrincipalForMethod,
+  mockEnsureBaseRebatePrincipal,
   mockGetConsumerPrincipalForMethod,
   mockGetBaseRebatePrincipal,
   mockPaymentFetch,
@@ -13,6 +15,7 @@ const {
   mockGetApiKey: vi.fn(),
   mockGetPaymentFetch: vi.fn(),
   mockEnsureConsumerPrincipalForMethod: vi.fn(),
+  mockEnsureBaseRebatePrincipal: vi.fn(),
   mockGetConsumerPrincipalForMethod: vi.fn(),
   mockGetBaseRebatePrincipal: vi.fn(),
   mockPaymentFetch: vi.fn(),
@@ -29,6 +32,7 @@ vi.mock("../payments.js", () => ({
 
 vi.mock("../principal.js", () => ({
   ensureConsumerPrincipal: vi.fn(),
+  ensureBaseRebatePrincipal: (...args: unknown[]) => mockEnsureBaseRebatePrincipal(...args),
   ensureConsumerPrincipalForMethod: (...args: unknown[]) => mockEnsureConsumerPrincipalForMethod(...args),
   getConsumerPrincipal: vi.fn(),
   getConsumerPrincipalForMethod: (...args: unknown[]) => mockGetConsumerPrincipalForMethod(...args),
@@ -50,6 +54,9 @@ describe("api-client headers", () => {
     mockGetBaseRebatePrincipal.mockResolvedValue(
       "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
     );
+    mockEnsureBaseRebatePrincipal.mockResolvedValue(
+      "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    );
     mockPaymentFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), {
       status: 200,
       headers: { "content-type": "application/json" },
@@ -72,7 +79,7 @@ describe("api-client headers", () => {
           "X-AW-Rebate-Principal":
             "did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
           "X-AW-Surface": "mcp",
-          "X-AW-MCP-Version": "0.1.44",
+          "X-AW-MCP-Version": MCP_PACKAGE_VERSION,
           "X-AW-MCP-Tool": "run_agent",
           "X-AW-MCP-Action": "execute",
         }),

package/src/core/__tests__/payments.test.ts

@@ -26,6 +26,7 @@ vi.mock("../config.js", () => ({
   getApiUrl: () => "http://api.test",
   getCardConfig: () => currentCard,
   getLinkConfig: () => currentLink,
+  getLinkCooldown: () => null,
   getConfig: () => ({ defaultPaymentMethod: currentDefaultPaymentMethod }),
   getDefaultWallet: () => currentDefaultWallet,
   getWallets: () => currentWallets,
@@ -166,17 +167,50 @@ describe("payment method initialization", () => {
 
     expect(mockCreateLinkSharedPaymentToken).toHaveBeenCalledWith(
       expect.objectContaining({
-        amount: "2000",
+        amount: "25",
         currency: "usd",
         networkId: "profile_test",
         paymentMethodId: "csmrpd_link_123",
       }),
     );
     const linkTokenRequest = mockCreateLinkSharedPaymentToken.mock.calls[0]?.[0] as { context: string } | undefined;
-    expect(linkTokenRequest?.context).toContain("up to USD 20.00");
+    expect(linkTokenRequest?.context).toContain("up to USD 0.25");
     expect(linkTokenRequest?.context).toContain("quoted at USD 0.25");
   });
 
+  it("uses an explicit Link approval override when configured", async () => {
+    process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS = "2000";
+    currentLink = {
+      paymentMethodId: "csmrpd_link_123",
+      label: "Visa ****4242",
+    };
+    currentDefaultPaymentMethod = "link";
+
+    const { getPaymentFetch } = await import("../payments.js");
+    await getPaymentFetch("link");
+
+    const stripeConfig = mockStripe.mock.calls[0]?.[0] as {
+      createToken: (params: {
+        amount: string;
+        currency: string;
+        expiresAt: number;
+        networkId: string;
+      }) => Promise<string>;
+    };
+    await stripeConfig.createToken({
+      amount: "25",
+      currency: "usd",
+      expiresAt: 1778290000,
+      networkId: "profile_test",
+    });
+
+    expect(mockCreateLinkSharedPaymentToken).toHaveBeenCalledWith(
+      expect.objectContaining({
+        amount: "2000",
+      }),
+    );
+  });
+
   it("allows a low env override while never approving below the quoted amount", async () => {
     process.env.AGENTWONDERLAND_LINK_APPROVAL_LIMIT_CENTS = "10";
     currentLink = {

package/src/core/__tests__/principal.test.ts

@@ -137,6 +137,22 @@ describe("consumer principal helpers", () => {
     expect(state.addedWallets).toHaveLength(1);
   });
 
+  it("creates an EVM identity for Link payments when only a Solana wallet exists", async () => {
+    state.wallets = [
+      { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+    ];
+    state.addresses = {
+      "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    };
+
+    const { ensureConsumerPrincipalForMethod } = await import("../principal.js");
+    const principal = await ensureConsumerPrincipalForMethod("link");
+
+    expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+    expect(state.addedWallets).toHaveLength(1);
+    expect(state.addedWallets[0]?.chains).toEqual(["tempo", "base"]);
+  });
+
   it("returns the Base rebate principal when an EVM wallet is available", async () => {
     state.wallets = [
       { id: "aw-main", keyType: "ows", owsWalletId: "ows-main", chains: ["tempo", "base", "solana"], defaultChain: "tempo" },
@@ -152,4 +168,19 @@ describe("consumer principal helpers", () => {
 
     expect(principal).toBe("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
   });
+
+  it("ensures a Base rebate principal even when the default wallet is Solana-only", async () => {
+    state.wallets = [
+      { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+    ];
+    state.addresses = {
+      "sol-wallet": "42W2HfLfveSm1T5et9WTLp2CZ2QXdF2EYCUvyJ2gPpxF",
+    };
+
+    const { ensureBaseRebatePrincipal } = await import("../principal.js");
+    const principal = await ensureBaseRebatePrincipal();
+
+    expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+    expect(state.addedWallets).toHaveLength(1);
+  });
 });

package/src/core/api-client.ts

@@ -2,7 +2,7 @@ import { getApiUrl, getApiKey } from "./config.js";
 import { getPaymentFetch } from "./payments.js";
 import {
   getBaseRebatePrincipal,
-  ensureConsumerPrincipal,
+  ensureBaseRebatePrincipal,
   ensureConsumerPrincipalForMethod,
   getConsumerPrincipal,
   getConsumerPrincipalForMethod,
@@ -70,7 +70,9 @@ async function buildHeaders(path: string, method: string, options?: RequestOptio
     headers["X-AW-Consumer-Principal"] = principal;
   }
 
-  const rebatePrincipal = await getBaseRebatePrincipal();
+  const rebatePrincipal = options?.ensureConsumerPrincipal
+    ? await ensureBaseRebatePrincipal()
+    : await getBaseRebatePrincipal();
   if (rebatePrincipal) {
     headers["X-AW-Rebate-Principal"] = rebatePrincipal;
   }

package/src/core/config.ts

@@ -32,6 +32,24 @@ export interface PendingLinkSetup {
   createdAt: string;
 }
 
+export interface PendingLinkSpendRequest {
+  id: string;
+  approvalUrl?: string;
+  amount: string;
+  currency: string;
+  context: string;
+  expiresAt: number;
+  networkId: string;
+  paymentMethodId: string;
+  createdAt: string;
+}
+
+export interface LinkCooldown {
+  reason: string;
+  createdAt: string;
+  blockedUntil: string;
+}
+
 export interface SpendPolicy {
   maxPerTxUsd?: number;
   maxPerDayUsd?: number;
@@ -55,6 +73,8 @@ export interface Config {
   card: CardConfig | null;
   link: LinkConfig | null;
   pendingLinkSetup?: PendingLinkSetup | null;
+  pendingLinkSpendRequest?: PendingLinkSpendRequest | null;
+  linkCooldown?: LinkCooldown | null;
   pendingCardSetupToken?: string | null;
   favorites: string[];
   /** Require user confirmation before spending. Default: true. Set false for headless/automated use. */
@@ -113,6 +133,8 @@ interface LegacyConfig {
   card?: CardConfig | null;
   link?: LinkConfig | null;
   pendingLinkSetup?: PendingLinkSetup | null;
+  pendingLinkSpendRequest?: PendingLinkSpendRequest | null;
+  linkCooldown?: LinkCooldown | null;
   pendingCardSetupToken?: string | null;
   spendPolicies?: Record<string, SpendPolicy>;
   spendLedger?: SpendLedgerEntry[];
@@ -136,6 +158,8 @@ function migrateIfNeeded(raw: LegacyConfig): Config {
       card: raw.card ?? null,
       link: raw.link ?? null,
       pendingLinkSetup: raw.link ? null : (raw.pendingLinkSetup ?? null),
+      pendingLinkSpendRequest: raw.pendingLinkSpendRequest ?? null,
+      linkCooldown: raw.linkCooldown ?? null,
       pendingCardSetupToken: (r.pendingCardSetupToken as string | null | undefined) ?? null,
       favorites: r.favorites as string[] ?? [],
       confirmBeforeSpend: r.confirmBeforeSpend !== false,
@@ -214,6 +238,8 @@ function migrateIfNeeded(raw: LegacyConfig): Config {
     card,
     link: raw.link ?? null,
     pendingLinkSetup: raw.link ? null : (raw.pendingLinkSetup ?? null),
+    pendingLinkSpendRequest: raw.pendingLinkSpendRequest ?? null,
+    linkCooldown: raw.linkCooldown ?? null,
     pendingCardSetupToken: null,
     favorites: [],
     confirmBeforeSpend: true,
@@ -243,6 +269,8 @@ export function getConfig(): Config {
     card: null,
     link: null,
     pendingLinkSetup: null,
+    pendingLinkSpendRequest: null,
+    linkCooldown: null,
     pendingCardSetupToken: null,
     favorites: [],
     confirmBeforeSpend: true,
@@ -432,6 +460,22 @@ export function getPendingLinkSetup(): PendingLinkSetup | null {
   return getConfig().pendingLinkSetup ?? null;
 }
 
+export function getPendingLinkSpendRequest(): PendingLinkSpendRequest | null {
+  return getConfig().pendingLinkSpendRequest ?? null;
+}
+
+export function setPendingLinkSpendRequest(pendingLinkSpendRequest: PendingLinkSpendRequest | null): void {
+  saveConfig({ pendingLinkSpendRequest });
+}
+
+export function getLinkCooldown(): LinkCooldown | null {
+  return getConfig().linkCooldown ?? null;
+}
+
+export function setLinkCooldown(linkCooldown: LinkCooldown | null): void {
+  saveConfig({ linkCooldown });
+}
+
 /**
  * Save card configuration after setup.
  */
@@ -461,11 +505,13 @@ export function setLinkConfig(link: LinkConfig | null): void {
       link,
       defaultPaymentMethod: "link",
       pendingLinkSetup: null,
+      pendingLinkSpendRequest: null,
     });
   } else {
     saveConfig({
       link,
       pendingLinkSetup: null,
+      pendingLinkSpendRequest: null,
       defaultPaymentMethod: current.defaultPaymentMethod === "link"
         ? undefined
         : current.defaultPaymentMethod,

package/src/core/link-cli.ts

@@ -1,5 +1,11 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import {
+  getPendingLinkSpendRequest,
+  setLinkCooldown,
+  setPendingLinkSpendRequest,
+  type PendingLinkSpendRequest,
+} from "./config.js";
 
 const execFileAsync = promisify(execFile);
 const LINK_CLI_PACKAGE = "@stripe/link-cli";
@@ -116,6 +122,40 @@ function extractSpendRequestApproval(output: unknown): { id: string; approvalUrl
   return null;
 }
 
+function isMatchingPendingSpendRequest(
+  pending: PendingLinkSpendRequest | null,
+  params: {
+    amount: string;
+    currency: string;
+    context: string;
+    expiresAt: number;
+    networkId: string;
+    paymentMethodId: string;
+  },
+): pending is PendingLinkSpendRequest {
+  if (!pending) return false;
+  if (pending.amount !== params.amount) return false;
+  if (pending.currency.toLowerCase() !== params.currency.toLowerCase()) return false;
+  if (pending.context !== params.context) return false;
+  if (pending.networkId !== params.networkId) return false;
+  if (pending.paymentMethodId !== params.paymentMethodId) return false;
+  if (pending.expiresAt <= Math.floor(Date.now() / 1000)) return false;
+  return true;
+}
+
+function isProjectedSpendCapError(message: string): boolean {
+  return /projected daily spend|projected spend|exceeds limit/i.test(message);
+}
+
+function recordLinkCooldown(reason: string): void {
+  const now = new Date();
+  setLinkCooldown({
+    reason,
+    createdAt: now.toISOString(),
+    blockedUntil: new Date(now.getTime() + 24 * 60 * 60 * 1000).toISOString(),
+  });
+}
+
 function normalizePaymentMethods(output: unknown): LinkCliPaymentMethod[] {
   const values = Array.isArray(output)
     ? output
@@ -215,6 +255,22 @@ export async function createLinkSharedPaymentToken(params: {
   networkId: string;
   paymentMethodId: string;
 }): Promise<string> {
+  const existing = getPendingLinkSpendRequest();
+  if (isMatchingPendingSpendRequest(existing, params)) {
+    try {
+      console.error(`Resuming pending Link approval: ${existing.id}`);
+      const spt = await retrieveSharedPaymentToken(existing.id, existing.approvalUrl);
+      setPendingLinkSpendRequest(null);
+      return spt;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!/denied|expired|not found|without a shared payment token|POLLING_TIMEOUT/i.test(message)) {
+        throw err;
+      }
+      setPendingLinkSpendRequest(null);
+    }
+  }
+
   const args = [
     "spend-request",
     "create",
@@ -242,6 +298,18 @@ export async function createLinkSharedPaymentToken(params: {
     output = await runLinkCli(args);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
+    if (isProjectedSpendCapError(message)) {
+      recordLinkCooldown(message);
+      throw new Error(
+        [
+          "Link is temporarily blocked by Stripe's projected-spend cap.",
+          "Reauthing Link or switching cards in the same Link account will not fix this.",
+          "Use USDC for now, wait for the rolling Link window to clear, or ask Stripe to raise/clear the merchant projected-spend cap.",
+          "",
+          message,
+        ].join("\n"),
+      );
+    }
     if (/invalid network_id|could not retrieve merchant information/i.test(message)) {
       throw new Error(
         [
@@ -256,45 +324,63 @@ export async function createLinkSharedPaymentToken(params: {
   }
   const spt = extractSharedPaymentToken(output);
   if (spt) {
+    setPendingLinkSpendRequest(null);
     return spt;
   }
 
   const approval = extractSpendRequestApproval(output);
   if (approval?.id && approval.status === "pending_approval") {
+    setPendingLinkSpendRequest({
+      id: approval.id,
+      approvalUrl: approval.approvalUrl,
+      amount: params.amount,
+      currency: params.currency,
+      context: params.context,
+      expiresAt: params.expiresAt,
+      networkId: params.networkId,
+      paymentMethodId: params.paymentMethodId,
+      createdAt: new Date().toISOString(),
+    });
     if (approval.approvalUrl) {
       console.error(`Link approval required: ${approval.approvalUrl}`);
     }
-    let retrieved = await runLinkCli([
-      "spend-request",
-      "retrieve",
-      approval.id,
-      "--interval",
-      "2",
-      "--max-attempts",
-      "150",
-    ]);
-    let retrievedSpt = extractSharedPaymentToken(retrieved);
-    for (let attempt = 0; !retrievedSpt && attempt < 30; attempt += 1) {
-      await sleep(2_000);
-      retrieved = await runLinkCli([
-        "spend-request",
-        "retrieve",
-        approval.id,
-      ]);
-      retrievedSpt = extractSharedPaymentToken(retrieved);
-    }
-    if (retrievedSpt) {
-      return retrievedSpt;
-    }
-    throw new Error(
-      [
-        "Link spend request finished without a shared payment token.",
-        approval.approvalUrl ? `Approval URL: ${approval.approvalUrl}` : undefined,
-      ].filter(Boolean).join("\n"),
-    );
+    const retrievedSpt = await retrieveSharedPaymentToken(approval.id, approval.approvalUrl);
+    setPendingLinkSpendRequest(null);
+    return retrievedSpt;
   }
 
   {
     throw new Error("Link spend request completed without a shared payment token in the CLI response.");
   }
 }
+
+async function retrieveSharedPaymentToken(spendRequestId: string, approvalUrl?: string): Promise<string> {
+  let retrieved = await runLinkCli([
+    "spend-request",
+    "retrieve",
+    spendRequestId,
+    "--interval",
+    "2",
+    "--max-attempts",
+    "150",
+  ]);
+  let retrievedSpt = extractSharedPaymentToken(retrieved);
+  for (let attempt = 0; !retrievedSpt && attempt < 30; attempt += 1) {
+    await sleep(2_000);
+    retrieved = await runLinkCli([
+      "spend-request",
+      "retrieve",
+      spendRequestId,
+    ]);
+    retrievedSpt = extractSharedPaymentToken(retrieved);
+  }
+  if (retrievedSpt) {
+    return retrievedSpt;
+  }
+  throw new Error(
+    [
+      "Link spend request finished without a shared payment token.",
+      approvalUrl ? `Approval URL: ${approvalUrl}` : undefined,
+    ].filter(Boolean).join("\n"),
+  );
+}