@agentwonderland/mcp 0.1.52 → 0.1.54

package/dist/core/__tests__/api-client.test.js

@@ -56,4 +56,44 @@ 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.map(([url, init]) => ({
+            url: String(url).replace("https://api.agentwonderland.test", ""),
+            headers: init.headers,
+        }));
+        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/dist/core/__tests__/link-cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/link-cli.test.js

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const { execCalls, outputs, state, mockExecFile, } = vi.hoisted(() => {
+    const execCalls = [];
+    const outputs = [];
+    const state = {
+        pending: null,
+        pendingWrites: [],
+    };
+    const mockExecFile = vi.fn((file, args, _options, callback) => {
+        execCalls.push({ file, args });
+        const next = outputs.shift();
+        if (next instanceof Error) {
+            callback(next);
+            return;
+        }
+        callback(null, JSON.stringify(next ?? null), "");
+    });
+    mockExecFile[Symbol.for("nodejs.util.promisify.custom")] = async (file, args) => {
+        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) => {
+        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/dist/core/api-client.js

@@ -23,6 +23,24 @@ function inferToolHeaders(path, method) {
     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/dist/core/link-cli.d.ts

@@ -1,3 +1,8 @@
+export declare class LinkApprovalRequiredError extends Error {
+    readonly spendRequestId: string;
+    readonly approvalUrl?: string | undefined;
+    constructor(spendRequestId: string, approvalUrl?: string | undefined);
+}
 export interface LinkCliAuthStatus {
     authenticated: boolean;
     credentialsPath?: string;

package/dist/core/link-cli.js

@@ -4,8 +4,23 @@ import { getPendingLinkSpendRequest, setLinkCooldown, setPendingLinkSpendRequest
 const execFileAsync = promisify(execFile);
 const LINK_CLI_PACKAGE = "@stripe/link-cli";
 const LINK_CLI_TIMEOUT_MS = 10 * 60 * 1000;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export class LinkApprovalRequiredError extends Error {
+    spendRequestId;
+    approvalUrl;
+    constructor(spendRequestId, approvalUrl) {
+        super(formatLinkApprovalRequiredMessage(spendRequestId, approvalUrl));
+        this.spendRequestId = spendRequestId;
+        this.approvalUrl = approvalUrl;
+        this.name = "LinkApprovalRequiredError";
+    }
+}
+function formatLinkApprovalRequiredMessage(spendRequestId, approvalUrl) {
+    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");
 }
 async function runLinkCli(args, timeout = LINK_CLI_TIMEOUT_MS) {
     try {
@@ -220,6 +235,9 @@ export async function createLinkSharedPaymentToken(params) {
         }
         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;
             }
@@ -293,39 +311,21 @@ 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);
     }
     {
         throw new Error("Link spend request completed without a shared payment token in the CLI response.");
     }
 }
 async function retrieveSharedPaymentToken(spendRequestId, approvalUrl) {
-    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/dist/core/version.d.ts

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

package/dist/core/version.js

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

package/dist/index.js

@@ -16,6 +16,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";
 import { registerWalletResources } from "./resources/wallet.js";
@@ -41,16 +42,17 @@ export async function startMcpServer() {
             "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.",
@@ -66,7 +68,7 @@ export async function startMcpServer() {
             "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"),
@@ -86,6 +88,7 @@ export async function startMcpServer() {
     registerUploadTools(server);
     registerProbeTools(server);
     registerProviderTools(server);
+    registerPlaybookTools(server);
     // Register resources
     registerAgentResources(server);
     registerWalletResources(server);

package/dist/tools/__tests__/playbooks.test.d.ts

@@ -0,0 +1 @@
+export {};