@agentwonderland/mcp 0.1.23 → 0.1.25

package/dist/tools/__tests__/_payment-confirmation.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { formatPaymentChoicePrompt, formatRunConfirmationCommand, formatSolveConfirmationCommand, makeSolvePendingKey, resolveConfirmationMethod, } from "../_payment-confirmation.js";
+describe("payment confirmation helpers", () => {
+    it("prefers the explicit method, then pending, then configured default", () => {
+        expect(resolveConfirmationMethod("card", "tempo", ["tempo", "card"])).toBe("card");
+        expect(resolveConfirmationMethod(undefined, "card", ["tempo", "card"])).toBe("card");
+        expect(resolveConfirmationMethod(undefined, undefined, ["card", "tempo"])).toBe("card");
+    });
+    it("includes pay_with in run confirmation commands when present", () => {
+        expect(formatRunConfirmationCommand("agent_123", "card")).toContain('pay_with: "card"');
+        expect(formatRunConfirmationCommand("agent_123", undefined)).not.toContain("pay_with");
+    });
+    it("includes pay_with in solve confirmation commands when present", () => {
+        expect(formatSolveConfirmationCommand("translate", 1, "card")).toContain('pay_with: "card"');
+        expect(formatSolveConfirmationCommand("translate", 1, undefined)).not.toContain("pay_with");
+    });
+    it("uses a stable solve pending key for the same request", () => {
+        const input = { text: "hello", target_language: "es" };
+        expect(makeSolvePendingKey("translate", input, 1)).toBe(makeSolvePendingKey("translate", input, 1));
+    });
+    it("formats a payment choice prompt with explicit options", () => {
+        const prompt = formatPaymentChoicePrompt("Echo Agent", ["card", "tempo"], [
+            '  run_agent({ agent_id: "agent_123", input: <same>, pay_with: "card" })',
+            '  run_agent({ agent_id: "agent_123", input: <same>, pay_with: "tempo" })',
+        ]);
+        expect(prompt).toContain("Multiple payment methods are available for Echo Agent.");
+        expect(prompt).toContain('Available methods: "card", "tempo"');
+        expect(prompt).toContain('pay_with: "card"');
+    });
+});

package/dist/tools/_payment-confirmation.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveConfirmationMethod(requestedMethod: string | undefined, pendingMethod: string | undefined, compatibleMethods: string[]): string | undefined;
+export declare function formatPaymentLabel(method: string | undefined): string;
+export declare function formatRunConfirmationCommand(agentId: string, method: string | undefined): string;
+export declare function formatSolveConfirmationCommand(intent: string, budget: number, method: string | undefined): string;
+export declare function makeSolvePendingKey(intent: string, input: Record<string, unknown>, budget: number): string;
+export declare function formatPaymentChoicePrompt(subject: string, methods: string[], commands: string[]): string;

package/dist/tools/_payment-confirmation.js

@@ -0,0 +1,28 @@
+export function resolveConfirmationMethod(requestedMethod, pendingMethod, compatibleMethods) {
+    return requestedMethod ?? pendingMethod ?? compatibleMethods[0];
+}
+export function formatPaymentLabel(method) {
+    return method ?? "auto";
+}
+export function formatRunConfirmationCommand(agentId, method) {
+    const payWith = method ? `, pay_with: "${method}"` : "";
+    return `  run_agent({ agent_id: "${agentId}", input: <same>${payWith}, confirmed: true })`;
+}
+export function formatSolveConfirmationCommand(intent, budget, method) {
+    const payWith = method ? `, pay_with: "${method}"` : "";
+    return `  solve({ intent: "${intent}", input: <same>, budget: ${budget}${payWith}, confirmed: true })`;
+}
+export function makeSolvePendingKey(intent, input, budget) {
+    return JSON.stringify({ intent, input, budget });
+}
+export function formatPaymentChoicePrompt(subject, methods, commands) {
+    return [
+        `Multiple payment methods are available for ${subject}.`,
+        "",
+        "Ask the user which payment method they want to use, then call one of:",
+        ...commands,
+        "",
+        `Available methods: ${methods.map((method) => `"${method}"`).join(", ")}`,
+        "For fully agentic execution, include pay_with explicitly.",
+    ].join("\n");
+}

package/dist/tools/agent-info.js

@@ -13,13 +13,14 @@ export function registerAgentInfoTools(server) {
         const s = (a.stats ?? {});
         const payment = (a.payment ?? {});
         const _pricing = (payment.pricing ?? {});
+        const creditPacks = payment.credit_packs;
         const lines = [
             `${a.name}`,
             `${stars(a.avgRating ?? s.avgRating)} (${s.ratingCount ?? 0} reviews) • ${compactNumber((s.completedJobs ?? a.totalExecutions ?? 0))} jobs`,
             "",
             a.description ?? "",
             "",
-            `Pricing: ${formatPrice(a.pricePer1kTokens, a.pricingModel)}`,
+            `Pricing: ${formatPrice(a.pricePerRunUsd)}`,
             `Reliability: ${a.successRate != null ? (Number(a.successRate) * 100).toFixed(0) + "%" : "N/A"}`,
             `Avg latency: ${a.avgResponseTimeMs != null ? a.avgResponseTimeMs + "ms" : "N/A"}`,
             ...(() => {
@@ -32,6 +33,19 @@ export function registerAgentInfoTools(server) {
                 const hint = outputTypeHint(a.tags);
                 return hint ? [`Output: ${hint}`] : [];
             })(),
+            ...(() => {
+                if (!creditPacks?.packs?.length)
+                    return [];
+                const packLines = [
+                    "",
+                    `Discounted credit packs: ${creditPacks.unit_type ?? "run"}s`,
+                ];
+                for (const pack of creditPacks.packs) {
+                    packLines.push(`  ${pack.name ?? pack.key}: ${pack.included_units ?? 0} units for $${pack.price_usd ?? "0.00"}`);
+                }
+                packLines.push("  Use buy_agent_credit_pack to purchase one.");
+                return packLines;
+            })(),
         ];
         // Feedback summary (rating + tips)
         const feedbackSummary = formatFeedbackSummary(s);
@@ -86,7 +100,7 @@ export function registerAgentInfoTools(server) {
             return [
                 `  ${a.name}`,
                 `  ${stars(rating)} (${s.ratingCount ?? 0} reviews)${tipCount > 0 ? ` • ${tipCount} tips` : ""}`,
-                `  ${compactNumber(jobs)} jobs • ${formatPrice(a.pricePer1kTokens, a.pricingModel)}`,
+                `  ${compactNumber(jobs)} jobs • ${formatPrice(a.pricePerRunUsd)}`,
                 `  Success: ${a.successRate != null ? (Number(a.successRate) * 100).toFixed(0) + "%" : "N/A"}`,
                 `  ${agentWebUrl(a.id)}`,
                 "",

package/dist/tools/favorites.js

@@ -34,7 +34,7 @@ export function registerFavoriteTools(server) {
                 const agent = await apiGet(`/agents/${id}`);
                 const rating = stars(agent.avgRating);
                 const jobs = compactNumber(agent.totalExecutions);
-                const price = formatPrice(agent.pricePer1kTokens, agent.pricingModel);
+                const price = formatPrice(agent.pricePerRunUsd);
                 lines.push(`${agent.name} ${rating} ${jobs} jobs | ${price}`);
                 lines.push(`  ID: ${id}`);
                 if (agent.description)

package/dist/tools/index.d.ts

@@ -7,3 +7,4 @@ export { registerRateTools } from "./rate.js";
 export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
+export { registerPassTools } from "./passes.js";

package/dist/tools/index.js

@@ -7,3 +7,4 @@ export { registerRateTools } from "./rate.js";
 export { registerWalletTools } from "./wallet.js";
 export { registerFavoriteTools } from "./favorites.js";
 export { registerTipTools } from "./tip.js";
+export { registerPassTools } from "./passes.js";

package/dist/tools/observability.d.ts

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

package/dist/tools/observability.js

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

package/dist/tools/passes.d.ts

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

package/dist/tools/passes.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { apiGet, apiPostWithPayment } from "../core/api-client.js";
+import { formatCreditPack, formatCreditPackOffer, getCreditPackProgram, } from "../core/passes.js";
+import { getCompatiblePaymentMethods, getConfiguredMethods, hasWalletConfigured, normalizePaymentMethod, } from "../core/payments.js";
+import { requiresSpendConfirmation } from "../core/config.js";
+import { ensureConsumerPrincipal } from "../core/principal.js";
+import { getOrCreatePendingCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
+import { formatPaymentChoicePrompt, formatPaymentLabel, resolveConfirmationMethod, } from "./_payment-confirmation.js";
+const pendingCreditPackPurchases = new Map();
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+function multiText(...blocks) {
+    return { content: blocks.map((t) => ({ type: "text", text: t })) };
+}
+async function getAgent(agentId) {
+    return apiGet(`/agents/${agentId}`);
+}
+function findOffer(agent, packId) {
+    const program = getCreditPackProgram(agent);
+    const pack = program?.packs?.find((candidate) => candidate.key === packId);
+    if (!pack)
+        return null;
+    const price = Number(pack.price_usd ?? "0");
+    const units = pack.included_units ?? 0;
+    return {
+        pack_id: packId,
+        label: pack.name ?? pack.key ?? "Credit Pack",
+        included_units: units,
+        price_usd: price.toFixed(2),
+        effective_price_per_unit_usd: units > 0 ? (price / units).toFixed(6) : undefined,
+    };
+}
+export function registerPassTools(server) {
+    server.tool("buy_agent_credit_pack", "Purchase a discounted prepaid credit pack for an agent. Credit packs are agent-specific and automatically cover future runs until the included units run out.", {
+        agent_id: z.string().describe("Agent ID (UUID, slug, or name)"),
+        pack_id: z.string().optional().describe("Specific pack key to buy, like 'starter' or 'growth'. If omitted and only one pack exists, it is selected automatically."),
+        pay_with: z.string().optional().describe("Payment method — wallet ID, chain name, or 'card'. Auto-detected if omitted."),
+        confirmed: z.boolean().optional().describe("Set to true to confirm the purchase after seeing the quote."),
+    }, async ({ agent_id, pack_id, pay_with, confirmed }) => {
+        if (!hasWalletConfigured()) {
+            try {
+                const { url } = await getOrCreatePendingCardSetup();
+                return multiText(...formatCardSetupBlocks(url));
+            }
+            catch {
+                return text("No payment method configured.\n\n" +
+                    "To add a credit card: wallet_setup({ action: \"add-card\" })\n" +
+                    "To use crypto: wallet_setup({ action: \"create\" })");
+            }
+        }
+        const agent = await getAgent(agent_id);
+        const agentName = agent.name ?? agent_id;
+        const principal = await ensureConsumerPrincipal();
+        const program = getCreditPackProgram(agent);
+        const offers = (program?.packs ?? [])
+            .map((pack) => findOffer(agent, pack.key ?? ""))
+            .filter((offer) => !!offer);
+        if (offers.length === 0) {
+            return text(`${agentName} does not currently offer discounted credit packs.`);
+        }
+        const configuredMethods = getConfiguredMethods();
+        const compatibleMethods = getCompatiblePaymentMethods(agent, configuredMethods);
+        const pending = pendingCreditPackPurchases.get(agent.id);
+        const requestedMethod = pay_with ?? pending?.method;
+        const normalizedRequestedMethod = requestedMethod ? normalizePaymentMethod(requestedMethod) : null;
+        if (requestedMethod && !normalizedRequestedMethod) {
+            return text(`Payment method "${requestedMethod}" is not configured.\n\n` +
+                "Use wallet_status to review your current payment methods.");
+        }
+        if (normalizedRequestedMethod && !compatibleMethods.includes(normalizedRequestedMethod)) {
+            return text(`This agent cannot be paid with "${requestedMethod}".\n\n` +
+                `Available payment methods for this agent: ${compatibleMethods.join(", ") || "none"}.`);
+        }
+        if (!requestedMethod && compatibleMethods.length === 0) {
+            return text(`No compatible payment methods are configured for ${agentName}.\n\n` +
+                `Your configured methods: ${configuredMethods.join(", ") || "none"}`);
+        }
+        if (!requestedMethod && compatibleMethods.length > 1) {
+            return text(formatPaymentChoicePrompt(`${agentName} credit-pack purchase`, compatibleMethods, compatibleMethods.map((method) => `  buy_agent_credit_pack({ agent_id: "${agent.id}"${pack_id ? `, pack_id: "${pack_id}"` : ""}, pay_with: "${method}" })`)));
+        }
+        let resolvedOffer;
+        if (pack_id) {
+            const offer = offers.find((candidate) => candidate.pack_id === pack_id);
+            if (!offer) {
+                return text(`Unknown credit pack "${pack_id}" for ${agentName}.\n\n` +
+                    `Available packs:\n${offers.map((offer) => `  ${formatCreditPackOffer(offer)}`).join("\n")}`);
+            }
+            resolvedOffer = offer;
+        }
+        else if (offers.length === 1) {
+            resolvedOffer = offers[0];
+        }
+        else {
+            return text([
+                `Multiple credit packs are available for ${agentName}.`,
+                "",
+                ...offers.map((offer) => `  ${offer.pack_id}: ${formatCreditPackOffer(offer)}`),
+                "",
+                "Choose one by calling:",
+                `  buy_agent_credit_pack({ agent_id: "${agent.id}", pack_id: "${offers[0].pack_id}" })`,
+            ].join("\n"));
+        }
+        const method = resolveConfirmationMethod(pay_with, pending?.method, compatibleMethods);
+        if (requiresSpendConfirmation() && !confirmed) {
+            pendingCreditPackPurchases.set(agent.id, {
+                agentId: agent.id,
+                agentName,
+                offer: resolvedOffer,
+                method,
+            });
+            return text([
+                `Ready to buy a credit pack for ${agentName}`,
+                "",
+                formatCreditPackOffer(resolvedOffer),
+                `Payment: ${formatPaymentLabel(method)}`,
+                `Consumer principal: ${principal}`,
+                "",
+                "To proceed, call:",
+                `  buy_agent_credit_pack({ agent_id: "${agent.id}", pack_id: "${resolvedOffer.pack_id}", pay_with: "${method}", confirmed: true })`,
+                "",
+                "To cancel, do nothing.",
+            ].join("\n"));
+        }
+        const result = await apiPostWithPayment(`/agents/${agent.id}/credit-packs/purchase`, { pack_id: resolvedOffer.pack_id }, method, { ensureConsumerPrincipal: true });
+        pendingCreditPackPurchases.delete(agent.id);
+        return text([
+            `Credit pack purchased for ${agentName}`,
+            "",
+            formatCreditPackOffer(result.offer),
+            formatCreditPack(result.credit_pack),
+            `Consumer principal: ${result.consumer_principal}`,
+            "",
+            "Future runs through run_agent will automatically use this credit pack while units remain.",
+        ].join("\n"));
+    });
+    server.tool("list_agent_credit_packs", "Show discounted credit-pack offers for an agent plus any balances available under the current consumer principal.", {
+        agent_id: z.string().describe("Agent ID (UUID, slug, or name)"),
+    }, async ({ agent_id }) => {
+        const agent = await getAgent(agent_id);
+        const result = await apiGet(`/agents/${agent.id}/credit-packs`, { ensureConsumerPrincipal: true });
+        const lines = [
+            `Credit packs for ${agent.name}`,
+            ...(result.consumer_principal ? [`Consumer principal: ${result.consumer_principal}`] : []),
+        ];
+        if (result.offers.length > 0) {
+            lines.push("", "Available packs:", ...result.offers.map((offer) => `  ${offer.pack_id}: ${formatCreditPackOffer(offer)}`));
+        }
+        if (result.balances.length > 0) {
+            lines.push("", "Your balances:", ...result.balances.map((pack) => `  ${formatCreditPack(pack)}`));
+        }
+        else {
+            lines.push("", "No purchased credit packs found for this agent.");
+        }
+        return text(lines.join("\n"));
+    });
+}

package/dist/tools/run.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
 import { uploadLocalFiles } from "../core/file-upload.js";
-import { getConfiguredMethods, hasWalletConfigured, getWalletAddress } from "../core/payments.js";
+import { formatCreditPackOffer, getActiveCreditPack, getCreditPackInventory, getCreditPackProgram, } from "../core/passes.js";
+import { getCompatiblePaymentMethods, getConfiguredMethods, hasWalletConfigured, getWalletAddress, normalizePaymentMethod, } from "../core/payments.js";
 import { requiresSpendConfirmation, getDefaultTipAmount } from "../core/config.js";
 import { formatRunResult } from "../core/formatters.js";
+import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend-policy.js";
 import { storeFeedbackToken } from "./_token-cache.js";
-import { initiateCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
+import { getOrCreatePendingCardSetup, formatCardSetupBlocks } from "../core/card-setup.js";
+import { formatPaymentLabel, formatRunConfirmationCommand, resolveConfirmationMethod, } from "./_payment-confirmation.js";
 const POLL_INTERVAL_MS = 3000;
-const POLL_MAX_MS = 120000; // 2 minutes
-async function pollJobUntilDone(jobId, agentName) {
+const POLL_MAX_MS = 120000;
+async function pollJobUntilDone(jobId) {
     const deadline = Date.now() + POLL_MAX_MS;
     const walletAddress = await getWalletAddress();
     const walletParam = walletAddress ? `?wallet=${walletAddress}` : "";
@@ -22,10 +25,9 @@ async function pollJobUntilDone(jobId, agentName) {
             if (job.status === "failed") {
                 return { status: "failed", output: job.output, error_code: job.error_code };
             }
-            // Still processing — continue polling
         }
         catch {
-            // Ignore poll errors, keep trying until deadline
+            // Ignore poll errors until timeout.
         }
     }
     return { status: "failed", error_code: "POLL_TIMEOUT" };
@@ -36,20 +38,36 @@ function text(t) {
 function multiText(...blocks) {
     return { content: blocks.map((t) => ({ type: "text", text: t })) };
 }
-// Pending confirmations: agent_id → { agent, input, method }
 const pendingRuns = new Map();
+function buildCreditPackOfferLines(agent) {
+    const program = getCreditPackProgram(agent);
+    if (!program?.packs?.length)
+        return [];
+    return [
+        "Discounted credit packs:",
+        ...program.packs.map((pack) => formatCreditPackOffer({
+            pack_id: pack.key ?? "",
+            label: pack.name ?? pack.key ?? "Credit Pack",
+            included_units: pack.included_units ?? 0,
+            price_usd: pack.price_usd ?? "0.00",
+            effective_price_per_unit_usd: (pack.included_units ?? 0) > 0 && pack.price_usd
+                ? (Number(pack.price_usd) / (pack.included_units ?? 1)).toFixed(6)
+                : undefined,
+        })).map((line) => `  ${line}`),
+        `  Buy one with buy_agent_credit_pack({ agent_id: "${agent.id}", pack_id: "<pack_id>" })`,
+    ];
+}
 export function registerRunTools(server) {
-    server.tool("run_agent", "Run an AI agent from the marketplace. Pays automatically via configured wallet. Returns the agent's output, cost, and job ID for tracking. If spending confirmation is enabled, first call returns a price quote — call again with confirmed: true to execute. Local file paths in the input (e.g. /Users/.../photo.jpg) are automatically uploaded to temporary storage and replaced with download URLs — just pass the path directly, no base64 encoding needed.", {
+    server.tool("run_agent", "Run an AI agent from the marketplace. Pays automatically via configured wallet. Returns the agent's output, cost, and job ID for tracking. If spending confirmation is enabled, first call returns a price quote — call again with confirmed: true to execute. Local file paths in the input (e.g. /Users/.../photo.jpg) are automatically uploaded to temporary storage and replaced with download URLs before execution.", {
         agent_id: z.string().describe("Agent ID (UUID, slug, or name)"),
         input: z.record(z.unknown()).describe("Input payload for the agent"),
-        pay_with: z.string().optional().describe("Payment method — wallet ID, chain name (tempo, base, etc.), or 'card'. Auto-detected if omitted."),
+        pay_with: z.string().trim().min(1).describe("Required payment method — wallet ID, chain name (tempo, base, etc.), or 'card'. Use wallet_status to see configured options."),
         confirmed: z.boolean().optional().describe("Set to true to confirm spending after seeing the price quote."),
     }, async ({ agent_id, input, pay_with, confirmed }) => {
         if (!hasWalletConfigured()) {
             try {
-                const { qr, url } = await initiateCardSetup();
-                const blocks = formatCardSetupBlocks(qr, url);
-                return multiText(...blocks);
+                const { url } = await getOrCreatePendingCardSetup();
+                return multiText(...formatCardSetupBlocks(url));
             }
             catch {
                 return text("No payment method configured.\n\n" +
@@ -57,7 +75,6 @@ export function registerRunTools(server) {
                     "To use crypto: wallet_setup({ action: \"create\" })");
             }
         }
-        // Resolve agent and fetch details
         let agent;
         try {
             agent = await apiGet(`/agents/${agent_id}`);
@@ -65,28 +82,54 @@ export function registerRunTools(server) {
         catch {
             return text(`Agent "${agent_id}" not found. Use search_agents to find available agents.`);
         }
-        const price = parseFloat(agent.pricePer1kTokens ?? "0.01");
+        const price = parseFloat(agent.pricePerRunUsd ?? "0.01");
         const agentName = agent.name ?? agent_id;
-        // Confirmation step: show price and wait for confirmed: true
-        if (requiresSpendConfirmation() && !confirmed) {
+        const creditPackInventory = await getCreditPackInventory(agent.id);
+        const activeCreditPack = getActiveCreditPack(creditPackInventory);
+        const compatibleMethods = getCompatiblePaymentMethods(agent, getConfiguredMethods());
+        const pending = pendingRuns.get(agent.id);
+        const requestedMethod = pay_with;
+        const normalizedRequestedMethod = normalizePaymentMethod(requestedMethod);
+        if (!normalizedRequestedMethod) {
+            return text(`Payment method "${requestedMethod}" is not configured.\n\n` +
+                "Use wallet_status to review your current payment methods.");
+        }
+        if (!compatibleMethods.includes(normalizedRequestedMethod)) {
+            return text(`This agent cannot be paid with "${requestedMethod}".\n\n` +
+                `Available payment methods for this agent: ${compatibleMethods.join(", ") || "none"}.\n` +
+                "Use get_agent to inspect the agent details or choose another payment method.");
+        }
+        const method = resolveConfirmationMethod(pay_with, pending?.method, compatibleMethods);
+        const spendCheckMethod = method ?? normalizedRequestedMethod;
+        if (!activeCreditPack) {
+            const spendCheck = canSpend({
+                method: spendCheckMethod,
+                amountUsd: price,
+            });
+            if (!spendCheck.ok) {
+                return text(spendCheck.message);
+            }
+        }
+        const needsPolicyConfirmation = !activeCreditPack && requiresPolicyConfirmation(spendCheckMethod, price);
+        if (!activeCreditPack && (requiresSpendConfirmation() || needsPolicyConfirmation) && !confirmed) {
             pendingRuns.set(agent.id, {
                 agent: { id: agent.id, name: agentName, price },
                 input,
-                method: pay_with,
+                method,
             });
-            return text([
+            const quoteLines = [
                 `Ready to run ${agentName}`,
                 "",
                 `  Cost: $${price.toFixed(2)}`,
-                `  Payment: ${pay_with ?? getConfiguredMethods()[0] ?? "auto"}`,
-                "",
-                "To proceed, call:",
-                `  run_agent({ agent_id: "${agent.id}", input: <same>, confirmed: true })`,
-                "",
-                "To cancel, do nothing.",
-            ].join("\n"));
+                `  Payment: ${formatPaymentLabel(method)}`,
+            ];
+            const creditPackLines = buildCreditPackOfferLines(agent);
+            if (creditPackLines.length > 0) {
+                quoteLines.push("", ...creditPackLines);
+            }
+            quoteLines.push("", "To proceed, call:", formatRunConfirmationCommand(agent.id, method), "", "To cancel, do nothing.");
+            return text(quoteLines.join("\n"));
         }
-        const method = pay_with;
         let processedInput;
         let uploadSummary = "";
         try {
@@ -94,7 +137,7 @@ export function registerRunTools(server) {
             processedInput = uploadResult.input;
             if (uploadResult.uploads.length > 0) {
                 uploadSummary = uploadResult.uploads
-                    .map((u) => `Uploaded ${u.field}: ${u.originalPath} → ${u.url}`)
+                    .map((upload) => `Uploaded ${upload.field}: ${upload.originalPath} → ${upload.url}`)
                     .join("\n");
             }
         }
@@ -103,18 +146,41 @@ export function registerRunTools(server) {
             return text(`Error: ${msg}`);
         }
         let result;
+        let usedPaidMethod = !activeCreditPack;
         try {
-            result = await apiPostWithPayment(`/agents/${agent.id}/run`, { input: processedInput }, method);
+            if (activeCreditPack) {
+                try {
+                    result = await apiPost(`/agents/${agent.id}/run`, { input: processedInput }, { ensureConsumerPrincipal: true });
+                }
+                catch (packErr) {
+                    const packApiErr = packErr;
+                    if (packApiErr?.status !== 402)
+                        throw packErr;
+                    result = await apiPostWithPayment(`/agents/${agent.id}/run`, { input: processedInput }, method);
+                    usedPaidMethod = true;
+                }
+            }
+            else {
+                result = await apiPostWithPayment(`/agents/${agent.id}/run`, { input: processedInput }, method);
+            }
+            if (usedPaidMethod) {
+                recordSpend(spendCheckMethod, price);
+            }
         }
         catch (err) {
             const apiErr = err;
             if (apiErr?.status === 402) {
                 const allMethods = getConfiguredMethods();
                 const methodName = method ?? allMethods[0] ?? "auto";
-                return text(`Payment failed — "${methodName}" payment was rejected.\n\n` +
-                    "Check your payment method and try again.\n" +
-                    (allMethods.length > 0 ? `Configured methods: ${allMethods.join(", ")}\n` : "") +
-                    "Use wallet_status to check your current payment methods.");
+                const creditPackLines = buildCreditPackOfferLines(agent);
+                return text([
+                    `Payment failed — "${methodName}" payment was rejected.`,
+                    "",
+                    "Check your payment method and try again.",
+                    ...(allMethods.length > 0 ? [`Configured methods: ${allMethods.join(", ")}`] : []),
+                    "Use wallet_status to check your current payment methods.",
+                    ...(creditPackLines.length > 0 ? ["", ...creditPackLines] : []),
+                ].join("\n"));
             }
             const msg = apiErr?.message ?? "Failed to run agent";
             if (msg.includes("Missing required field") || msg.includes("validation failed")) {
@@ -122,7 +188,6 @@ export function registerRunTools(server) {
             }
             return text(`Error: ${msg}`);
         }
-        // Clean up pending confirmation
         pendingRuns.delete(agent.id);
         const formatted = formatRunResult(result, {
             paymentMethod: method ?? getConfiguredMethods()[0],
@@ -134,22 +199,23 @@ export function registerRunTools(server) {
         }
         const actualCost = result.cost;
         const status = result.status;
-        // Async agent — poll until complete
+        const usedCreditPack = result.consumption_mode === "credit_pack";
         if (status === "processing") {
-            const pollResult = await pollJobUntilDone(jobId, agentName);
+            const pollResult = await pollJobUntilDone(jobId);
             if (pollResult.status === "completed") {
                 const asyncFormatted = formatRunResult({
                     ...result,
                     status: "success",
                     output: pollResult.output,
                 }, { paymentMethod: method ?? getConfiguredMethods()[0] });
-                if (result.feedback_token) {
-                    storeFeedbackToken(jobId, result.feedback_token, resultAgentId);
-                }
-                const asyncCostLine = actualCost != null ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.` : "";
+                const asyncSpendLine = usedCreditPack
+                    ? "This run used your available credit pack."
+                    : actualCost != null
+                        ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.`
+                        : "This run completed successfully.";
                 const asyncFeedbackAsk = [
-                    `IMPORTANT: After presenting the result above, you MUST ask the user:`,
-                    `"${asyncCostLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
+                    "IMPORTANT: After presenting the result above, you MUST ask the user:",
+                    `"${asyncSpendLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
                     "",
                     `If the user wants to rate: rate_agent({ job_id: "${jobId}", rating: <1-5>, comment: "..." })`,
                     `If the user wants to tip: tip_agent({ job_id: "${jobId}", agent_id: "${resultAgentId}", amount: 0.25 })`,
@@ -157,16 +223,16 @@ export function registerRunTools(server) {
                 ].join("\n");
                 return multiText(uploadSummary ? `${uploadSummary}\n\n${asyncFormatted}` : asyncFormatted, asyncFeedbackAsk);
             }
-            // Async agent failed
             const failedFormatted = formatRunResult({
                 ...result,
                 status: "failed",
                 output: pollResult.output,
                 error_code: pollResult.error_code,
             }, { paymentMethod: method ?? getConfiguredMethods()[0] });
-            return multiText(uploadSummary ? `${uploadSummary}\n\n${failedFormatted}` : failedFormatted, "The agent execution failed. A refund has been initiated automatically.");
+            return multiText(uploadSummary ? `${uploadSummary}\n\n${failedFormatted}` : failedFormatted, usedCreditPack
+                ? "The agent execution failed and your reserved credit-pack unit was released automatically."
+                : "The agent execution failed. A refund has been initiated automatically.");
         }
-        // Auto-tip if configured and run succeeded
         const defaultTip = getDefaultTipAmount();
         let tipLine = "";
         if (status === "success" && defaultTip > 0 && result.feedback_token) {
@@ -184,17 +250,21 @@ export function registerRunTools(server) {
             }
         }
         if (status !== "success") {
-            return multiText(uploadSummary ? `${uploadSummary}\n\n${formatted}` : formatted, "The agent execution failed. A refund has been initiated automatically.");
+            return multiText(uploadSummary ? `${uploadSummary}\n\n${formatted}` : formatted, usedCreditPack
+                ? "The agent execution failed and your reserved credit-pack unit was released automatically."
+                : "The agent execution failed. A refund has been initiated automatically.");
         }
-        const costLine = actualCost != null ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.` : "";
-        // Separate the feedback ask into its own content block so the LLM
-        // surfaces it to the user as a distinct follow-up question, rather than
-        // burying it inside a collapsed tool output.
+        const costLine = usedCreditPack
+            ? ""
+            : actualCost != null
+                ? `Paid $${actualCost.toFixed(actualCost < 0.01 ? 4 : 2)}.`
+                : "";
+        const spendLine = usedCreditPack ? "This run used your available credit pack." : (costLine || "This run completed successfully.");
         const feedbackAsk = [
-            `--- Job ${jobId} | ${agentName} | ${costLine} ---`,
+            `--- Job ${jobId} | ${agentName} | ${usedCreditPack ? "covered by credit pack" : (costLine || "completed")} ---`,
             "",
-            `IMPORTANT: After presenting the result above, you MUST ask the user:`,
-            `"${costLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
+            "IMPORTANT: After presenting the result above, you MUST ask the user:",
+            `"${spendLine} Was this result helpful? I can rate it (1-5 stars) or tip the builder for you."`,
             tipLine,
             "",
             `If the user wants to rate: rate_agent({ job_id: "${jobId}", rating: <1-5>, comment: "..." })`,
@@ -203,6 +273,10 @@ export function registerRunTools(server) {
             ] : []),
             `To save for later: favorite_agent({ agent_id: "${resultAgentId}" })`,
         ].join("\n");
-        return multiText(uploadSummary ? `${uploadSummary}\n\n${formatted}` : formatted, feedbackAsk);
+        const supplementalLines = !usedCreditPack
+            ? buildCreditPackOfferLines(agent)
+            : [];
+        const primaryBlock = uploadSummary ? `${uploadSummary}\n\n${formatted}` : formatted;
+        return multiText(supplementalLines.length > 0 ? `${primaryBlock}\n\n${supplementalLines.join("\n")}` : primaryBlock, feedbackAsk);
     });
 }