@agentwonderland/mcp 0.1.52 → 0.1.54

package/dist/tools/run.js

@@ -2,12 +2,11 @@ import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
 import { uploadLocalFiles } from "../core/file-upload.js";
 import { formatCreditPackOffer, getActiveCreditPack, getCreditPackInventory, getCreditPackProgram, } from "../core/passes.js";
-import { getCompatiblePaymentMethods, getConfiguredMethods, hasWalletConfigured, getWalletAddress, normalizePaymentMethod, isCardPaymentEnabled, } from "../core/payments.js";
+import { getCompatiblePaymentMethods, getConfiguredMethods, hasWalletConfigured, getWalletAddress, normalizePaymentMethod, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
 import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend-policy.js";
 import { storeFeedbackToken } from "./_token-cache.js";
-import { getOrCreatePendingCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
 import { formatPaymentLabel, formatRunConfirmationCommand, resolveConfirmationMethod, } from "./_payment-confirmation.js";
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 300000;
@@ -88,30 +87,17 @@ export function registerRunTools(server) {
     server.tool("run_agent", "Run an AI agent from the marketplace. Pays automatically via configured wallet. Returns the agent's output, cost, and job ID for tracking. If spending confirmation is enabled, first call returns a price quote — call again with confirmed: true to execute. Local file paths in the input (e.g. /Users/.../photo.jpg) are automatically uploaded to temporary storage and replaced with download URLs before execution. If a file you need isn't on this MCP server's filesystem (e.g. a sandboxed /mnt/... attachment), call upload_file first to get a presigned upload URL, PUT the bytes to it, then pass the returned GET URL as input instead — that keeps the bytes out of the conversation context.", {
         agent_id: z.string().describe("Agent ID (UUID, slug, or name)"),
         input: z.record(z.string(), z.unknown()).describe("Input payload for the agent"),
-        pay_with: z.string().trim().min(1).optional().describe("Payment method — wallet ID, chain name (tempo, base, solana), 'link', or 'card'. Auto-detected if omitted."),
+        pay_with: z.string().trim().min(1).optional().describe("Launch payment method — wallet ID or chain name (tempo, base, solana). Auto-detected if omitted."),
         confirmed: z.boolean().optional().describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ agent_id, input, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
-            if (isCardPaymentEnabled()) {
-                try {
-                    const { url } = await getOrCreatePendingCardSetup();
-                    return multiText(...formatCardSetupBlocks(url));
-                }
-                catch {
-                    // Fall through to the setup message below.
-                }
-            }
             const setupLines = [
                 "No payment method configured.",
                 "",
-                "Recommended: wallet_setup({ action: \"add-link\" }) to connect a Link card or bank account.",
-                "You can also run wallet_setup({ action: \"start\" }) to see all payment options.",
+                "Run wallet_setup({ action: \"start\" }) to configure a launch USDC payment method.",
                 "",
-                "USDC options: Tempo, Base, or Solana.",
+                "Launch options: Tempo USDC, Base USDC, or Solana USDC.",
             ];
-            if (isCardPaymentEnabled()) {
-                setupLines.push("", "Or wallet_setup({ action: \"add-card\" }) to connect a credit card.");
-            }
             return text(setupLines.join("\n"));
         }
         let agent;
@@ -166,6 +152,9 @@ export function registerRunTools(server) {
                 `  Cost: $${price.toFixed(2)}`,
                 `  Payment: ${formatPaymentLabel(method)}`,
             ];
+            if (method === "link") {
+                quoteLines.push("  Link: after confirming here, approve the Link spend request and rerun the confirmed call.");
+            }
             const creditPackLines = buildCreditPackOfferLines(agent);
             if (creditPackLines.length > 0) {
                 quoteLines.push("", ...creditPackLines);
@@ -226,6 +215,9 @@ export function registerRunTools(server) {
                 ].join("\n"));
             }
             const msg = apiErr?.message ?? "Failed to run agent";
+            if (msg.includes("Link approval required.")) {
+                return text(msg);
+            }
             if (msg.includes("Missing required field") || msg.includes("validation failed")) {
                 return text(`Error: ${msg}\n\nUse get_agent("${agent_id}") to see the required input fields.`);
             }

package/dist/tools/solve.js

@@ -1,7 +1,6 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
-import { getOrCreatePendingCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
-import { getCompatiblePaymentMethods, hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, normalizePaymentMethod, toRegistryPaymentMethod, isCardPaymentEnabled, } from "../core/payments.js";
+import { getCompatiblePaymentMethods, hasWalletConfigured, getConfiguredMethods, getAcceptedPaymentMethods, getWalletAddress, normalizePaymentMethod, toRegistryPaymentMethod, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { agentList, formatRunResult } from "../core/formatters.js";
 import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend-policy.js";
@@ -126,33 +125,20 @@ export function registerSolveTools(server) {
             .trim()
             .min(1)
             .optional()
-            .describe("Payment method — wallet ID, chain name (tempo, base, solana), 'link', or 'card'. Auto-detected if omitted."),
+            .describe("Launch payment method — wallet ID or chain name (tempo, base, solana). Auto-detected if omitted."),
         confirmed: z
             .boolean()
             .optional()
             .describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ intent, input, budget, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
-            if (isCardPaymentEnabled()) {
-                try {
-                    const { url } = await getOrCreatePendingCardSetup();
-                    return multiText(...formatCardSetupBlocks(url));
-                }
-                catch {
-                    // Fall through to the setup message below.
-                }
-            }
             const setupLines = [
                 "No payment method configured.",
                 "",
-                "Recommended: wallet_setup({ action: \"add-link\" }) to connect a Link card or bank account.",
-                "You can also run wallet_setup({ action: \"start\" }) to see all payment options.",
+                "Run wallet_setup({ action: \"start\" }) to configure a launch USDC payment method.",
                 "",
-                "USDC options: Tempo, Base, or Solana.",
+                "Launch options: Tempo USDC, Base USDC, or Solana USDC.",
             ];
-            if (isCardPaymentEnabled()) {
-                setupLines.push("", "Or wallet_setup({ action: \"add-card\" }) to connect a credit card.");
-            }
             return text(setupLines.join("\n"));
         }
         const pendingKey = makeSolvePendingKey(intent, input, budget);
@@ -241,6 +227,9 @@ export function registerSolveTools(server) {
                 `Best match: ${selected.name}`,
                 `Cost: $${estimatedCost.toFixed(2)}`,
                 `Payment: ${formatPaymentLabel(method)}`,
+                ...(method === "link"
+                    ? ["Link: after confirming here, approve the Link spend request and rerun the confirmed call."]
+                    : []),
                 ...(() => {
                     const summary = buildCreditPackSummary(selected);
                     return summary.length > 0 ? ["", ...summary] : [];
@@ -298,7 +287,11 @@ export function registerSolveTools(server) {
                     })(),
                 ].join("\n"));
             }
-            return text(`Error: ${apiErr?.message ?? "Failed to run agent"}`);
+            const msg = apiErr?.message ?? "Failed to run agent";
+            if (msg.includes("Link approval required.")) {
+                return text(msg);
+            }
+            return text(`Error: ${msg}`);
         }
         pendingSolves.delete(pendingKey);
         const jobId = result.job_id ?? "";

package/dist/tools/wallet.js

@@ -30,21 +30,18 @@ function isFreshLinkSetup(pending) {
 }
 function formatPaymentSetupMenu() {
     return [
-        "Choose a payment method to set up:",
+        "Choose a launch payment method to set up:",
         "",
-        "1. Link card or bank account (recommended)",
-        "   wallet_setup({ action: \"add-link\" })",
-        "",
-        "2. Tempo USDC",
+        "1. Tempo USDC",
         "   wallet_setup({ action: \"create\", chain: \"tempo\" })",
         "",
-        "3. Base USDC",
+        "2. Base USDC",
         "   wallet_setup({ action: \"create\", chain: \"base\" })",
         "",
-        "4. Solana USDC",
+        "3. Solana USDC",
         "   wallet_setup({ action: \"create\", chain: \"solana\" })",
         "",
-        "5. Import an existing wallet",
+        "4. Import an existing wallet",
         "   wallet_setup({ action: \"import\", chain: \"base\", key: \"<private key>\" })",
     ].join("\n");
 }
@@ -53,7 +50,7 @@ function setDefaultCryptoPaymentMethod(chain) {
 }
 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 () => {
+    server.tool("wallet_status", "Check launch payment readiness. Shows configured wallets, chains, addresses, and USDC balances.", {}, async () => {
         const wallets = getWallets();
         const card = getCardConfig();
         const link = getLinkConfig();
@@ -133,10 +130,10 @@ export function registerWalletTools(server) {
         return text(lines.join("\n"));
     });
     // ── wallet_setup ────────────────────────────────────────────────
-    server.tool("wallet_setup", "Set up or manage an Agent Wonderland payment method. Use 'start' for a guided setup menu. Link card/bank is recommended for most users. 'add-link' connects a Link card or bank account for agent payments. 'create' makes a new crypto wallet (encrypted via OWS if available, otherwise plaintext — run 'enable-ows' to upgrade). 'import' takes an existing private key. 'enable-ows' installs the Open Wallet Standard native module for encrypted at-rest storage. Tempo/Base share one EVM key; Solana uses a separate ed25519 key. NEVER delete or rotate keys programmatically; direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.", {
+    server.tool("wallet_setup", "Set up or manage an Agent Wonderland launch payment method. Use 'start' for a guided USDC setup menu. 'create' makes a new crypto wallet (encrypted via OWS if available, otherwise plaintext — run 'enable-ows' to upgrade). 'import' takes an existing private key. 'enable-ows' installs the Open Wallet Standard native module for encrypted at-rest storage. Tempo/Base share one EVM key; Solana uses a separate ed25519 key. Card and Link actions are present for non-launch compatibility only and should not be recommended for launch runs. NEVER delete or rotate keys programmatically; direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.", {
         action: z
             .enum(["start", "create", "import", "add-card", "remove-card", "add-link", "remove-link", "enable-ows"])
-            .describe("'start' shows the guided payment setup menu, 'add-link' connects Link card/bank, 'create' makes a crypto wallet, 'import' imports an existing key, 'enable-ows' installs encrypted key storage"),
+            .describe("'start' shows the guided launch USDC setup menu, 'create' makes a crypto wallet, 'import' imports an existing key, 'enable-ows' installs encrypted key storage; add-card/add-link are non-launch compatibility actions"),
         name: z
             .string()
             .optional()
@@ -150,7 +147,7 @@ export function registerWalletTools(server) {
         link_payment_method_id: z.string().optional()
             .describe("Link payment method ID from `npx @stripe/link-cli payment-methods list`; used with action 'add-link'."),
         link_payment_method: z.string().optional()
-            .describe("Friendly Link payment method selector, such as a card/bank name or last4; used with action 'add-link'."),
+            .describe("Friendly Link payment method selector, such as a saved payment method label or last4; used with action 'add-link'."),
     }, async ({ action, name, key, chain, link_payment_method_id, link_payment_method }) => {
         if (action === "start") {
             return text(formatPaymentSetupMenu());

package/package.json

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

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

@@ -86,4 +86,48 @@ describe("api-client headers", () => {
       }),
     );
   });
+
+  it("labels playbook API calls with MCP surface, version, tool, and action headers", async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    }));
+    vi.stubGlobal("fetch", fetchMock);
+    const { apiGet, apiPost } = await import("../api-client.js");
+
+    await apiGet("/playbooks?limit=1");
+    await apiGet("/playbooks/competitor-ads");
+    await apiGet("/playbooks/competitor-ads/versions");
+    await apiGet("/playbooks/competitor-ads/versions/1");
+    await apiPost("/playbooks/competitor-ads/favorite", {});
+    await apiPost("/playbooks/competitor-ads/feedback", { rating: 5 });
+    await apiPost("/playbook-quotes", { slug: "competitor-ads", budget: 5 });
+    await apiPost("/playbook-runs", { slug: "competitor-ads", budget: 5 });
+    await apiGet("/playbook-runs/run-1");
+    await apiPost("/playbook-runs/run-1/steps/ads", { status: "running" });
+
+    const calls = (fetchMock.mock.calls as unknown as Array<[unknown, { headers?: unknown }]>).map(([url, init]) => ({
+      url: String(url).replace("https://api.agentwonderland.test", ""),
+      headers: init.headers as Record<string, string>,
+    }));
+
+    for (const call of calls) {
+      expect(call.headers).toMatchObject({
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-AW-Surface": "mcp",
+        "X-AW-MCP-Version": MCP_PACKAGE_VERSION,
+      });
+    }
+    expect(calls[0]).toMatchObject({ url: "/playbooks?limit=1", headers: { "X-AW-MCP-Tool": "search_playbooks", "X-AW-MCP-Action": "search" } });
+    expect(calls[1]).toMatchObject({ url: "/playbooks/competitor-ads", headers: { "X-AW-MCP-Tool": "get_playbook", "X-AW-MCP-Action": "view" } });
+    expect(calls[2]).toMatchObject({ url: "/playbooks/competitor-ads/versions", headers: { "X-AW-MCP-Tool": "get_playbook", "X-AW-MCP-Action": "view" } });
+    expect(calls[3]).toMatchObject({ url: "/playbooks/competitor-ads/versions/1", headers: { "X-AW-MCP-Tool": "get_playbook", "X-AW-MCP-Action": "view" } });
+    expect(calls[4]).toMatchObject({ url: "/playbooks/competitor-ads/favorite", headers: { "X-AW-MCP-Tool": "favorite_playbook", "X-AW-MCP-Action": "favorite" } });
+    expect(calls[5]).toMatchObject({ url: "/playbooks/competitor-ads/feedback", headers: { "X-AW-MCP-Tool": "rate_playbook", "X-AW-MCP-Action": "feedback" } });
+    expect(calls[6]).toMatchObject({ url: "/playbook-quotes", headers: { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": "quote" } });
+    expect(calls[7]).toMatchObject({ url: "/playbook-runs", headers: { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": "execute" } });
+    expect(calls[8]).toMatchObject({ url: "/playbook-runs/run-1", headers: { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": "poll" } });
+    expect(calls[9]).toMatchObject({ url: "/playbook-runs/run-1/steps/ads", headers: { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": "execute" } });
+  });
 });

package/src/core/__tests__/link-cli.test.ts

@@ -0,0 +1,125 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PendingLinkSpendRequest } from "../config.js";
+
+const {
+  execCalls,
+  outputs,
+  state,
+  mockExecFile,
+} = vi.hoisted(() => {
+  const execCalls: Array<{ file: string; args: string[] }> = [];
+  const outputs: unknown[] = [];
+  const state: { pending: PendingLinkSpendRequest | null; pendingWrites: Array<PendingLinkSpendRequest | null> } = {
+    pending: null,
+    pendingWrites: [],
+  };
+
+  type MockExecFile = ((file: string, args: string[], options: unknown, callback: (err: Error | null, stdout?: string, stderr?: string) => void) => void) & {
+    [key: symbol]: unknown;
+  };
+  const mockExecFile = vi.fn((file: string, args: string[], _options: unknown, callback: (err: Error | null, stdout?: string, stderr?: string) => void) => {
+    execCalls.push({ file, args });
+    const next = outputs.shift();
+    if (next instanceof Error) {
+      callback(next);
+      return;
+    }
+    callback(null, JSON.stringify(next ?? null), "");
+  }) as unknown as MockExecFile;
+  mockExecFile[Symbol.for("nodejs.util.promisify.custom")] = async (file: string, args: string[]) => {
+    execCalls.push({ file, args });
+    const next = outputs.shift();
+    if (next instanceof Error) {
+      throw next;
+    }
+    return { stdout: JSON.stringify(next ?? null), stderr: "" };
+  };
+
+  return { execCalls, outputs, state, mockExecFile };
+});
+
+vi.mock("node:child_process", () => ({
+  execFile: mockExecFile,
+}));
+
+vi.mock("../config.js", () => ({
+  getPendingLinkSpendRequest: () => state.pending,
+  setPendingLinkSpendRequest: (pending: PendingLinkSpendRequest | null) => {
+    state.pending = pending;
+    state.pendingWrites.push(pending);
+  },
+  setLinkCooldown: vi.fn(),
+}));
+
+describe("Link CLI spend requests", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    execCalls.length = 0;
+    outputs.length = 0;
+    state.pending = null;
+    state.pendingWrites = [];
+  });
+
+  it("returns an approval-required error immediately instead of blocking on Link approval", async () => {
+    outputs.push([
+      {
+        id: "lsrq_test_123",
+        approval_url: "https://link.example/approve/lsrq_test_123",
+        status: "pending_approval",
+      },
+    ]);
+
+    const { createLinkSharedPaymentToken, LinkApprovalRequiredError } = await import("../link-cli.js");
+
+    await expect(createLinkSharedPaymentToken({
+      amount: "10",
+      currency: "usd",
+      context: "Agent Wonderland test",
+      expiresAt: Math.floor(Date.now() / 1000) + 300,
+      networkId: "profile_test",
+      paymentMethodId: "csmrpd_test_123",
+    })).rejects.toBeInstanceOf(LinkApprovalRequiredError);
+
+    expect(execCalls).toHaveLength(1);
+    expect(execCalls[0]?.args).toContain("create");
+    expect(state.pendingWrites[0]).toMatchObject({
+      id: "lsrq_test_123",
+      approvalUrl: "https://link.example/approve/lsrq_test_123",
+      amount: "10",
+      currency: "usd",
+      networkId: "profile_test",
+      paymentMethodId: "csmrpd_test_123",
+    });
+  });
+
+  it("resumes a stored Link spend request and returns the approved shared payment token", async () => {
+    const expiresAt = Math.floor(Date.now() / 1000) + 300;
+    state.pending = {
+      id: "lsrq_test_123",
+      approvalUrl: "https://link.example/approve/lsrq_test_123",
+      amount: "10",
+      currency: "usd",
+      context: "Agent Wonderland test",
+      expiresAt,
+      networkId: "profile_test",
+      paymentMethodId: "csmrpd_test_123",
+      createdAt: new Date().toISOString(),
+    };
+    outputs.push({ shared_payment_token: "spt_test_123" });
+
+    const { createLinkSharedPaymentToken } = await import("../link-cli.js");
+
+    await expect(createLinkSharedPaymentToken({
+      amount: "10",
+      currency: "usd",
+      context: "Agent Wonderland test",
+      expiresAt,
+      networkId: "profile_test",
+      paymentMethodId: "csmrpd_test_123",
+    })).resolves.toBe("spt_test_123");
+
+    expect(execCalls).toHaveLength(1);
+    expect(execCalls[0]?.args).toEqual(expect.arrayContaining(["spend-request", "retrieve", "lsrq_test_123"]));
+    expect(state.pendingWrites).toEqual([null]);
+  });
+});

package/src/core/api-client.ts

@@ -40,6 +40,24 @@ function inferToolHeaders(path: string, method: string): Record<string, string>
   if (path.startsWith("/agents?") || path === "/agents" || path === "/agents/search") {
     return { "X-AW-MCP-Tool": "search_agents", "X-AW-MCP-Action": "search" };
   }
+  if (path.startsWith("/playbooks?") || path === "/playbooks") {
+    return { "X-AW-MCP-Tool": "search_playbooks", "X-AW-MCP-Action": "search" };
+  }
+  if (/^\/playbooks\/[^/]+(?:\/versions(?:\/[^/]+)?)?$/.test(path)) {
+    return { "X-AW-MCP-Tool": "get_playbook", "X-AW-MCP-Action": "view" };
+  }
+  if (/^\/playbooks\/[^/]+\/favorite$/.test(path)) {
+    return { "X-AW-MCP-Tool": "favorite_playbook", "X-AW-MCP-Action": "favorite" };
+  }
+  if (/^\/playbooks\/[^/]+\/feedback$/.test(path)) {
+    return { "X-AW-MCP-Tool": "rate_playbook", "X-AW-MCP-Action": "feedback" };
+  }
+  if (path === "/playbook-quotes") {
+    return { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": "quote" };
+  }
+  if (path === "/playbook-runs" || path.startsWith("/playbook-runs/")) {
+    return { "X-AW-MCP-Tool": "run_playbook", "X-AW-MCP-Action": method === "GET" ? "poll" : "execute" };
+  }
   if (/^\/agents\/[^/]+$/.test(path)) {
     return { "X-AW-MCP-Tool": "get_agent", "X-AW-MCP-Action": "view" };
   }

package/src/core/link-cli.ts

@@ -11,8 +11,23 @@ const execFileAsync = promisify(execFile);
 const LINK_CLI_PACKAGE = "@stripe/link-cli";
 const LINK_CLI_TIMEOUT_MS = 10 * 60 * 1000;
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+export class LinkApprovalRequiredError extends Error {
+  constructor(
+    public readonly spendRequestId: string,
+    public readonly approvalUrl?: string,
+  ) {
+    super(formatLinkApprovalRequiredMessage(spendRequestId, approvalUrl));
+    this.name = "LinkApprovalRequiredError";
+  }
+}
+
+function formatLinkApprovalRequiredMessage(spendRequestId: string, approvalUrl?: string): string {
+  return [
+    "Link approval required.",
+    "The agent has not run yet and no charge has been captured.",
+    approvalUrl ? `Approve this spend request in Link: ${approvalUrl}` : `Spend request: ${spendRequestId}`,
+    "After approving, rerun the same tool call with confirmed: true.",
+  ].join("\n");
 }
 
 export interface LinkCliAuthStatus {
@@ -264,6 +279,9 @@ export async function createLinkSharedPaymentToken(params: {
       return spt;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      if (err instanceof LinkApprovalRequiredError) {
+        throw err;
+      }
       if (!/denied|expired|not found|without a shared payment token|POLLING_TIMEOUT/i.test(message)) {
         throw err;
       }
@@ -344,9 +362,7 @@ export async function createLinkSharedPaymentToken(params: {
     if (approval.approvalUrl) {
       console.error(`Link approval required: ${approval.approvalUrl}`);
     }
-    const retrievedSpt = await retrieveSharedPaymentToken(approval.id, approval.approvalUrl);
-    setPendingLinkSpendRequest(null);
-    return retrievedSpt;
+    throw new LinkApprovalRequiredError(approval.id, approval.approvalUrl);
   }
 
   {
@@ -355,32 +371,14 @@ export async function createLinkSharedPaymentToken(params: {
 }
 
 async function retrieveSharedPaymentToken(spendRequestId: string, approvalUrl?: string): Promise<string> {
-  let retrieved = await runLinkCli([
+  const 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);
-  }
+  ], 30_000);
+  const 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"),
-  );
+  throw new LinkApprovalRequiredError(spendRequestId, approvalUrl);
 }

package/src/core/version.ts

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.51";
+export const MCP_PACKAGE_VERSION = "0.1.54";

package/src/index.ts

@@ -18,6 +18,7 @@ import { registerRebateTools } from "./tools/rebates.js";
 import { registerUploadTools } from "./tools/upload.js";
 import { registerProbeTools } from "./tools/probe.js";
 import { registerProviderTools } from "./tools/providers.js";
+import { registerPlaybookTools } from "./tools/playbooks.js";
 
 // ── Resources ────────────────────────────────────────────────────
 import { registerAgentResources } from "./resources/agents.js";
@@ -48,16 +49,17 @@ export async function startMcpServer(): Promise<void> {
         "WORKFLOW:",
         "1. solve(intent, input, budget) — one call: find best agent + pay + run. Use when the task is clear.",
         "   OR: search_agents() → get_agent() to inspect schema → run_agent() with required fields.",
+        "   For multi-agent workflows, use search_playbooks() → get_playbook() → run_playbook().",
         "2. If the agent returns status 'processing', poll with get_job(). Async runs resolve automatically.",
-        "3. After a successful run, rate_agent() and optionally tip_agent() if the result was useful.",
+        "3. After a successful agent run, rate_agent() and optionally tip_agent() if the result was useful.",
+        "   After a successful playbook run, offer favorite_playbook() or rate_playbook() using the returned run_id.",
         "4. Use list_jobs() to recover state across sessions (it checks every configured wallet).",
         "",
         "PAYMENT:",
-        "- Supported payment methods: Link card/bank via @stripe/link-cli, Tempo USDC, Base USDC, and Solana USDC.",
-        "- Link payments may ask the user to approve a spend request in Link before the first charge.",
+        "- Supported launch payment methods: Tempo USDC, Base USDC, and Solana USDC.",
         "- Tempo and Base share one EVM wallet key. Solana uses a separate ed25519 key. One OWS wallet can manage both.",
         "- If pay_with is omitted, the MCP auto-selects a compatible configured rail. Pass pay_with explicitly",
-        "  (tempo | base | solana | link | wallet-id) for deterministic behavior.",
+        "  (tempo | base | solana | wallet-id) for deterministic behavior.",
         "- Payment is automatic: on a 402 challenge the MCP signs on-chain, submits, then retries. Failed runs are refunded.",
         "- If a specific rail fails, surface the real reason — do NOT silently retry with a different method.",
         "- Headless/automation: set wallet_set_policy() to cap max_per_tx and max_per_day so a runaway loop can't drain funds.",
@@ -73,7 +75,7 @@ export async function startMcpServer(): Promise<void> {
         "WALLET HYGIENE:",
         "- wallet_status shows per-chain USDC balance and the active network (mainnet vs testnet).",
         "- rebate_status shows accrued, pending, paid, and blocked consumer rebates plus recent payout transactions.",
-        "- To set up payments: wallet_setup({ action: \"start\" }). Link card/bank is recommended for most users.",
+        "- To set up payments: wallet_setup({ action: \"start\" }). Use Tempo, Base, or Solana USDC for launch runs.",
         "- To create or import a crypto wallet directly: wallet_setup({ action: \"create\" }) or { action: \"import\", key }.",
         "- NEVER delete or rotate keys programmatically. Direct users to edit ~/.agentwonderland/config.json or ~/.ows/ manually.",
       ].join("\n"),
@@ -95,6 +97,7 @@ export async function startMcpServer(): Promise<void> {
   registerUploadTools(server);
   registerProbeTools(server);
   registerProviderTools(server);
+  registerPlaybookTools(server);
 
   // Register resources
   registerAgentResources(server);