@agentwonderland/mcp 0.1.53 → 0.1.54

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

@@ -0,0 +1,2043 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const mockApiGet = vi.fn();
+const mockApiPost = vi.fn();
+const mockApiPostWithPayment = vi.fn();
+const mockUploadLocalFiles = vi.fn();
+const mockHasWalletConfigured = vi.fn();
+const mockGetConfiguredMethods = vi.fn();
+const mockGetWalletAddress = vi.fn();
+const mockRequiresSpendConfirmation = vi.fn();
+const mockCanSpend = vi.fn();
+const mockRecordSpend = vi.fn();
+const mockRequiresPolicyConfirmation = vi.fn();
+const mockStoreFeedbackToken = vi.fn();
+vi.mock("../../core/api-client.js", () => ({
+    apiGet: mockApiGet,
+    apiPost: mockApiPost,
+    apiPostWithPayment: mockApiPostWithPayment,
+}));
+vi.mock("../../core/file-upload.js", () => ({
+    uploadLocalFiles: mockUploadLocalFiles,
+}));
+vi.mock("../../core/payments.js", () => ({
+    hasWalletConfigured: mockHasWalletConfigured,
+    getConfiguredMethods: mockGetConfiguredMethods,
+    getWalletAddress: mockGetWalletAddress,
+}));
+vi.mock("../../core/config.js", () => ({
+    requiresSpendConfirmation: mockRequiresSpendConfirmation,
+}));
+vi.mock("../../core/spend-policy.js", () => ({
+    canSpend: mockCanSpend,
+    recordSpend: mockRecordSpend,
+    requiresPolicyConfirmation: mockRequiresPolicyConfirmation,
+}));
+vi.mock("../_token-cache.js", () => ({
+    storeFeedbackToken: mockStoreFeedbackToken,
+}));
+function flattenToolText(result) {
+    const content = result?.content ?? [];
+    return content
+        .filter((item) => item?.type === "text")
+        .map((item) => item.text ?? "")
+        .join("\n\n");
+}
+function makeServerHarness() {
+    const handlers = new Map();
+    return {
+        handlers,
+        server: {
+            tool(name, _description, _schema, handler) {
+                handlers.set(name, handler);
+            },
+        },
+    };
+}
+const playbook = {
+    id: "pb_competitor_ads_v1",
+    slug: "competitor-ads",
+    version: 1,
+    name: "Competitor Ads",
+    persona: "gtm",
+    tags: ["gtm"],
+    description: "Competitor ad workflow",
+    outcome: "Ad intel",
+    support_status: "supported",
+    input_schema: {
+        type: "object",
+        properties: { domain: { type: "string", description: "Competitor domain" } },
+        required: ["domain"],
+    },
+    sample_input: { domain: "notion.so" },
+    budget_notes: ["Low fanout"],
+    risks: [],
+    stats: {
+        favorite_count: 3,
+        rating_count: 2,
+        average_rating: 4.5,
+    },
+    current_quote: {
+        estimated_cost_usd: 1.25,
+        step_count: 1,
+        blocking_issues: [],
+        steps: [
+            {
+                id: "ads",
+                index: 0,
+                node_type: "aw_agent",
+                agent_slug: "ad-strategy-intel",
+                agent_id: "11111111-1111-4111-8111-111111111111",
+                provider_id: null,
+                agent_name: "AdStrategyIntel",
+                description: "Ad intelligence",
+                quantity: 1,
+                unit_price_usd: 1.25,
+                quoted_cost_usd: 1.25,
+                support_status: "ready",
+            },
+        ],
+    },
+};
+describe("playbook MCP tools", () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+        mockHasWalletConfigured.mockReturnValue(true);
+        mockGetConfiguredMethods.mockReturnValue(["card"]);
+        mockGetWalletAddress.mockResolvedValue("0xabc");
+        mockRequiresSpendConfirmation.mockReturnValue(true);
+        mockRequiresPolicyConfirmation.mockReturnValue(false);
+        mockCanSpend.mockReturnValue({ ok: true, message: "" });
+        mockUploadLocalFiles.mockResolvedValue({ input: { domain: "notion.so" }, uploads: [] });
+    });
+    it("searches playbooks through the gateway", async () => {
+        mockApiGet.mockResolvedValueOnce({ playbooks: [playbook] });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("search_playbooks")({ query: "competitor ads", limit: 5 });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks?q=competitor+ads&limit=5");
+        expect(text).toContain("Competitor Ads (competitor-ads)");
+        expect(text).toContain("Favorites: 3");
+        expect(text).toContain("Rating: 4.5/5 (2)");
+        expect(text).toContain("get_playbook");
+    });
+    it("passes playbook search filters and sorting to the gateway", async () => {
+        mockApiGet.mockResolvedValueOnce({ playbooks: [playbook] });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        await harness.handlers.get("search_playbooks")({
+            query: "lead gen",
+            persona: "gtm",
+            tag: "prospecting",
+            max_budget: 5,
+            sort: "popularity",
+            limit: 3,
+        });
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks?q=lead+gen&persona=gtm&tag=prospecting&limit=3&max_budget=5&sort=popularity");
+    });
+    it("returns a useful search empty state", async () => {
+        mockApiGet.mockResolvedValueOnce({ playbooks: [] });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("search_playbooks")({ query: "quantum waffles", limit: 5 });
+        const text = flattenToolText(result);
+        expect(text).toContain('No playbooks found matching "quantum waffles"');
+        expect(text).toContain('search_playbooks({ persona: "gtm" })');
+        expect(text).toContain('search_playbooks({ tag: "research" })');
+    });
+    it("labels catalog-only playbooks clearly in search results", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            playbooks: [{
+                    ...playbook,
+                    slug: "trend-radar",
+                    name: "Trend Radar",
+                    support_status: "catalog_only",
+                    support_note: "Best as a future scheduling demo.",
+                }],
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("search_playbooks")({ query: "trend", limit: 5 });
+        const text = flattenToolText(result);
+        expect(text).toContain("Trend Radar (trend-radar)");
+        expect(text).toContain("catalog-only: Best as a future scheduling demo.");
+    });
+    it("gets a playbook with live quote, graph, risks, and run suggestion", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            ...playbook,
+            budget_notes: ["Low fanout", "Stops before exceeding the approved budget cap."],
+            risks: ["SERP step may need a derived query."],
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("get_playbook")({ slug: "competitor-ads" });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks/competitor-ads");
+        expect(text).toContain("Competitor Ads (competitor-ads)");
+        expect(text).toContain("Support: supported");
+        expect(text).toContain("Estimated cost: $1.25 across 1 paid step");
+        expect(text).toContain("Inputs:");
+        expect(text).toContain("domain: string (required)");
+        expect(text).toContain("Execution plan:");
+        expect(text).toContain("1. AdStrategyIntel (ad-strategy-intel) — $1.25");
+        expect(text).toContain("Budget notes:");
+        expect(text).toContain("Stops before exceeding the approved budget cap.");
+        expect(text).toContain("Risks:");
+        expect(text).toContain("SERP step may need a derived query.");
+        expect(text).toContain("Sample input:");
+        expect(text).toContain('Run quote: run_playbook({ slug: "competitor-ads"');
+    });
+    it("shows blocking child-agent issues in get_playbook output", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            ...playbook,
+            current_quote: {
+                ...playbook.current_quote,
+                blocking_issues: ["Inactive child agent: ad-strategy-intel"],
+                steps: [{
+                        ...playbook.current_quote.steps[0],
+                        support_status: "blocking",
+                        agent_id: null,
+                    }],
+            },
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("get_playbook")({ playbook_id: "pb_competitor_ads_v1" });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks/pb_competitor_ads_v1");
+        expect(text).toContain("Blocking issues: Inactive child agent: ad-strategy-intel");
+        expect(text).toContain("[blocking]");
+    });
+    it("favorites a playbook with consumer principal headers", async () => {
+        mockApiPost.mockResolvedValueOnce({
+            ok: true,
+            favorite_id: "favorite-row-1",
+            playbook_slug: "competitor-ads",
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("favorite_playbook")({ slug: "competitor-ads" });
+        const text = flattenToolText(result);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbooks/competitor-ads/favorite", {}, { ensureConsumerPrincipal: true });
+        expect(text).toContain("Saved competitor-ads to favorites");
+    });
+    it("records playbook feedback with consumer principal headers", async () => {
+        mockApiPost.mockResolvedValueOnce({
+            ok: true,
+            feedback_id: "feedback-row-1",
+            playbook_slug: "competitor-ads",
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("rate_playbook")({
+            slug: "competitor-ads",
+            run_id: "22222222-2222-4222-8222-222222222222",
+            rating: 5,
+            useful: true,
+            comment: "Useful.",
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbooks/competitor-ads/feedback", {
+            run_id: "22222222-2222-4222-8222-222222222222",
+            rating: 5,
+            useful: true,
+            comment: "Useful.",
+        }, { ensureConsumerPrincipal: true });
+        expect(text).toContain("Recorded feedback for competitor-ads");
+    });
+    it("validates favorite and feedback inputs before calling the gateway", async () => {
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const favoriteResult = await harness.handlers.get("favorite_playbook")({});
+        const emptyFeedbackResult = await harness.handlers.get("rate_playbook")({ slug: "competitor-ads" });
+        const missingIdFeedbackResult = await harness.handlers.get("rate_playbook")({ rating: 5 });
+        expect(flattenToolText(favoriteResult)).toContain("Provide slug or playbook_id.");
+        expect(flattenToolText(emptyFeedbackResult)).toContain("Provide rating, useful, or comment.");
+        expect(flattenToolText(missingIdFeedbackResult)).toContain("Provide slug or playbook_id.");
+        expect(mockApiPost).not.toHaveBeenCalled();
+    });
+    it("quotes before confirmed execution", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            ...playbook,
+            risks: ["SERP step may need a derived query."],
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+        });
+        const text = flattenToolText(result);
+        expect(text).toContain("Ready to run Competitor Ads");
+        expect(text).toContain("Budget and fanout notes:");
+        expect(text).toContain("Low fanout");
+        expect(text).toContain("Risks and limitations:");
+        expect(text).toContain("SERP step may need a derived query.");
+        expect(text).toContain('run_playbook({ slug: "competitor-ads", input: <same>, budget: 5, pay_with: "card", confirmed: true })');
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("keeps reduced fanout limits in the confirmation command", async () => {
+        mockApiGet.mockResolvedValueOnce(playbook);
+        mockApiPost.mockResolvedValueOnce({
+            playbook,
+            budget_usd: 5,
+            budget_sufficient: true,
+            remaining_budget_usd: 3.75,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            limits: { prospects: 2 },
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-quotes", expect.objectContaining({
+            limits: { prospects: 2 },
+        }));
+        expect(text).toContain('run_playbook({ slug: "competitor-ads", input: <same>, budget: 5, limits: {"prospects":2}, pay_with: "card", confirmed: true })');
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("returns the first quote before wallet setup is complete", async () => {
+        mockHasWalletConfigured.mockReturnValue(false);
+        mockApiGet.mockResolvedValueOnce(playbook);
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "tempo",
+        });
+        const text = flattenToolText(result);
+        expect(text).toContain("Ready to run Competitor Ads");
+        expect(text).toContain("Estimated child-agent charges: $1.25");
+        expect(text).toContain('run_playbook({ slug: "competitor-ads", input: <same>, budget: 5, pay_with: "tempo", confirmed: true })');
+        expect(text).not.toContain("No payment method configured");
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs", expect.anything());
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("requires a configured wallet before confirmed playbook execution", async () => {
+        mockHasWalletConfigured.mockReturnValue(false);
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet.mockResolvedValueOnce(playbook);
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "tempo",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(text).toContain("No payment method configured");
+        expect(text).toContain('wallet_setup({ action: "start" })');
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs", expect.anything());
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("quotes the direct IPO brief run before any paid execution", async () => {
+        const ipoBrief = {
+            ...playbook,
+            id: "pb_ipo_brief_v1",
+            slug: "ipo-brief",
+            name: "IPO Brief",
+            persona: "investor",
+            input_schema: {
+                type: "object",
+                properties: { ticker: { type: "string", description: "IPO ticker" } },
+                required: ["ticker"],
+            },
+            sample_input: { ticker: "CRCL" },
+            current_quote: {
+                ...playbook.current_quote,
+                estimated_cost_usd: 2.5,
+                step_count: 3,
+            },
+        };
+        mockApiGet.mockResolvedValueOnce(ipoBrief);
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "ipo-brief",
+            input: { ticker: "CRCL" },
+            budget: 3,
+            pay_with: "card",
+        });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks/ipo-brief");
+        expect(text).toContain("Ready to run IPO Brief");
+        expect(text).toContain("Estimated child-agent charges: $2.50");
+        expect(text).toContain('run_playbook({ slug: "ipo-brief", input: <same>, budget: 3, pay_with: "card", confirmed: true })');
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs", expect.anything());
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("returns no paid execution when the budget is below the live quote", async () => {
+        const cheaperPlaybook = {
+            ...playbook,
+            id: "pb_quick_ads_v1",
+            slug: "quick-ads-check",
+            name: "Quick Ads Check",
+            current_quote: {
+                ...playbook.current_quote,
+                estimated_cost_usd: 0.25,
+                step_count: 1,
+                blocking_issues: [],
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({ playbooks: [cheaperPlaybook] });
+        mockApiPost.mockResolvedValueOnce({
+            playbook,
+            budget_usd: 0.5,
+            budget_sufficient: false,
+            remaining_budget_usd: 0,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 0.5,
+            pay_with: "card",
+        });
+        const text = flattenToolText(result);
+        expect(text).toContain("quote exceeds the budget");
+        expect(text).toContain("Estimated cost: $1.25");
+        expect(text).toContain("Cheaper supported alternatives under this budget");
+        expect(text).toContain("Quick Ads Check (quick-ads-check) — $0.2500 est.");
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-quotes", expect.objectContaining({
+            slug: "competitor-ads",
+            budget: 0.5,
+        }));
+        expect(mockApiGet).toHaveBeenCalledWith("/playbooks?max_budget=0.5&limit=4&sort=price");
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs", expect.anything());
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+    });
+    it("creates a run, executes child agent, records step receipt, and completes", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                },
+            ],
+        });
+        mockApiPost
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            steps: playbook.current_quote.steps,
+        })
+            .mockResolvedValueOnce({ ok: true })
+            .mockRejectedValueOnce(new Error("temporary receipt write failure"))
+            .mockResolvedValueOnce({ ok: true })
+            .mockRejectedValueOnce({ status: 402, message: "payment required" })
+            .mockResolvedValueOnce({ ok: true })
+            .mockResolvedValueOnce({ ok: true });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { rows: 3 },
+            cost: 1.25,
+            feedback_token: "token",
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs", expect.objectContaining({
+            slug: "competitor-ads",
+            budget: 5,
+        }));
+        expect(mockApiPostWithPayment).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            input: expect.objectContaining({
+                startUrls: [{
+                        url: "https://notion.so",
+                    }],
+                maxAds: 1,
+            }),
+            playbook_context: {
+                playbook_run_id: "22222222-2222-4222-8222-222222222222",
+                playbook_id: "pb_competitor_ads_v1",
+                playbook_slug: "competitor-ads",
+                playbook_step_id: "ads",
+                playbook_step_index: 0,
+            },
+        }), "card");
+        expect(mockRecordSpend).toHaveBeenCalledWith("card", 1.25);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "succeeded",
+            error_code: null,
+            failure_message: null,
+        }));
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/status", expect.objectContaining({
+            status: "completed",
+            error_code: null,
+            failure_message: null,
+        }));
+        expect(mockStoreFeedbackToken).toHaveBeenCalledWith("33333333-3333-4333-8333-333333333333", "token", "11111111-1111-4111-8111-111111111111");
+        expect(text).toContain("Playbook run 22222222-2222-4222-8222-222222222222");
+        expect(text).toContain("Charged: $1.25");
+        expect(text).toContain("Was this playbook useful?");
+        expect(text).toContain("favorite_playbook({ slug: \"competitor-ads\" })");
+        expect(text).toContain("rate_playbook({ slug: \"competitor-ads\", run_id: \"22222222-2222-4222-8222-222222222222\"");
+    });
+    it("uploads local file inputs before run creation and child execution", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockUploadLocalFiles.mockResolvedValueOnce({
+            input: { domain: "https://files.example/notion.txt" },
+            uploads: [{
+                    field: "domain",
+                    originalPath: "/tmp/notion.txt",
+                    url: "https://files.example/notion.txt",
+                }],
+        });
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return {
+                    run_id: "22222222-2222-4222-8222-222222222222",
+                    steps: playbook.current_quote.steps,
+                };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { rows: 3 },
+            cost: 1.25,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "/tmp/notion.txt" },
+            budget: 5,
+            pay_with: "base",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockUploadLocalFiles).toHaveBeenCalledWith({ domain: "/tmp/notion.txt" });
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs", expect.objectContaining({
+            input: { domain: "https://files.example/notion.txt" },
+        }));
+        expect(mockApiPostWithPayment).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            input: expect.objectContaining({
+                domain: "https://files.example/notion.txt",
+            }),
+        }), "base");
+        expect(text).toContain("Uploaded domain: /tmp/notion.txt -> https://files.example/notion.txt");
+    });
+    it("records credit-pack child consumption distinctly from direct charges", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 0,
+            refunded_usd: 0,
+            remaining_budget_usd: 5,
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    consumption_mode: "credit_pack",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                },
+            ],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return {
+                    run_id: "22222222-2222-4222-8222-222222222222",
+                    steps: playbook.current_quote.steps,
+                };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    output: { rows: 3 },
+                    cost: 1.25,
+                    consumption_mode: "credit_pack",
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+        expect(mockRecordSpend).not.toHaveBeenCalled();
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "succeeded",
+            consumption_mode: "credit_pack",
+            charged_usd: 0,
+        }));
+        expect(text).toContain("Charged: $0.00");
+        expect(text).toContain("credit pack");
+    });
+    it("URL-encodes fanout step ids when recording receipts", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        const fanoutPlaybook = {
+            ...playbook,
+            current_quote: {
+                ...playbook.current_quote,
+                steps: [{
+                        ...playbook.current_quote.steps[0],
+                        id: "people:1",
+                    }],
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(fanoutPlaybook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "people:1",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    consumption_mode: "direct_charge",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return {
+                    run_id: "22222222-2222-4222-8222-222222222222",
+                    steps: fanoutPlaybook.current_quote.steps,
+                };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    output: { rows: 3 },
+                    cost: 1.25,
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "base",
+            confirmed: true,
+        });
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/people%3A1", expect.objectContaining({ status: "running" }));
+        expect(mockApiPost).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            playbook_context: expect.objectContaining({ playbook_step_id: "people:1" }),
+        }), expect.objectContaining({ ensureConsumerPrincipal: true }));
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/people%3A1", expect.objectContaining({ status: "succeeded" }));
+    });
+    it("resumes an existing run without creating a new run or rerunning completed steps", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        const twoStepPlaybook = {
+            ...playbook,
+            current_quote: {
+                ...playbook.current_quote,
+                estimated_cost_usd: 2,
+                step_count: 2,
+                steps: [
+                    playbook.current_quote.steps[0],
+                    {
+                        ...playbook.current_quote.steps[0],
+                        id: "traffic",
+                        index: 1,
+                        agent_slug: "traffic-estimator",
+                        agent_id: "44444444-4444-4444-8444-444444444444",
+                        agent_name: "Traffic Estimator",
+                        quoted_cost_usd: 0.75,
+                        unit_price_usd: 0.75,
+                    },
+                ],
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            input: { domain: "notion.so" },
+            budget_usd: 5,
+            quoted_cost_usd: 2,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                    output: { ads: 3 },
+                },
+                {
+                    playbook_step_id: "traffic",
+                    step_index: 1,
+                    node_type: "aw_agent",
+                    agent_slug: "traffic-estimator",
+                    agent_id: "44444444-4444-4444-8444-444444444444",
+                    provider_id: null,
+                    job_id: null,
+                    status: "pending",
+                    quoted_cost_usd: 0.75,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                },
+            ],
+        })
+            .mockResolvedValueOnce(twoStepPlaybook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 2,
+            charged_usd: 2,
+            refunded_usd: 0,
+            remaining_budget_usd: 3,
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                },
+                {
+                    playbook_step_id: "traffic",
+                    step_index: 1,
+                    node_type: "aw_agent",
+                    agent_slug: "traffic-estimator",
+                    agent_id: "44444444-4444-4444-8444-444444444444",
+                    provider_id: null,
+                    job_id: "55555555-5555-4555-8555-555555555555",
+                    status: "succeeded",
+                    quoted_cost_usd: 0.75,
+                    charged_usd: 0.75,
+                    refunded_usd: 0,
+                },
+            ],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                throw new Error("resume should not create a new run");
+            }
+            if (path === "/agents/44444444-4444-4444-8444-444444444444/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "55555555-5555-4555-8555-555555555555",
+            agent_id: "44444444-4444-4444-8444-444444444444",
+            output: { traffic: "ok" },
+            cost: 0.75,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            resume_run_id: "22222222-2222-4222-8222-222222222222",
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs", expect.anything());
+        expect(mockApiPost).not.toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.anything(), expect.anything());
+        expect(mockApiPostWithPayment).toHaveBeenCalledTimes(1);
+        expect(mockApiPostWithPayment).toHaveBeenCalledWith("/agents/44444444-4444-4444-8444-444444444444/run", expect.objectContaining({
+            playbook_context: expect.objectContaining({
+                playbook_run_id: "22222222-2222-4222-8222-222222222222",
+                playbook_step_id: "traffic",
+            }),
+        }), "card");
+        expect(text).toContain("completed");
+        expect(text).toContain("traffic-estimator");
+    });
+    it("uses net charged amount after refunds when enforcing resume budget", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            input: { domain: "notion.so" },
+            budget_usd: 1.25,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 1.25,
+            remaining_budget_usd: 1.25,
+            error_code: "UPSTREAM_FAILED",
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "failed",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 1.25,
+                    error_code: "UPSTREAM_FAILED",
+                }],
+        })
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 1.25,
+            quoted_cost_usd: 1.25,
+            charged_usd: 2.5,
+            refunded_usd: 1.25,
+            remaining_budget_usd: 0,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "55555555-5555-4555-8555-555555555555",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                throw new Error("resume should not create a new run");
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "55555555-5555-4555-8555-555555555555",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { retry: "ok" },
+            cost: 1.25,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            resume_run_id: "22222222-2222-4222-8222-222222222222",
+            budget: 1.25,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.anything(), "card");
+        expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "skipped",
+            error_code: "BUDGET_EXHAUSTED",
+        }));
+        expect(text).toContain("completed");
+    });
+    it("pauses without another payment when the next step would exceed the budget", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        const twoStepPlaybook = {
+            ...playbook,
+            current_quote: {
+                ...playbook.current_quote,
+                estimated_cost_usd: 2,
+                step_count: 2,
+                steps: [
+                    playbook.current_quote.steps[0],
+                    {
+                        ...playbook.current_quote.steps[0],
+                        id: "traffic",
+                        index: 1,
+                        agent_slug: "traffic-estimator",
+                        agent_id: "44444444-4444-4444-8444-444444444444",
+                        agent_name: "Traffic Estimator",
+                        quoted_cost_usd: 1,
+                        unit_price_usd: 1,
+                    },
+                ],
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(twoStepPlaybook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 2.1,
+            quoted_cost_usd: 2,
+            charged_usd: 1.5,
+            refunded_usd: 0,
+            remaining_budget_usd: 0.6,
+            error_code: "BUDGET_EXHAUSTED",
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1,
+                    charged_usd: 1.5,
+                    refunded_usd: 0,
+                },
+                {
+                    playbook_step_id: "traffic",
+                    step_index: 1,
+                    node_type: "aw_agent",
+                    agent_slug: "traffic-estimator",
+                    agent_id: "44444444-4444-4444-8444-444444444444",
+                    provider_id: null,
+                    job_id: null,
+                    status: "skipped",
+                    quoted_cost_usd: 1,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                    error_code: "BUDGET_EXHAUSTED",
+                },
+            ],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return {
+                    run_id: "22222222-2222-4222-8222-222222222222",
+                    steps: twoStepPlaybook.current_quote.steps,
+                };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { ads: 3 },
+            cost: 1.5,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 2.1,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).toHaveBeenCalledTimes(1);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/traffic", expect.objectContaining({
+            status: "skipped",
+            consumption_mode: "not_charged",
+            error_code: "BUDGET_EXHAUSTED",
+        }));
+        expect(text).toContain("BUDGET_EXHAUSTED");
+        expect(text).toContain("Resume:");
+    });
+    it("records payment rejection as an uncharged skipped step", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 0,
+            refunded_usd: 0,
+            remaining_budget_usd: 5,
+            error_code: "PAYMENT_REJECTED",
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: null,
+                    status: "skipped",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                    error_code: "PAYMENT_REJECTED",
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockRejectedValueOnce({ status: 402, message: "wallet declined" });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockRecordSpend).not.toHaveBeenCalled();
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "skipped",
+            consumption_mode: "not_charged",
+            error_code: "PAYMENT_REJECTED",
+        }));
+        expect(text).toContain("wallet_status");
+    });
+    it("records schema mismatch before payment as an uncharged skipped step", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            id: "11111111-1111-4111-8111-111111111111",
+            schema: {
+                input: {
+                    inputSchema: {
+                        type: "object",
+                        properties: { prompt: { type: "string" } },
+                        required: ["prompt"],
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 0,
+            refunded_usd: 0,
+            remaining_budget_usd: 5,
+            error_code: "SCHEMA_MISMATCH",
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: null,
+                    status: "skipped",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                    error_code: "SCHEMA_MISMATCH",
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 400, message: "validation failed: missing required field prompt" };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "skipped",
+            consumption_mode: "not_charged",
+            error_code: "SCHEMA_MISMATCH",
+        }));
+        expect(text).toContain("get_agent");
+    });
+    it("uses live child schema metadata to safely repair a field name before payment", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            id: "11111111-1111-4111-8111-111111111111",
+            schema: {
+                input: {
+                    inputSchema: {
+                        type: "object",
+                        properties: { q: { type: "string", description: "Search query" } },
+                        required: ["q"],
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        let agentRunAttempts = 0;
+        mockApiPost.mockImplementation(async (path, body) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                agentRunAttempts += 1;
+                if (agentRunAttempts === 1) {
+                    throw { status: 400, message: "validation failed: missing required field q" };
+                }
+                expect(body).toMatchObject({
+                    input: {
+                        q: "notion.so",
+                    },
+                });
+                expect(body.input).not.toHaveProperty("domain");
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    output: { repaired: true },
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111");
+        expect(agentRunAttempts).toBe(2);
+        expect(mockApiPostWithPayment).not.toHaveBeenCalled();
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "succeeded",
+            charged_usd: 1.25,
+        }));
+        expect(text).toContain("completed");
+    });
+    it("uses live child schema metadata to derive startUrls from a domain before payment", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            id: "11111111-1111-4111-8111-111111111111",
+            schema: {
+                input: {
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            startUrls: { type: "array", items: { type: "object" } },
+                            maxAds: { type: "number", default: 10 },
+                        },
+                        required: ["startUrls"],
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        let agentRunAttempts = 0;
+        mockApiPost.mockImplementation(async (path, body) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                agentRunAttempts += 1;
+                if (agentRunAttempts === 1) {
+                    throw { status: 400, message: "validation failed: missing required field startUrls; unknown field domain" };
+                }
+                expect(body).toMatchObject({
+                    input: {
+                        startUrls: [{ url: "https://notion.so" }],
+                        maxAds: 10,
+                    },
+                });
+                expect(body.input).not.toHaveProperty("domain");
+                expect(body.input).not.toHaveProperty("platforms");
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    output: { repaired: true },
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(agentRunAttempts).toBe(2);
+        expect(text).toContain("completed");
+    });
+    it("uses live child schema metadata to derive urls from a domain before payment", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            id: "11111111-1111-4111-8111-111111111111",
+            schema: {
+                input: {
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            urls: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["urls"],
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        let agentRunAttempts = 0;
+        mockApiPost.mockImplementation(async (path, body) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                agentRunAttempts += 1;
+                if (agentRunAttempts === 1) {
+                    throw { status: 400, message: "validation failed: missing required field urls; unknown field domain" };
+                }
+                expect(body).toMatchObject({
+                    input: {
+                        urls: ["https://notion.so"],
+                    },
+                });
+                expect(body.input).not.toHaveProperty("domain");
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    output: { repaired: true },
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(agentRunAttempts).toBe(2);
+        expect(text).toContain("completed");
+    });
+    it("uses live child schema metadata to coerce array fields into strings before payment", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        const playbookWithArrayDefault = {
+            ...playbook,
+            current_quote: {
+                ...playbook.current_quote,
+                steps: playbook.current_quote.steps.map((step) => ({
+                    ...step,
+                    default_input: { queries: ["notion.so alternatives", "notion.so pricing"] },
+                })),
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(playbookWithArrayDefault)
+            .mockResolvedValueOnce({
+            id: "11111111-1111-4111-8111-111111111111",
+            schema: {
+                input: {
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            queries: { type: "string" },
+                            countryCode: { type: "string", default: "us" },
+                        },
+                        required: ["queries"],
+                    },
+                },
+            },
+        })
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        let agentRunAttempts = 0;
+        mockApiPost.mockImplementation(async (path, body) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbookWithArrayDefault.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                agentRunAttempts += 1;
+                if (agentRunAttempts === 1) {
+                    throw { status: 400, message: "validation failed: queries expected string, got object" };
+                }
+                expect(body).toMatchObject({
+                    input: {
+                        queries: "notion.so alternatives; notion.so pricing",
+                        countryCode: "us",
+                    },
+                });
+                expect(body.input).not.toHaveProperty("domain");
+                return {
+                    status: "success",
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    output: { repaired: true },
+                };
+            }
+            return { ok: true };
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(agentRunAttempts).toBe(2);
+        expect(text).toContain("completed");
+    });
+    it("uses company_name for company enrichment children", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockUploadLocalFiles.mockResolvedValueOnce({ input: { leads: [{ company: "Kelvin" }] }, uploads: [] });
+        const companyPlaybook = {
+            ...playbook,
+            input_schema: {
+                type: "object",
+                properties: { leads: { type: "array" } },
+                required: ["leads"],
+            },
+            current_quote: {
+                ...playbook.current_quote,
+                steps: playbook.current_quote.steps.map((step) => ({
+                    ...step,
+                    agent_slug: "company-enrichment-deep",
+                    agent_name: "Company Enrichment",
+                })),
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(companyPlaybook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 0,
+            remaining_budget_usd: 3.75,
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "company-enrichment-deep",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: companyPlaybook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { enriched: true },
+            cost: 1.25,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { leads: [{ company: "Kelvin" }] },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).toHaveBeenCalledWith("/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            input: expect.objectContaining({
+                company: "Kelvin",
+                company_name: "Kelvin",
+            }),
+        }), "card");
+        expect(text).toContain("completed");
+    });
+    it("builds cold email council brief and email verification inputs from a lead", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockUploadLocalFiles.mockResolvedValueOnce({ input: { leads: [{ name: "Dana Ko", company: "Kelvin", email: "dana@example.com" }] }, uploads: [] });
+        const steps = [
+            {
+                ...playbook.current_quote.steps[0],
+                id: "copy",
+                index: 0,
+                agent_slug: "cold-email-council",
+                agent_name: "Cold Email Council",
+            },
+            {
+                ...playbook.current_quote.steps[0],
+                id: "verify",
+                index: 1,
+                agent_slug: "email-verification",
+                agent_name: "Email Verification",
+            },
+        ];
+        const coldPlaybook = {
+            ...playbook,
+            input_schema: {
+                type: "object",
+                properties: { leads: { type: "array" } },
+                required: ["leads"],
+            },
+            current_quote: {
+                ...playbook.current_quote,
+                estimated_cost_usd: 2.5,
+                step_count: 2,
+                steps,
+            },
+        };
+        mockApiGet
+            .mockResolvedValueOnce(coldPlaybook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "completed",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 2.5,
+            charged_usd: 2.5,
+            refunded_usd: 0,
+            remaining_budget_usd: 2.5,
+            steps: steps.map((step) => ({
+                playbook_step_id: step.id,
+                step_index: step.index,
+                node_type: "aw_agent",
+                agent_slug: step.agent_slug,
+                agent_id: "11111111-1111-4111-8111-111111111111",
+                provider_id: null,
+                job_id: `33333333-3333-4333-8333-33333333333${step.index}`,
+                status: "succeeded",
+                quoted_cost_usd: 1.25,
+                charged_usd: 1.25,
+                refunded_usd: 0,
+            })),
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment
+            .mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333330",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { email: "hello" },
+            cost: 1.25,
+        })
+            .mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333331",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { valid: true },
+            cost: 1.25,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { leads: [{ name: "Dana Ko", company: "Kelvin", email: "dana@example.com" }] },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPostWithPayment).toHaveBeenNthCalledWith(1, "/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            input: expect.objectContaining({
+                brief: expect.stringContaining("Dana Ko"),
+                context: expect.objectContaining({
+                    company: "Kelvin",
+                    email: "dana@example.com",
+                }),
+                num_outputs: 1,
+            }),
+        }), "card");
+        expect(mockApiPostWithPayment).toHaveBeenNthCalledWith(2, "/agents/11111111-1111-4111-8111-111111111111/run", expect.objectContaining({
+            input: expect.objectContaining({
+                emails: ["dana@example.com"],
+            }),
+        }), "card");
+        expect(text).toContain("completed");
+    });
+    it("marks still-processing child jobs as needs reconciliation on poll timeout", async () => {
+        vi.useFakeTimers();
+        try {
+            mockRequiresSpendConfirmation.mockReturnValue(false);
+            mockApiGet.mockImplementation(async (path) => {
+                if (path === "/playbooks/competitor-ads")
+                    return playbook;
+                if (path.startsWith("/jobs/33333333-3333-4333-8333-333333333333")) {
+                    return { status: "processing" };
+                }
+                if (path === "/playbook-runs/22222222-2222-4222-8222-222222222222") {
+                    return {
+                        run_id: "22222222-2222-4222-8222-222222222222",
+                        status: "needs_reconciliation",
+                        playbook_id: playbook.id,
+                        playbook_slug: playbook.slug,
+                        playbook_version: 1,
+                        budget_usd: 5,
+                        quoted_cost_usd: 1.25,
+                        charged_usd: 0,
+                        refunded_usd: 0,
+                        remaining_budget_usd: 5,
+                        error_code: "POLL_TIMEOUT",
+                        steps: [{
+                                playbook_step_id: "ads",
+                                step_index: 0,
+                                node_type: "aw_agent",
+                                agent_slug: "ad-strategy-intel",
+                                agent_id: "11111111-1111-4111-8111-111111111111",
+                                provider_id: null,
+                                job_id: "33333333-3333-4333-8333-333333333333",
+                                status: "running",
+                                quoted_cost_usd: 1.25,
+                                charged_usd: 0,
+                                refunded_usd: 0,
+                                error_code: "POLL_TIMEOUT",
+                            }],
+                    };
+                }
+                throw new Error(`Unexpected GET ${path}`);
+            });
+            mockApiPost.mockImplementation(async (path) => {
+                if (path === "/playbook-runs") {
+                    return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+                }
+                if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                    throw { status: 402, message: "payment required" };
+                }
+                return { ok: true };
+            });
+            mockApiPostWithPayment.mockResolvedValueOnce({
+                status: "processing",
+                job_id: "33333333-3333-4333-8333-333333333333",
+                agent_id: "11111111-1111-4111-8111-111111111111",
+            });
+            const { registerPlaybookTools } = await import("../playbooks.js");
+            const harness = makeServerHarness();
+            registerPlaybookTools(harness.server);
+            const resultPromise = harness.handlers.get("run_playbook")({
+                slug: "competitor-ads",
+                input: { domain: "notion.so" },
+                budget: 5,
+                pay_with: "card",
+                confirmed: true,
+            });
+            await vi.advanceTimersByTimeAsync(305_000);
+            const result = await resultPromise;
+            const text = flattenToolText(result);
+            expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+                status: "running",
+                job_id: "33333333-3333-4333-8333-333333333333",
+                error_code: "POLL_TIMEOUT",
+            }));
+            expect(mockApiPost).not.toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+                status: "refunded",
+            }));
+            expect(text).toContain("needs_reconciliation");
+            expect(text).toContain("still processing");
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("records child failure and explains the per-agent refund behavior", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet
+            .mockResolvedValueOnce(playbook)
+            .mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            budget_usd: 5,
+            quoted_cost_usd: 1.25,
+            charged_usd: 1.25,
+            refunded_usd: 1.25,
+            remaining_budget_usd: 5,
+            error_code: "CHILD_AGENT_FAILED",
+            steps: [{
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    status: "failed",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 1.25,
+                    error_code: "UPSTREAM_FAILED",
+                }],
+        });
+        mockApiPost.mockImplementation(async (path) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "failed",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { error: "upstream failed" },
+            error_code: "UPSTREAM_FAILED",
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads", expect.objectContaining({
+            status: "refunded",
+            consumption_mode: "direct_charge",
+            charged_usd: 1.25,
+            refunded_usd: 1.25,
+            error_code: "UPSTREAM_FAILED",
+        }));
+        expect(text).toContain("Existing per-agent refund behavior applies");
+    });
+    it("returns paid child output and marks the run for reconciliation when receipt writes keep failing", async () => {
+        mockRequiresSpendConfirmation.mockReturnValue(false);
+        mockApiGet.mockResolvedValueOnce(playbook);
+        let successfulStepReceiptAttempts = 0;
+        mockApiPost.mockImplementation(async (path, body) => {
+            if (path === "/playbook-runs") {
+                return { run_id: "22222222-2222-4222-8222-222222222222", steps: playbook.current_quote.steps };
+            }
+            if (path === "/agents/11111111-1111-4111-8111-111111111111/run") {
+                throw { status: 402, message: "payment required" };
+            }
+            if (path === "/playbook-runs/22222222-2222-4222-8222-222222222222/steps/ads" && body?.status === "succeeded") {
+                successfulStepReceiptAttempts += 1;
+                throw new Error("receipt store unavailable");
+            }
+            return { ok: true };
+        });
+        mockApiPostWithPayment.mockResolvedValueOnce({
+            status: "success",
+            job_id: "33333333-3333-4333-8333-333333333333",
+            agent_id: "11111111-1111-4111-8111-111111111111",
+            output: { rows: 3 },
+            cost: 1.25,
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("run_playbook")({
+            slug: "competitor-ads",
+            input: { domain: "notion.so" },
+            budget: 5,
+            pay_with: "card",
+            confirmed: true,
+        });
+        const text = flattenToolText(result);
+        expect(successfulStepReceiptAttempts).toBe(3);
+        expect(mockApiPost).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222/status", expect.objectContaining({
+            status: "needs_reconciliation",
+            error_code: "RECEIPT_WRITE_FAILED",
+        }));
+        expect(text).toContain("needs reconciliation");
+        expect(text).toContain("rows");
+    });
+    it("gets a paused playbook run receipt with completed, refunded, skipped, and resume details", async () => {
+        mockApiGet.mockResolvedValueOnce({
+            run_id: "22222222-2222-4222-8222-222222222222",
+            status: "paused",
+            playbook_id: playbook.id,
+            playbook_slug: playbook.slug,
+            playbook_version: 1,
+            input: { domain: "notion.so" },
+            limits: { prospects: 2 },
+            budget_usd: 5,
+            quoted_cost_usd: 3,
+            charged_usd: 2,
+            refunded_usd: 0.75,
+            remaining_budget_usd: 3.75,
+            error_code: "BUDGET_EXHAUSTED",
+            steps: [
+                {
+                    playbook_step_id: "ads",
+                    step_index: 0,
+                    node_type: "aw_agent",
+                    agent_slug: "ad-strategy-intel",
+                    agent_id: "11111111-1111-4111-8111-111111111111",
+                    provider_id: null,
+                    job_id: "33333333-3333-4333-8333-333333333333",
+                    consumption_mode: "direct_charge",
+                    status: "succeeded",
+                    quoted_cost_usd: 1.25,
+                    charged_usd: 1.25,
+                    refunded_usd: 0,
+                },
+                {
+                    playbook_step_id: "traffic",
+                    step_index: 1,
+                    node_type: "aw_agent",
+                    agent_slug: "traffic-estimator",
+                    agent_id: "44444444-4444-4444-8444-444444444444",
+                    provider_id: null,
+                    job_id: "55555555-5555-4555-8555-555555555555",
+                    consumption_mode: "direct_charge",
+                    status: "failed",
+                    quoted_cost_usd: 0.75,
+                    charged_usd: 0.75,
+                    refunded_usd: 0.75,
+                    error_code: "UPSTREAM_FAILED",
+                },
+                {
+                    playbook_step_id: "serp",
+                    step_index: 2,
+                    node_type: "external_x402",
+                    agent_slug: null,
+                    agent_id: null,
+                    provider_id: null,
+                    job_id: null,
+                    consumption_mode: "not_charged",
+                    status: "skipped",
+                    quoted_cost_usd: 1,
+                    charged_usd: 0,
+                    refunded_usd: 0,
+                    error_code: "BUDGET_EXHAUSTED",
+                },
+            ],
+        });
+        const { registerPlaybookTools } = await import("../playbooks.js");
+        const harness = makeServerHarness();
+        registerPlaybookTools(harness.server);
+        const result = await harness.handlers.get("get_playbook_run")({
+            run_id: "22222222-2222-4222-8222-222222222222",
+        });
+        const text = flattenToolText(result);
+        expect(mockApiGet).toHaveBeenCalledWith("/playbook-runs/22222222-2222-4222-8222-222222222222");
+        expect(text).toContain("competitor-ads v1 — paused");
+        expect(text).toContain("Charged: $2.00");
+        expect(text).toContain("Refunded: $0.7500");
+        expect(text).toContain("Remaining unspent budget: $3.75");
+        expect(text).toContain("ad-strategy-intel: succeeded");
+        expect(text).toContain("traffic-estimator: failed");
+        expect(text).toContain("refunded $0.7500");
+        expect(text).toContain("serp: skipped · not charged");
+        expect(text).not.toContain("null: skipped");
+        expect(text).toContain("error: BUDGET_EXHAUSTED");
+        expect(text).toContain('Resume: run_playbook({ resume_run_id: "22222222-2222-4222-8222-222222222222", confirmed: true, budget: 5, limits: {"prospects":2} })');
+    });
+});