@agentwonderland/mcp 0.1.56 → 0.1.57

package/dist/core/version.d.ts

@@ -1 +1 @@
-export declare const MCP_PACKAGE_VERSION = "0.1.56";
+export declare const MCP_PACKAGE_VERSION = "0.1.57";

package/dist/core/version.js

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.56";
+export const MCP_PACKAGE_VERSION = "0.1.57";

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,8 +42,10 @@ 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 agent run, rate_agent() and optionally tip_agent() if the result was useful.",
+            "   Playbooks return one run-level receipt; do not ask users to rate or tip individual child-agent steps.",
             "4. Use list_jobs() to recover state across sessions (it checks every configured wallet).",
             "",
             "PAYMENT:",
@@ -85,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__/playbook-adapters.test.d.ts

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

package/dist/tools/__tests__/playbook-adapters.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { buildExplicitPlaybookStepInput, playbookRunBlocker } from "../playbook-adapters.js";
+describe("playbook step adapters", () => {
+    it("maps ipo-brief child steps to their live input schemas", () => {
+        expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL" }, {
+            id: "s1",
+            agent_slug: "ipo-s-1-analysis",
+        })).toMatchObject({ status: "ready", input: { ticker: "CRCL" } });
+        expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL" }, {
+            id: "insiders",
+            agent_slug: "insider-trading-tracker",
+        })).toMatchObject({ status: "ready", input: { ticker: "CRCL", days_back: 365 } });
+        expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL", peer_tickers: ["COIN", "HOOD"] }, {
+            id: "comps",
+            agent_slug: "stock-comparison",
+        })).toMatchObject({ status: "ready", input: { tickers: ["CRCL", "COIN", "HOOD"] } });
+    });
+    it("maps launch-landing council, writer, and publisher steps explicitly", () => {
+        const council = buildExplicitPlaybookStepInput("launch-landing", {
+            brief: "Agent marketplace for builders",
+            product_slug: "agent-wonderland",
+        }, {
+            id: "council",
+            agent_slug: "marketing-copy-council",
+        });
+        expect(council).toMatchObject({ status: "ready", input: { brief: "Agent marketplace for builders" } });
+        const writer = buildExplicitPlaybookStepInput("launch-landing", {
+            brief: "Agent marketplace for builders",
+            product_slug: "agent-wonderland",
+            previous_outputs: [{ step: "council", output: { headline: "Hire agents on demand" } }],
+        }, {
+            id: "structure",
+            agent_slug: "write-landing-page-copy",
+        });
+        expect(writer).toMatchObject({
+            status: "ready",
+            input: {
+                product: "agent-wonderland",
+                audience: "builders and operators",
+            },
+        });
+        expect(writer.input.context).toContain("Hire agents on demand");
+        const publisher = buildExplicitPlaybookStepInput("launch-landing", {
+            brief: "Agent marketplace for builders",
+            product_slug: "agent-wonderland",
+            previous_outputs: [{ step: "structure", output: { html: "<html><body>Ship</body></html>" } }],
+        }, {
+            id: "publish",
+            agent_slug: "publish-html-to-a-public-url",
+        });
+        expect(publisher).toMatchObject({
+            status: "ready",
+            input: {
+                html: "<html><body>Ship</body></html>",
+                slug: "agent-wonderland",
+            },
+        });
+    });
+    it("blocks known broken fanout playbooks before paid child execution", () => {
+        expect(playbookRunBlocker("icp-hunter")).toContain("prospect-search schema");
+        expect(playbookRunBlocker("no-web-leads")).toContain("no-web/place/phone schemas");
+        expect(buildExplicitPlaybookStepInput("icp-hunter", { icp: "VP Eng" }, {
+            id: "prospects",
+            agent_slug: "find-prospects",
+        })).toMatchObject({ status: "blocked", code: "PLAYBOOK_NOT_CERTIFIED" });
+    });
+});

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

@@ -533,7 +533,7 @@ describe("playbook MCP tools", () => {
         expect(text).not.toContain("favorite_playbook({ slug: \"competitor-ads\" })");
         expect(text).not.toContain("rate_playbook");
     });
-    it("uses one approved Link spend request across paid playbook child steps", async () => {
+    it("uses a separate approved Link spend request for the paid child step", async () => {
         mockRequiresSpendConfirmation.mockReturnValue(false);
         mockGetConfiguredMethods.mockReturnValue(["link"]);
         mockApiGet
@@ -599,8 +599,9 @@ describe("playbook MCP tools", () => {
         const text = flattenToolText(result);
         expect(mockDecodeMppNetworkId).toHaveBeenCalledWith("Payment challenge");
         expect(mockEnsureApprovedLinkSpendRequest).toHaveBeenCalledWith(expect.objectContaining({
-            amount: "500",
+            amount: "125",
             currency: "usd",
+            context: expect.stringContaining("step 1"),
             networkId: "profile_test",
             paymentMethodId: "csmrpd_test_123",
         }));

package/dist/tools/index.d.ts

@@ -12,3 +12,4 @@ export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";
+export { registerPlaybookTools } from "./playbooks.js";

package/dist/tools/index.js

@@ -12,3 +12,4 @@ export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";
+export { registerPlaybookTools } from "./playbooks.js";

package/dist/tools/playbook-adapters.d.ts

@@ -0,0 +1,19 @@
+type StepLike = {
+    id: string;
+    agent_slug: string | null;
+    default_input?: Record<string, unknown>;
+    quantity?: number;
+    iteration?: number;
+};
+export type PlaybookStepInputResult = {
+    status: "ready";
+    input: Record<string, unknown>;
+    certification: "explicit";
+} | {
+    status: "blocked";
+    code: string;
+    message: string;
+};
+export declare function playbookRunBlocker(slug: string): string | null;
+export declare function buildExplicitPlaybookStepInput(playbookSlug: string, baseInput: Record<string, unknown>, step: StepLike): PlaybookStepInputResult | null;
+export {};

package/dist/tools/playbook-adapters.js

@@ -0,0 +1,164 @@
+const BLOCKED_PLAYBOOKS = {
+    "icp-hunter": "Blocked until the friendly ICP input is mapped to the live prospect-search schema and the prospect agent is verified to honor those filters.",
+    "no-web-leads": "Blocked until zip/category inputs are mapped to the live no-web/place/phone schemas and the no-web agent is verified to honor the requested local filters.",
+};
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function outputRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function previousOutputs(input) {
+    return Array.isArray(input.previous_outputs)
+        ? input.previous_outputs.map(outputRecord).filter((item) => Boolean(item))
+        : [];
+}
+function stepOutput(entry) {
+    return outputRecord(entry)?.output ?? entry;
+}
+function extractHtml(value) {
+    if (typeof value === "string" && /<html|<!doctype|<body|<section|<main/i.test(value))
+        return value;
+    const record = outputRecord(value);
+    if (!record)
+        return undefined;
+    const direct = record.html;
+    if (typeof direct === "string" && direct.trim())
+        return direct;
+    const output = record.output;
+    if (typeof output === "string" && /<html|<!doctype|<body|<section|<main/i.test(output))
+        return output;
+    const nested = outputRecord(output);
+    return typeof nested?.html === "string" && nested.html.trim() ? nested.html : undefined;
+}
+function launchLandingInput(baseInput, step) {
+    const brief = asString(baseInput.brief) ?? asString(baseInput.context) ?? asString(baseInput.product);
+    if (!brief) {
+        return {
+            status: "blocked",
+            code: "PLAYBOOK_INPUT_MISSING_BRIEF",
+            message: "launch-landing requires a brief before any child agent is called.",
+        };
+    }
+    if (step.agent_slug === "marketing-copy-council") {
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: {
+                brief,
+                context: {
+                    product_slug: asString(baseInput.product_slug),
+                },
+                num_outputs: 1,
+            },
+        };
+    }
+    const outputs = previousOutputs(baseInput);
+    if (step.agent_slug === "write-landing-page-copy") {
+        const council = outputs.find((item) => item.step === "council" || item.step === "marketing-copy-council") ?? outputs.at(-1);
+        const product = asString(baseInput.product)
+            ?? asString(baseInput.product_name)
+            ?? asString(baseInput.product_slug)
+            ?? "Landing page";
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: {
+                product,
+                audience: asString(baseInput.audience) ?? "builders and operators",
+                tone: asString(baseInput.tone) ?? "confident and practical",
+                context: JSON.stringify({
+                    brief,
+                    product_slug: asString(baseInput.product_slug),
+                    council_output: stepOutput(council),
+                }),
+            },
+        };
+    }
+    if (step.agent_slug === "publish-html-to-a-public-url") {
+        const writer = outputs.find((item) => item.step === "structure" || item.step === "write-landing-page-copy") ?? outputs.at(-1);
+        const html = extractHtml(stepOutput(writer)) ?? extractHtml(writer);
+        if (!html) {
+            return {
+                status: "blocked",
+                code: "PLAYBOOK_INPUT_MISSING_HTML",
+                message: "launch-landing publish step requires generated HTML from the writer step.",
+            };
+        }
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: {
+                html,
+                slug: asString(baseInput.product_slug) ?? asString(baseInput.slug),
+                title: asString(baseInput.title) ?? asString(baseInput.product) ?? asString(baseInput.product_slug),
+            },
+        };
+    }
+    return {
+        status: "blocked",
+        code: "PLAYBOOK_STEP_NOT_CERTIFIED",
+        message: `launch-landing step ${step.id} (${step.agent_slug ?? "unknown"}) has no explicit adapter.`,
+    };
+}
+function ipoBriefInput(baseInput, step) {
+    const ticker = asString(baseInput.ticker) ?? asString(baseInput.symbol);
+    if (!ticker) {
+        return {
+            status: "blocked",
+            code: "PLAYBOOK_INPUT_MISSING_TICKER",
+            message: "ipo-brief requires ticker before any child agent is called.",
+        };
+    }
+    if (step.agent_slug === "ipo-s-1-analysis") {
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: { ticker },
+        };
+    }
+    if (step.agent_slug === "insider-trading-tracker") {
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: {
+                ticker,
+                days_back: Number(baseInput.days_back ?? 365),
+            },
+        };
+    }
+    if (step.agent_slug === "stock-comparison") {
+        const peers = Array.isArray(baseInput.peer_tickers) ? baseInput.peer_tickers : [];
+        const tickers = [ticker, ...peers].filter((item) => typeof item === "string" && Boolean(item.trim())).slice(0, 5);
+        return {
+            status: "ready",
+            certification: "explicit",
+            input: { tickers },
+        };
+    }
+    return {
+        status: "blocked",
+        code: "PLAYBOOK_STEP_NOT_CERTIFIED",
+        message: `ipo-brief step ${step.id} (${step.agent_slug ?? "unknown"}) has no explicit adapter.`,
+    };
+}
+export function playbookRunBlocker(slug) {
+    return BLOCKED_PLAYBOOKS[slug] ?? null;
+}
+export function buildExplicitPlaybookStepInput(playbookSlug, baseInput, step) {
+    const blocker = playbookRunBlocker(playbookSlug);
+    if (blocker) {
+        return {
+            status: "blocked",
+            code: "PLAYBOOK_NOT_CERTIFIED",
+            message: blocker,
+        };
+    }
+    if (playbookSlug === "launch-landing")
+        return launchLandingInput(baseInput, step);
+    if (playbookSlug === "ipo-brief")
+        return ipoBriefInput(baseInput, step);
+    return null;
+}

package/dist/tools/playbooks.js

@@ -7,6 +7,7 @@ import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend
 import { formatRunResult } from "../core/formatters.js";
 import { decodeMppNetworkId, ensureApprovedLinkSpendRequest, LinkApprovalRequiredError, } from "../core/link-cli.js";
 import { formatPaymentLabel, resolveConfirmationMethod, } from "./_payment-confirmation.js";
+import { buildExplicitPlaybookStepInput, playbookRunBlocker } from "./playbook-adapters.js";
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 300000;
 const pendingPlaybookRuns = new Map();
@@ -33,9 +34,9 @@ function fanoutControls(playbook) {
 }
 function buildPlaybookLinkApprovalContext(params) {
     return [
-        `Approve up to ${money(params.budget)} for the Agent Wonderland "${params.playbook.name}" playbook.`,
-        `This playbook run ${params.runId} has ${params.stepCount} child-agent steps and will stop before exceeding the approved budget.`,
-        "Each child agent is still charged at its exact quoted price, unused budget is not spent, and failed child runs keep the existing Agent Wonderland refund behavior.",
+        `Approve ${money(params.step.quoted_cost_usd)} for step ${params.step.index + 1} of the Agent Wonderland "${params.playbook.name}" playbook.`,
+        `Run ${params.runId}, step ${params.step.id}: ${params.step.agent_name}.`,
+        "Each child agent is approved separately, and failed child runs keep the existing Agent Wonderland refund behavior.",
     ].join(" ");
 }
 async function collectWalletAddresses(paymentMethod) {
@@ -217,7 +218,15 @@ async function formatCheaperAlternatives(currentSlug, budget) {
         return "";
     }
 }
-function stepInput(baseInput, step, iteration) {
+function stepInput(playbookSlug, baseInput, step, iteration) {
+    const explicit = buildExplicitPlaybookStepInput(playbookSlug, baseInput, step);
+    if (explicit?.status === "ready")
+        return explicit.input;
+    if (explicit?.status === "blocked") {
+        const error = new Error(explicit.message);
+        error.code = explicit.code;
+        throw error;
+    }
     const input = { ...(step.default_input ?? {}), ...baseInput };
     const itemIndex = Math.max(0, (step.iteration ?? 1) - 1);
     if (Array.isArray(input.leads) && input.leads[itemIndex] && typeof input.leads[itemIndex] === "object") {
@@ -591,6 +600,10 @@ export function registerPlaybookTools(server) {
         if (playbook.current_quote.blocking_issues.length > 0) {
             return text(`Cannot run ${playbook.slug}; child-agent issues must be fixed first:\n${playbook.current_quote.blocking_issues.map((issue) => `- ${issue}`).join("\n")}`);
         }
+        const blocker = playbookRunBlocker(playbook.slug);
+        if (blocker) {
+            return text(`Playbook ${playbook.slug} is temporarily paused for certification.\n\n${blocker}`);
+        }
         const runLimits = appliedPlaybookLimits(playbook) ?? effectiveLimits;
         const estimatedCost = playbook.current_quote.estimated_cost_usd;
         const spendCheck = canSpend({ method: spendMethod, amountUsd: Math.min(effectiveBudget, estimatedCost) });
@@ -684,14 +697,7 @@ export function registerPlaybookTools(server) {
         await apiPost(`/playbook-runs/${runState.run_id}/status`, { status: "running" });
         let charged = runState.chargedUsd;
         const childOutputs = [...runState.existingOutputs];
-        let linkSpendRequestId;
         let linkNetworkId;
-        const linkApprovalContext = buildPlaybookLinkApprovalContext({
-            playbook,
-            budget: effectiveBudget,
-            stepCount: playbook.current_quote.step_count,
-            runId: runState.run_id,
-        });
         for (const [iteration, step] of runState.steps.entries()) {
             if (runState.completedStepIds.has(step.id)) {
                 continue;
@@ -727,7 +733,28 @@ export function registerPlaybookTools(server) {
                 provider_id: step.provider_id,
                 quoted_cost_usd: step.quoted_cost_usd,
             });
-            const payload = stepInput({ ...processedInput, previous_outputs: childOutputs }, step, iteration);
+            let payload;
+            try {
+                payload = stepInput(playbook.slug, { ...processedInput, previous_outputs: childOutputs }, step, iteration);
+            }
+            catch (err) {
+                const blocked = err;
+                await recordStep(runState.run_id, step.id, {
+                    status: "skipped",
+                    agent_id: step.agent_id,
+                    provider_id: step.provider_id,
+                    consumption_mode: "not_charged",
+                    error_code: blocked.code ?? "PLAYBOOK_STEP_INPUT_BLOCKED",
+                    failure_message: blocked.message,
+                });
+                await updateRun(runState.run_id, {
+                    status: "paused",
+                    error_code: blocked.code ?? "PLAYBOOK_STEP_INPUT_BLOCKED",
+                    failure_message: blocked.message,
+                });
+                const receipt = await apiGet(`/playbook-runs/${runState.run_id}`);
+                return text(`${formatReceipt(receipt)}\n\n${blocked.message}`);
+            }
             const playbookContext = {
                 playbook_run_id: runState.run_id,
                 playbook_id: playbook.id,
@@ -738,6 +765,7 @@ export function registerPlaybookTools(server) {
             let result;
             let schemaError;
             let usedPaidMethod = false;
+            let stepLinkSpendRequestId;
             const executeChild = async (childInput) => {
                 const body = { input: childInput, playbook_context: playbookContext };
                 try {
@@ -758,15 +786,19 @@ export function registerPlaybookTools(server) {
                             throw new Error("Link payment challenge did not include a WWW-Authenticate header.");
                         }
                         linkNetworkId = linkNetworkId ?? await decodeMppNetworkId(challenge);
-                        linkSpendRequestId = linkSpendRequestId ?? await ensureApprovedLinkSpendRequest({
-                            amount: cents(effectiveBudget),
+                        stepLinkSpendRequestId = await ensureApprovedLinkSpendRequest({
+                            amount: cents(step.quoted_cost_usd),
                             currency: "usd",
-                            context: linkApprovalContext,
+                            context: buildPlaybookLinkApprovalContext({
+                                playbook,
+                                runId: runState.run_id,
+                                step,
+                            }),
                             expiresAt: Math.floor(Date.now() / 1000) + 3600,
                             networkId: linkNetworkId,
                             paymentMethodId: linkConfig.paymentMethodId,
                         });
-                        return await apiPostWithApprovedLinkSpendRequest(`/agents/${step.agent_id}/run`, body, linkSpendRequestId);
+                        return await apiPostWithApprovedLinkSpendRequest(`/agents/${step.agent_id}/run`, body, stepLinkSpendRequestId);
                     }
                     return await apiPostWithPayment(`/agents/${step.agent_id}/run`, body, method);
                 }
@@ -818,6 +850,9 @@ export function registerPlaybookTools(server) {
                 }
                 else {
                     const errorCode = apiErr?.status === 402 ? "PAYMENT_REJECTED" : "CHILD_AGENT_FAILED";
+                    if ((method ?? spendMethod) === "link" && stepLinkSpendRequestId) {
+                        setPendingLinkSpendRequest(null);
+                    }
                     await recordStep(runState.run_id, step.id, {
                         status: apiErr?.status === 402 ? "skipped" : "failed",
                         agent_id: step.agent_id,
@@ -838,6 +873,9 @@ export function registerPlaybookTools(server) {
                     return text(`${formatReceipt(receipt)}\n\n${help}`);
                 }
             }
+            if (result && (method ?? spendMethod) === "link" && stepLinkSpendRequestId) {
+                setPendingLinkSpendRequest(null);
+            }
             if (!result) {
                 await recordStep(runState.run_id, step.id, {
                     status: "skipped",
@@ -957,9 +995,6 @@ export function registerPlaybookTools(server) {
         });
         const receipt = await apiGet(`/playbook-runs/${runState.run_id}`);
         pendingPlaybookRuns.delete(playbook.slug);
-        if ((method ?? spendMethod) === "link" && linkSpendRequestId) {
-            setPendingLinkSpendRequest(null);
-        }
         const runBlocks = childOutputs.length > 0
             ? childOutputs.map((item) => item.output ? formatRunResult({ status: "success", job_id: item.job_id, output: item.output }, { paymentMethod: method }) : "").filter(Boolean)
             : [];

package/package.json

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

package/src/core/version.ts

@@ -1 +1 @@
-export const MCP_PACKAGE_VERSION = "0.1.56";
+export const MCP_PACKAGE_VERSION = "0.1.57";

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,8 +49,10 @@ 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 agent run, rate_agent() and optionally tip_agent() if the result was useful.",
+        "   Playbooks return one run-level receipt; do not ask users to rate or tip individual child-agent steps.",
         "4. Use list_jobs() to recover state across sessions (it checks every configured wallet).",
         "",
         "PAYMENT:",
@@ -94,6 +97,7 @@ export async function startMcpServer(): Promise<void> {
   registerUploadTools(server);
   registerProbeTools(server);
   registerProviderTools(server);
+  registerPlaybookTools(server);
 
   // Register resources
   registerAgentResources(server);

package/src/tools/__tests__/playbook-adapters.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { buildExplicitPlaybookStepInput, playbookRunBlocker } from "../playbook-adapters.js";
+
+describe("playbook step adapters", () => {
+  it("maps ipo-brief child steps to their live input schemas", () => {
+    expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL" }, {
+      id: "s1",
+      agent_slug: "ipo-s-1-analysis",
+    })).toMatchObject({ status: "ready", input: { ticker: "CRCL" } });
+
+    expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL" }, {
+      id: "insiders",
+      agent_slug: "insider-trading-tracker",
+    })).toMatchObject({ status: "ready", input: { ticker: "CRCL", days_back: 365 } });
+
+    expect(buildExplicitPlaybookStepInput("ipo-brief", { ticker: "CRCL", peer_tickers: ["COIN", "HOOD"] }, {
+      id: "comps",
+      agent_slug: "stock-comparison",
+    })).toMatchObject({ status: "ready", input: { tickers: ["CRCL", "COIN", "HOOD"] } });
+  });
+
+  it("maps launch-landing council, writer, and publisher steps explicitly", () => {
+    const council = buildExplicitPlaybookStepInput("launch-landing", {
+      brief: "Agent marketplace for builders",
+      product_slug: "agent-wonderland",
+    }, {
+      id: "council",
+      agent_slug: "marketing-copy-council",
+    });
+    expect(council).toMatchObject({ status: "ready", input: { brief: "Agent marketplace for builders" } });
+
+    const writer = buildExplicitPlaybookStepInput("launch-landing", {
+      brief: "Agent marketplace for builders",
+      product_slug: "agent-wonderland",
+      previous_outputs: [{ step: "council", output: { headline: "Hire agents on demand" } }],
+    }, {
+      id: "structure",
+      agent_slug: "write-landing-page-copy",
+    });
+    expect(writer).toMatchObject({
+      status: "ready",
+      input: {
+        product: "agent-wonderland",
+        audience: "builders and operators",
+      },
+    });
+    expect((writer as { input: Record<string, unknown> }).input.context).toContain("Hire agents on demand");
+
+    const publisher = buildExplicitPlaybookStepInput("launch-landing", {
+      brief: "Agent marketplace for builders",
+      product_slug: "agent-wonderland",
+      previous_outputs: [{ step: "structure", output: { html: "<html><body>Ship</body></html>" } }],
+    }, {
+      id: "publish",
+      agent_slug: "publish-html-to-a-public-url",
+    });
+    expect(publisher).toMatchObject({
+      status: "ready",
+      input: {
+        html: "<html><body>Ship</body></html>",
+        slug: "agent-wonderland",
+      },
+    });
+  });
+
+  it("blocks known broken fanout playbooks before paid child execution", () => {
+    expect(playbookRunBlocker("icp-hunter")).toContain("prospect-search schema");
+    expect(playbookRunBlocker("no-web-leads")).toContain("no-web/place/phone schemas");
+    expect(buildExplicitPlaybookStepInput("icp-hunter", { icp: "VP Eng" }, {
+      id: "prospects",
+      agent_slug: "find-prospects",
+    })).toMatchObject({ status: "blocked", code: "PLAYBOOK_NOT_CERTIFIED" });
+  });
+});

package/src/tools/__tests__/playbooks.test.ts

@@ -621,7 +621,7 @@ describe("playbook MCP tools", () => {
     expect(text).not.toContain("rate_playbook");
   });
 
-  it("uses one approved Link spend request across paid playbook child steps", async () => {
+  it("uses a separate approved Link spend request for the paid child step", async () => {
     mockRequiresSpendConfirmation.mockReturnValue(false);
     mockGetConfiguredMethods.mockReturnValue(["link"]);
     mockApiGet
@@ -690,8 +690,9 @@ describe("playbook MCP tools", () => {
 
     expect(mockDecodeMppNetworkId).toHaveBeenCalledWith("Payment challenge");
     expect(mockEnsureApprovedLinkSpendRequest).toHaveBeenCalledWith(expect.objectContaining({
-      amount: "500",
+      amount: "125",
       currency: "usd",
+      context: expect.stringContaining("step 1"),
       networkId: "profile_test",
       paymentMethodId: "csmrpd_test_123",
     }));

package/src/tools/index.ts

@@ -12,3 +12,4 @@ export { registerRebateTools } from "./rebates.js";
 export { registerUploadTools } from "./upload.js";
 export { registerProbeTools } from "./probe.js";
 export { registerProviderTools } from "./providers.js";
+export { registerPlaybookTools } from "./playbooks.js";

package/src/tools/playbook-adapters.ts

@@ -0,0 +1,199 @@
+type StepLike = {
+  id: string;
+  agent_slug: string | null;
+  default_input?: Record<string, unknown>;
+  quantity?: number;
+  iteration?: number;
+};
+
+export type PlaybookStepInputResult =
+  | {
+      status: "ready";
+      input: Record<string, unknown>;
+      certification: "explicit";
+    }
+  | {
+      status: "blocked";
+      code: string;
+      message: string;
+    };
+
+const BLOCKED_PLAYBOOKS: Record<string, string> = {
+  "icp-hunter": "Blocked until the friendly ICP input is mapped to the live prospect-search schema and the prospect agent is verified to honor those filters.",
+  "no-web-leads": "Blocked until zip/category inputs are mapped to the live no-web/place/phone schemas and the no-web agent is verified to honor the requested local filters.",
+};
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function outputRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function previousOutputs(input: Record<string, unknown>): Array<Record<string, unknown>> {
+  return Array.isArray(input.previous_outputs)
+    ? input.previous_outputs.map(outputRecord).filter((item): item is Record<string, unknown> => Boolean(item))
+    : [];
+}
+
+function stepOutput(entry: Record<string, unknown> | undefined): unknown {
+  return outputRecord(entry)?.output ?? entry;
+}
+
+function extractHtml(value: unknown): string | undefined {
+  if (typeof value === "string" && /<html|<!doctype|<body|<section|<main/i.test(value)) return value;
+  const record = outputRecord(value);
+  if (!record) return undefined;
+  const direct = record.html;
+  if (typeof direct === "string" && direct.trim()) return direct;
+  const output = record.output;
+  if (typeof output === "string" && /<html|<!doctype|<body|<section|<main/i.test(output)) return output;
+  const nested = outputRecord(output);
+  return typeof nested?.html === "string" && nested.html.trim() ? nested.html : undefined;
+}
+
+function launchLandingInput(baseInput: Record<string, unknown>, step: StepLike): PlaybookStepInputResult {
+  const brief = asString(baseInput.brief) ?? asString(baseInput.context) ?? asString(baseInput.product);
+  if (!brief) {
+    return {
+      status: "blocked",
+      code: "PLAYBOOK_INPUT_MISSING_BRIEF",
+      message: "launch-landing requires a brief before any child agent is called.",
+    };
+  }
+
+  if (step.agent_slug === "marketing-copy-council") {
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: {
+        brief,
+        context: {
+          product_slug: asString(baseInput.product_slug),
+        },
+        num_outputs: 1,
+      },
+    };
+  }
+
+  const outputs = previousOutputs(baseInput);
+  if (step.agent_slug === "write-landing-page-copy") {
+    const council = outputs.find((item) => item.step === "council" || item.step === "marketing-copy-council") ?? outputs.at(-1);
+    const product = asString(baseInput.product)
+      ?? asString(baseInput.product_name)
+      ?? asString(baseInput.product_slug)
+      ?? "Landing page";
+
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: {
+        product,
+        audience: asString(baseInput.audience) ?? "builders and operators",
+        tone: asString(baseInput.tone) ?? "confident and practical",
+        context: JSON.stringify({
+          brief,
+          product_slug: asString(baseInput.product_slug),
+          council_output: stepOutput(council),
+        }),
+      },
+    };
+  }
+
+  if (step.agent_slug === "publish-html-to-a-public-url") {
+    const writer = outputs.find((item) => item.step === "structure" || item.step === "write-landing-page-copy") ?? outputs.at(-1);
+    const html = extractHtml(stepOutput(writer)) ?? extractHtml(writer);
+    if (!html) {
+      return {
+        status: "blocked",
+        code: "PLAYBOOK_INPUT_MISSING_HTML",
+        message: "launch-landing publish step requires generated HTML from the writer step.",
+      };
+    }
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: {
+        html,
+        slug: asString(baseInput.product_slug) ?? asString(baseInput.slug),
+        title: asString(baseInput.title) ?? asString(baseInput.product) ?? asString(baseInput.product_slug),
+      },
+    };
+  }
+
+  return {
+    status: "blocked",
+    code: "PLAYBOOK_STEP_NOT_CERTIFIED",
+    message: `launch-landing step ${step.id} (${step.agent_slug ?? "unknown"}) has no explicit adapter.`,
+  };
+}
+
+function ipoBriefInput(baseInput: Record<string, unknown>, step: StepLike): PlaybookStepInputResult {
+  const ticker = asString(baseInput.ticker) ?? asString(baseInput.symbol);
+  if (!ticker) {
+    return {
+      status: "blocked",
+      code: "PLAYBOOK_INPUT_MISSING_TICKER",
+      message: "ipo-brief requires ticker before any child agent is called.",
+    };
+  }
+
+  if (step.agent_slug === "ipo-s-1-analysis") {
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: { ticker },
+    };
+  }
+  if (step.agent_slug === "insider-trading-tracker") {
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: {
+        ticker,
+        days_back: Number(baseInput.days_back ?? 365),
+      },
+    };
+  }
+  if (step.agent_slug === "stock-comparison") {
+    const peers = Array.isArray(baseInput.peer_tickers) ? baseInput.peer_tickers : [];
+    const tickers = [ticker, ...peers].filter((item): item is string => typeof item === "string" && Boolean(item.trim())).slice(0, 5);
+    return {
+      status: "ready",
+      certification: "explicit",
+      input: { tickers },
+    };
+  }
+
+  return {
+    status: "blocked",
+    code: "PLAYBOOK_STEP_NOT_CERTIFIED",
+    message: `ipo-brief step ${step.id} (${step.agent_slug ?? "unknown"}) has no explicit adapter.`,
+  };
+}
+
+export function playbookRunBlocker(slug: string): string | null {
+  return BLOCKED_PLAYBOOKS[slug] ?? null;
+}
+
+export function buildExplicitPlaybookStepInput(
+  playbookSlug: string,
+  baseInput: Record<string, unknown>,
+  step: StepLike,
+): PlaybookStepInputResult | null {
+  const blocker = playbookRunBlocker(playbookSlug);
+  if (blocker) {
+    return {
+      status: "blocked",
+      code: "PLAYBOOK_NOT_CERTIFIED",
+      message: blocker,
+    };
+  }
+
+  if (playbookSlug === "launch-landing") return launchLandingInput(baseInput, step);
+  if (playbookSlug === "ipo-brief") return ipoBriefInput(baseInput, step);
+  return null;
+}

package/src/tools/playbooks.ts

@@ -15,6 +15,7 @@ import {
   formatPaymentLabel,
   resolveConfirmationMethod,
 } from "./_payment-confirmation.js";
+import { buildExplicitPlaybookStepInput, playbookRunBlocker } from "./playbook-adapters.js";
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_MAX_MS = 300000;
@@ -163,14 +164,13 @@ function fanoutControls(playbook: PlaybookRecord): PlaybookFanoutControl[] {
 
 function buildPlaybookLinkApprovalContext(params: {
   playbook: PlaybookRecord;
-  budget: number;
-  stepCount: number;
   runId: string;
+  step: PlaybookStepQuote;
 }): string {
   return [
-    `Approve up to ${money(params.budget)} for the Agent Wonderland "${params.playbook.name}" playbook.`,
-    `This playbook run ${params.runId} has ${params.stepCount} child-agent steps and will stop before exceeding the approved budget.`,
-    "Each child agent is still charged at its exact quoted price, unused budget is not spent, and failed child runs keep the existing Agent Wonderland refund behavior.",
+    `Approve ${money(params.step.quoted_cost_usd)} for step ${params.step.index + 1} of the Agent Wonderland "${params.playbook.name}" playbook.`,
+    `Run ${params.runId}, step ${params.step.id}: ${params.step.agent_name}.`,
+    "Each child agent is approved separately, and failed child runs keep the existing Agent Wonderland refund behavior.",
   ].join(" ");
 }
 
@@ -374,7 +374,15 @@ async function formatCheaperAlternatives(currentSlug: string, budget: number): P
   }
 }
 
-function stepInput(baseInput: Record<string, unknown>, step: PlaybookStepQuote, iteration: number): Record<string, unknown> {
+function stepInput(playbookSlug: string, baseInput: Record<string, unknown>, step: PlaybookStepQuote, iteration: number): Record<string, unknown> {
+  const explicit = buildExplicitPlaybookStepInput(playbookSlug, baseInput, step);
+  if (explicit?.status === "ready") return explicit.input;
+  if (explicit?.status === "blocked") {
+    const error = new Error(explicit.message) as Error & { code?: string };
+    error.code = explicit.code;
+    throw error;
+  }
+
   const input: Record<string, unknown> = { ...(step.default_input ?? {}), ...baseInput };
   const itemIndex = Math.max(0, (step.iteration ?? 1) - 1);
 
@@ -778,6 +786,10 @@ export function registerPlaybookTools(server: McpServer): void {
       if (playbook.current_quote.blocking_issues.length > 0) {
         return text(`Cannot run ${playbook.slug}; child-agent issues must be fixed first:\n${playbook.current_quote.blocking_issues.map((issue) => `- ${issue}`).join("\n")}`);
       }
+      const blocker = playbookRunBlocker(playbook.slug);
+      if (blocker) {
+        return text(`Playbook ${playbook.slug} is temporarily paused for certification.\n\n${blocker}`);
+      }
 
       const runLimits = appliedPlaybookLimits(playbook) ?? effectiveLimits;
       const estimatedCost = playbook.current_quote.estimated_cost_usd;
@@ -880,14 +892,7 @@ export function registerPlaybookTools(server: McpServer): void {
 
       let charged = runState.chargedUsd;
       const childOutputs: Array<{ step: string; job_id?: string; output?: unknown }> = [...runState.existingOutputs];
-      let linkSpendRequestId: string | undefined;
       let linkNetworkId: string | undefined;
-      const linkApprovalContext = buildPlaybookLinkApprovalContext({
-        playbook,
-        budget: effectiveBudget,
-        stepCount: playbook.current_quote.step_count,
-        runId: runState.run_id,
-      });
 
       for (const [iteration, step] of runState.steps.entries()) {
         if (runState.completedStepIds.has(step.id)) {
@@ -927,7 +932,27 @@ export function registerPlaybookTools(server: McpServer): void {
           quoted_cost_usd: step.quoted_cost_usd,
         });
 
-        const payload = stepInput({ ...processedInput, previous_outputs: childOutputs }, step, iteration);
+        let payload: Record<string, unknown>;
+        try {
+          payload = stepInput(playbook.slug, { ...processedInput, previous_outputs: childOutputs }, step, iteration);
+        } catch (err) {
+          const blocked = err as Error & { code?: string };
+          await recordStep(runState.run_id, step.id, {
+            status: "skipped",
+            agent_id: step.agent_id,
+            provider_id: step.provider_id,
+            consumption_mode: "not_charged",
+            error_code: blocked.code ?? "PLAYBOOK_STEP_INPUT_BLOCKED",
+            failure_message: blocked.message,
+          });
+          await updateRun(runState.run_id, {
+            status: "paused",
+            error_code: blocked.code ?? "PLAYBOOK_STEP_INPUT_BLOCKED",
+            failure_message: blocked.message,
+          });
+          const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+          return text(`${formatReceipt(receipt)}\n\n${blocked.message}`);
+        }
         const playbookContext = {
           playbook_run_id: runState.run_id,
           playbook_id: playbook.id,
@@ -938,6 +963,7 @@ export function registerPlaybookTools(server: McpServer): void {
         let result: Record<string, unknown> | undefined;
         let schemaError: { status?: number; message?: string } | undefined;
         let usedPaidMethod = false;
+        let stepLinkSpendRequestId: string | undefined;
         const executeChild = async (childInput: Record<string, unknown>) => {
           const body = { input: childInput, playbook_context: playbookContext };
           try {
@@ -960,10 +986,14 @@ export function registerPlaybookTools(server: McpServer): void {
                 throw new Error("Link payment challenge did not include a WWW-Authenticate header.");
               }
               linkNetworkId = linkNetworkId ?? await decodeMppNetworkId(challenge!);
-              linkSpendRequestId = linkSpendRequestId ?? await ensureApprovedLinkSpendRequest({
-                amount: cents(effectiveBudget),
+              stepLinkSpendRequestId = await ensureApprovedLinkSpendRequest({
+                amount: cents(step.quoted_cost_usd),
                 currency: "usd",
-                context: linkApprovalContext,
+                context: buildPlaybookLinkApprovalContext({
+                  playbook,
+                  runId: runState.run_id,
+                  step,
+                }),
                 expiresAt: Math.floor(Date.now() / 1000) + 3600,
                 networkId: linkNetworkId,
                 paymentMethodId: linkConfig.paymentMethodId,
@@ -971,7 +1001,7 @@ export function registerPlaybookTools(server: McpServer): void {
               return await apiPostWithApprovedLinkSpendRequest<Record<string, unknown>>(
                 `/agents/${step.agent_id}/run`,
                 body,
-                linkSpendRequestId,
+                stepLinkSpendRequestId,
               );
             }
             return await apiPostWithPayment<Record<string, unknown>>(
@@ -1023,6 +1053,9 @@ export function registerPlaybookTools(server: McpServer): void {
             }
           } else {
             const errorCode = apiErr?.status === 402 ? "PAYMENT_REJECTED" : "CHILD_AGENT_FAILED";
+            if ((method ?? spendMethod) === "link" && stepLinkSpendRequestId) {
+              setPendingLinkSpendRequest(null);
+            }
             await recordStep(runState.run_id, step.id, {
               status: apiErr?.status === 402 ? "skipped" : "failed",
               agent_id: step.agent_id,
@@ -1044,6 +1077,10 @@ export function registerPlaybookTools(server: McpServer): void {
           }
         }
 
+        if (result && (method ?? spendMethod) === "link" && stepLinkSpendRequestId) {
+          setPendingLinkSpendRequest(null);
+        }
+
         if (!result) {
           await recordStep(runState.run_id, step.id, {
             status: "skipped",
@@ -1172,9 +1209,6 @@ export function registerPlaybookTools(server: McpServer): void {
       });
       const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
       pendingPlaybookRuns.delete(playbook.slug);
-      if ((method ?? spendMethod) === "link" && linkSpendRequestId) {
-        setPendingLinkSpendRequest(null);
-      }
 
       const runBlocks = childOutputs.length > 0
         ? childOutputs.map((item) => item.output ? formatRunResult({ status: "success", job_id: item.job_id, output: item.output }, { paymentMethod: method }) : "").filter(Boolean)