@agentwonderland/mcp 0.1.23 → 0.1.24

package/src/core/payments.ts

@@ -19,9 +19,23 @@ import {
   getApiUrl,
   type WalletEntry,
 } from "./config.js";
+import type { AgentRecord } from "./types.js";
 
 // Cache per wallet+chain combo to avoid re-initializing
 const fetchCache = new Map<string, typeof fetch>();
+const REGISTRY_METHOD_MAP: Record<string, string> = {
+  tempo: "tempo_usdc",
+  base: "base_usdc",
+  solana: "solana_usdc",
+  card: "stripe_card",
+};
+
+const METHOD_REGISTRY_MAP: Record<string, string> = {
+  tempo_usdc: "tempo",
+  base_usdc: "base",
+  solana_usdc: "solana",
+  stripe_card: "card",
+};
 
 // ── Helpers ─────────────────────────────────────────────────────
 
@@ -33,6 +47,20 @@ function cacheKey(walletId: string, chain: string): string {
   return `${walletId}:${chain}`;
 }
 
+function cardCacheKey(): string | null {
+  const card = getCardConfig();
+  if (!card) return null;
+  return `card:${getApiUrl()}:${card.consumerToken}:${card.paymentMethodId ?? ""}`;
+}
+
+function clearStaleCardCache(activeKey?: string): void {
+  for (const key of fetchCache.keys()) {
+    if (key.startsWith("card:") && key !== activeKey) {
+      fetchCache.delete(key);
+    }
+  }
+}
+
 // ── Per-protocol initializers ───────────────────────────────────
 
 async function initMpp(wallet: WalletEntry): Promise<typeof fetch | null> {
@@ -58,6 +86,23 @@ async function initMpp(wallet: WalletEntry): Promise<typeof fetch | null> {
   }
 }
 
+async function initSolanaMpp(wallet: WalletEntry): Promise<typeof fetch | null> {
+  try {
+    if (wallet.keyType !== "ows" && !wallet.key) {
+      return null;
+    }
+
+    const { Mppx } = await import("mppx/client");
+    const { solanaChargeClient } = await import("./solana-charge.js");
+    const mppx = Mppx.create({
+      methods: [solanaChargeClient({ wallet })] as any,
+    });
+    return mppx.fetch.bind(mppx) as typeof fetch;
+  } catch {
+    return null;
+  }
+}
+
 async function initCard(): Promise<typeof fetch | null> {
   const cardConfig = getCardConfig();
   if (!cardConfig) return null;
@@ -101,7 +146,10 @@ async function initCard(): Promise<typeof fetch | null> {
 /**
  * Initialize a payment-aware fetch for a given wallet + chain.
  */
-async function initForChain(wallet: WalletEntry, _chain: string): Promise<typeof fetch | null> {
+async function initForChain(wallet: WalletEntry, chain: string): Promise<typeof fetch | null> {
+  if (chain === "solana") {
+    return initSolanaMpp(wallet);
+  }
   return initMpp(wallet);
 }
 
@@ -116,7 +164,11 @@ async function initForChain(wallet: WalletEntry, _chain: string): Promise<typeof
 export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
   // Card payment
   if (method === "card") {
-    const ck = "card:card";
+    const ck = cardCacheKey();
+    clearStaleCardCache(ck ?? undefined);
+    if (!ck) {
+      throw new Error('Payment method "card" is not configured. Use the wallet_setup tool to configure a wallet');
+    }
     if (fetchCache.has(ck)) return fetchCache.get(ck)!;
     const pf = await initCard();
     if (pf) {
@@ -148,7 +200,16 @@ export async function getPaymentFetch(method?: string): Promise<typeof fetch> {
 
   for (const m of configured) {
     if (m === "card") {
-      const ck = "card:card";
+      const ck = cardCacheKey();
+      clearStaleCardCache(ck ?? undefined);
+      if (!ck) {
+        if (m === defaultMethod) {
+          const others = configured.filter((x) => x !== m);
+          const altText = others.length > 0 ? ` Available alternatives: ${others.join(", ")}` : "";
+          throw new Error(`Card payment failed to initialize. Check your card with wallet_status.${altText}`);
+        }
+        continue;
+      }
       if (fetchCache.has(ck)) return fetchCache.get(ck)!;
       const pf = await initCard();
       if (pf) {
@@ -230,6 +291,16 @@ export function getConfiguredMethods(): string[] {
   return methods;
 }
 
+/**
+ * Normalize a requested payment method into the MCP-visible method identifier.
+ * Accepts chain names, wallet IDs, or "card".
+ */
+export function normalizePaymentMethod(method: string): string | null {
+  if (method === "card") return "card";
+  const resolved = resolveWalletAndChain(method);
+  return resolved?.chain ?? null;
+}
+
 /**
  * Human-friendly display name for a payment method identifier.
  */
@@ -250,13 +321,33 @@ export function paymentMethodDisplayName(method: string): string {
  */
 export function getAcceptedPaymentMethods(): string[] {
   const methods = getConfiguredMethods();
-  const map: Record<string, string> = {
-    tempo: "tempo_usdc",
-    base: "base_usdc",
-    solana: "solana_usdc",
-    card: "stripe_card",
-  };
-  return methods.map((m) => map[m]).filter(Boolean);
+  return methods
+    .map((m) => REGISTRY_METHOD_MAP[m])
+    .filter(Boolean);
+}
+
+export function toRegistryPaymentMethod(method: string): string | null {
+  const normalized = normalizePaymentMethod(method);
+  if (!normalized) return null;
+  return REGISTRY_METHOD_MAP[normalized] ?? null;
+}
+
+export function getCompatiblePaymentMethods(
+  agent: Pick<AgentRecord, "payment"> | null | undefined,
+  configuredMethods = getConfiguredMethods(),
+): string[] {
+  const acceptedPayments = agent?.payment?.accepted_payments;
+  if (!Array.isArray(acceptedPayments) || acceptedPayments.length === 0) {
+    return [...configuredMethods];
+  }
+
+  const acceptedMethods = new Set(
+    acceptedPayments
+      .map((payment) => METHOD_REGISTRY_MAP[payment])
+      .filter(Boolean),
+  );
+
+  return configuredMethods.filter((method) => acceptedMethods.has(method));
 }
 
 /**
@@ -270,13 +361,16 @@ export function hasWalletConfigured(): boolean {
  * Get address for a specific method, or the first configured one.
  */
 export async function getWalletAddress(method?: string): Promise<string | null> {
+  let chain: string | undefined;
   let wallet: WalletEntry | undefined;
 
   if (method && method !== "card") {
     const resolved = resolveWalletAndChain(method);
     wallet = resolved?.wallet;
+    chain = resolved?.chain;
   } else if (!method) {
     wallet = getDefaultWallet();
+    chain = wallet?.defaultChain ?? wallet?.chains[0];
   }
 
   if (!wallet) return null;
@@ -284,14 +378,20 @@ export async function getWalletAddress(method?: string): Promise<string | null>
   // OWS-managed wallet: derive address via the adapter
   if (wallet.keyType === "ows" && wallet.owsWalletId) {
     try {
-      const { owsAccountFromWalletId } = await import("./ows-adapter.js");
-      const account = await owsAccountFromWalletId(wallet.owsWalletId);
-      return account.address;
+      const { getOwsWalletAddress } = await import("./ows-adapter.js");
+      return await getOwsWalletAddress(
+        wallet.owsWalletId,
+        chain === "solana" ? "solana" : "evm",
+      );
     } catch {
       return null;
     }
   }
 
+  if (chain === "solana") {
+    return null;
+  }
+
   // Raw EVM key path
   if (!wallet.key) return null;
 

package/src/core/principal.ts

@@ -0,0 +1,128 @@
+import { addWallet, getDefaultWallet, getWallets, type WalletEntry } from "./config.js";
+import { getWalletAddress } from "./payments.js";
+import {
+  createOwsWallet,
+  isOwsAvailable,
+  listOwsWallets,
+} from "./ows-adapter.js";
+
+const BASE_CHAIN_ID = "8453";
+const SOLANA_CHAIN_ID = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+const AUTO_IDENTITY_LABEL = "AW Identity";
+
+function principalFromAddress(address: string, type: "evm" | "solana"): string {
+  if (type === "evm") {
+    return `did:pkh:eip155:${BASE_CHAIN_ID}:${address.toLowerCase()}`;
+  }
+  return `did:pkh:${SOLANA_CHAIN_ID}:${address}`;
+}
+
+function walletSupportsEvm(wallet: WalletEntry): boolean {
+  return wallet.chains.some((chain) => chain !== "solana");
+}
+
+function walletSupportsSolana(wallet: WalletEntry): boolean {
+  return wallet.chains.includes("solana");
+}
+
+async function walletPrincipal(wallet: WalletEntry): Promise<string | null> {
+  if (walletSupportsEvm(wallet)) {
+    const address = await getWalletAddress(wallet.id);
+    return address ? principalFromAddress(address, "evm") : null;
+  }
+
+  if (walletSupportsSolana(wallet)) {
+    const address = await getWalletAddress(wallet.id);
+    return address ? principalFromAddress(address, "solana") : null;
+  }
+
+  return null;
+}
+
+function preferredWallets(): WalletEntry[] {
+  const wallets = getWallets();
+  const defaultWallet = getDefaultWallet();
+  const ordered = defaultWallet
+    ? [defaultWallet, ...wallets.filter((wallet) => wallet.id !== defaultWallet.id)]
+    : wallets;
+
+  return ordered.sort((a, b) => {
+    const aScore = walletSupportsEvm(a) ? 0 : walletSupportsSolana(a) ? 1 : 2;
+    const bScore = walletSupportsEvm(b) ? 0 : walletSupportsSolana(b) ? 1 : 2;
+    return aScore - bScore;
+  });
+}
+
+async function createFallbackIdentityWallet(): Promise<WalletEntry> {
+  const { generatePrivateKey } = await import("viem/accounts");
+  const walletName = `aw-identity-${Date.now()}`;
+  const entry: WalletEntry = {
+    id: walletName,
+    keyType: "evm",
+    key: generatePrivateKey(),
+    chains: ["tempo", "base"],
+    defaultChain: "base",
+    label: AUTO_IDENTITY_LABEL,
+  };
+  addWallet(entry);
+  return entry;
+}
+
+async function ensureIdentityWallet(): Promise<WalletEntry> {
+  const wallets = preferredWallets();
+  const existing = wallets.find((wallet) => walletSupportsEvm(wallet) || walletSupportsSolana(wallet));
+  if (existing) return existing;
+
+  if (await isOwsAvailable()) {
+    const existingOwsWallets = await listOwsWallets();
+    const linked = existingOwsWallets[0];
+    if (linked) {
+      const entry: WalletEntry = {
+        id: linked.name,
+        keyType: "ows",
+        owsWalletId: linked.id,
+        chains: ["tempo", "base"],
+        defaultChain: "base",
+        label: linked.name,
+      };
+      addWallet(entry);
+      return entry;
+    }
+
+    const walletName = `aw-identity-${Date.now()}`;
+    const created = await createOwsWallet(walletName, "evm");
+    const entry: WalletEntry = {
+      id: walletName,
+      keyType: "ows",
+      owsWalletId: created.walletId,
+      chains: ["tempo", "base"],
+      defaultChain: "base",
+      label: AUTO_IDENTITY_LABEL,
+    };
+    addWallet(entry);
+    return entry;
+  }
+
+  return createFallbackIdentityWallet();
+}
+
+export async function getConsumerPrincipal(): Promise<string | null> {
+  for (const wallet of preferredWallets()) {
+    const principal = await walletPrincipal(wallet);
+    if (principal) return principal;
+  }
+
+  return null;
+}
+
+export async function ensureConsumerPrincipal(): Promise<string> {
+  const existing = await getConsumerPrincipal();
+  if (existing) return existing;
+
+  const identityWallet = await ensureIdentityWallet();
+  const principal = await walletPrincipal(identityWallet);
+  if (!principal) {
+    throw new Error("Could not derive a consumer principal from the configured identity wallet.");
+  }
+  return principal;
+}

package/src/core/solana-charge.ts

@@ -0,0 +1,149 @@
+/**
+ * Custom MPP payment method: Solana USDC charge (client-side).
+ *
+ * Sends an SPL Token transfer on Solana mainnet and returns the transaction
+ * signature as the payment credential.
+ */
+import { Credential, Method, z } from "mppx";
+import { Connection, Keypair, PublicKey, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
+import {
+  ASSOCIATED_TOKEN_PROGRAM_ID,
+  TOKEN_PROGRAM_ID,
+  createTransferCheckedInstruction,
+  getAssociatedTokenAddressSync,
+} from "@solana/spl-token";
+import type { WalletEntry } from "./config.js";
+
+export const SOLANA_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" as const;
+export const SOLANA_CHAIN_ID = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" as const;
+const SOLANA_RPC = "https://api.mainnet-beta.solana.com";
+
+const solanaChargeMethod = Method.from({
+  name: "solana" as const,
+  intent: "charge" as const,
+  schema: {
+    credential: {
+      payload: z.object({
+        signature: z.string(),
+        type: z.literal("signature"),
+      }),
+    },
+    request: z.pipe(
+      z.object({
+        amount: z.string(),
+        currency: z.string(),
+        recipient: z.string(),
+        chainId: z.optional(z.string()),
+        decimals: z.optional(z.number()),
+      }),
+      z.transform((value: any) => ({
+        ...value,
+        methodDetails: { chainId: value.chainId ?? SOLANA_CHAIN_ID },
+      })),
+    ),
+  },
+});
+
+function keypairFromPrivateKeyHex(privateKeyHex: string): Keypair {
+  const normalized = privateKeyHex.startsWith("0x")
+    ? privateKeyHex.slice(2)
+    : privateKeyHex;
+  const bytes = Uint8Array.from(Buffer.from(normalized, "hex"));
+  if (bytes.length === 32) {
+    return Keypair.fromSeed(bytes);
+  }
+  if (bytes.length === 64) {
+    return Keypair.fromSecretKey(bytes);
+  }
+  throw new Error(`Unsupported Solana private key length: ${bytes.length} bytes.`);
+}
+
+async function getKeypair(wallet: WalletEntry): Promise<Keypair> {
+  if (wallet.keyType === "ows" && wallet.owsWalletId) {
+    const { owsSolanaKeypairFromWalletId } = await import("./ows-adapter.js");
+    return owsSolanaKeypairFromWalletId(wallet.owsWalletId);
+  }
+  if (wallet.key) {
+    return keypairFromPrivateKeyHex(wallet.key);
+  }
+  throw new Error(`Wallet "${wallet.id}" cannot sign Solana transactions.`);
+}
+
+interface SolanaChargeClientConfig {
+  wallet: WalletEntry;
+  rpcUrl?: string;
+}
+
+async function resolveRecipientTokenAccount(
+  connection: Connection,
+  mint: PublicKey,
+  recipient: PublicKey,
+): Promise<PublicKey> {
+  const accountInfo = await connection.getParsedAccountInfo(recipient, "confirmed");
+  const owner = accountInfo.value?.owner;
+  if (owner && owner.toBase58() === TOKEN_PROGRAM_ID.toBase58()) {
+    return recipient;
+  }
+
+  return getAssociatedTokenAddressSync(
+    mint,
+    recipient,
+    false,
+    TOKEN_PROGRAM_ID,
+    ASSOCIATED_TOKEN_PROGRAM_ID,
+  );
+}
+
+export function solanaChargeClient(config: SolanaChargeClientConfig) {
+  return Method.toClient(solanaChargeMethod as any, {
+    async createCredential({ challenge }: any) {
+      const { request } = challenge;
+      const amount = BigInt(request.amount);
+      const decimals = request.decimals ?? 6;
+      const mint = new PublicKey(request.currency ?? SOLANA_USDC_MINT);
+      const recipient = new PublicKey(request.recipient);
+      const keypair = await getKeypair(config.wallet);
+      const owner = keypair.publicKey;
+      const connection = new Connection(config.rpcUrl ?? SOLANA_RPC, "confirmed");
+
+      const sourceTokenAccount = getAssociatedTokenAddressSync(
+        mint,
+        owner,
+        false,
+        TOKEN_PROGRAM_ID,
+        ASSOCIATED_TOKEN_PROGRAM_ID,
+      );
+      const destinationTokenAccount = await resolveRecipientTokenAccount(
+        connection,
+        mint,
+        recipient,
+      );
+
+      const instruction = createTransferCheckedInstruction(
+        sourceTokenAccount,
+        mint,
+        destinationTokenAccount,
+        owner,
+        amount,
+        decimals,
+      );
+
+      const { blockhash } = await connection.getLatestBlockhash("confirmed");
+
+      const transaction = new Transaction({
+        feePayer: owner,
+        recentBlockhash: blockhash,
+      }).add(instruction);
+
+      const signature = await sendAndConfirmTransaction(connection, transaction, [keypair], {
+        commitment: "confirmed",
+      });
+
+      return Credential.serialize({
+        challenge,
+        payload: { signature, type: "signature" as const },
+        source: `did:pkh:${SOLANA_CHAIN_ID}:${owner.toBase58()}`,
+      });
+    },
+  });
+}

package/src/core/types.ts

@@ -22,6 +22,16 @@ export interface AgentRecord {
   };
   payment?: {
     pricing?: Record<string, unknown>;
+    accepted_payments?: string[];
+    credit_packs?: {
+      unit_type?: string;
+      packs?: Array<{
+        key?: string;
+        name?: string;
+        included_units?: number;
+        price_usd?: string;
+      }>;
+    } | null;
     [key: string]: unknown;
   };
   [key: string]: unknown;

package/src/index.ts

@@ -13,6 +13,7 @@ import { registerRateTools } from "./tools/rate.js";
 import { registerWalletTools } from "./tools/wallet.js";
 import { registerFavoriteTools } from "./tools/favorites.js";
 import { registerTipTools } from "./tools/tip.js";
+import { registerPassTools } from "./tools/passes.js";
 
 // ── Resources ────────────────────────────────────────────────────
 import { registerAgentResources } from "./resources/agents.js";
@@ -40,14 +41,17 @@ export async function startMcpServer(): Promise<void> {
         "1. search_agents() or solve() — find agents for the task",
         "2. get_agent() — check required input fields before running",
         "3. run_agent() or solve() with ALL required fields",
-        "4. If no payment method is set up, run_agent returns a QR code to connect a credit card — present it to the user",
+        "3a. If the agent offers discounted credit packs, use buy_agent_credit_pack() and list_agent_credit_packs() when helpful",
+        "4. If no payment method is set up, run_agent returns a setup page to connect a credit card — present it to the user",
         "5. Ask user to rate or tip after a successful run",
         "",
         "PAYMENT:",
-        "- Credit/debit card is the default and easiest way to pay — scan a QR code to connect, no funding needed.",
-        "- Crypto wallets (Tempo USDC, Base USDC) are available for advanced users.",
+        "- Credit/debit card is the default and easiest way to pay — open the setup page to connect, no funding needed.",
+        "- Crypto wallets (Tempo USDC, Base USDC, Solana USDC) are available for advanced users.",
         "- Card and crypto are SEPARATE payment methods. Card charges a credit card; crypto sends USDC on-chain.",
         "- Card is set as the default payment method when configured.",
+        "- If multiple valid payment methods are available for a run and pay_with is not specified, ask the user which one to use.",
+        "- For fully agentic execution, include pay_with explicitly.",
         "- Payment is automatic once configured. Users are never charged for failed runs.",
         "- Do NOT ask the user to set up payment before they try to run an agent. Let them explore freely.",
         "- If a specific payment method fails, report the error clearly. Do NOT silently fall back to a different method.",
@@ -74,6 +78,7 @@ export async function startMcpServer(): Promise<void> {
   registerWalletTools(server);
   registerFavoriteTools(server);
   registerTipTools(server);
+  registerPassTools(server);
 
   // Register resources
   registerAgentResources(server);

package/src/prompts/index.ts

@@ -18,7 +18,7 @@ export function registerPrompts(server: McpServer) {
             "1. Check my wallet status with wallet_status",
             "2. If no wallet is configured, help me create one with wallet_setup",
             "3. Show me some popular agents with search_agents",
-            "4. Briefly explain how solve, run_agent, rating, and tipping work",
+            "4. Briefly explain how solve, run_agent, buy_agent_credit_pack, rating, and tipping work",
           ].join("\n"),
         },
       }],

package/src/resources/wallet.ts

@@ -1,11 +1,13 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getWallets, getCardConfig } from "../core/config.js";
+import { getWallets, getCardConfig, getPendingCardSetupToken } from "../core/config.js";
+import { getCardCapabilities } from "../core/card-setup.js";
 import { getWalletAddress, getConfiguredMethods } from "../core/payments.js";
 
 export function registerWalletResources(server: McpServer) {
   server.resource("wallet-config", "aw://wallet", async () => {
     const wallets = getWallets();
     const card = getCardConfig();
+    const pendingCardSetupToken = getPendingCardSetupToken();
     const methods = getConfiguredMethods();
 
     const lines = ["Wallet Configuration", ""];
@@ -16,6 +18,11 @@ export function registerWalletResources(server: McpServer) {
     }
     if (card) {
       lines.push(`Card: ${card.brand} ****${card.last4}`);
+      const capabilities = await getCardCapabilities();
+      lines.push(`Card MPP: ${capabilities.spt_status}${capabilities.message ? ` — ${capabilities.message}` : ""}`);
+    }
+    if (pendingCardSetupToken) {
+      lines.push("Card setup: pending confirmation");
     }
     lines.push("", `Configured methods: ${methods.join(", ") || "none"}`);
 

package/src/tools/__tests__/_payment-confirmation.test.ts

@@ -0,0 +1,45 @@
+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/src/tools/_payment-confirmation.ts

@@ -0,0 +1,52 @@
+export function resolveConfirmationMethod(
+  requestedMethod: string | undefined,
+  pendingMethod: string | undefined,
+  compatibleMethods: string[],
+): string | undefined {
+  return requestedMethod ?? pendingMethod ?? compatibleMethods[0];
+}
+
+export function formatPaymentLabel(method: string | undefined): string {
+  return method ?? "auto";
+}
+
+export function formatRunConfirmationCommand(
+  agentId: string,
+  method: string | undefined,
+): string {
+  const payWith = method ? `, pay_with: "${method}"` : "";
+  return `  run_agent({ agent_id: "${agentId}", input: <same>${payWith}, confirmed: true })`;
+}
+
+export function formatSolveConfirmationCommand(
+  intent: string,
+  budget: number,
+  method: string | undefined,
+): string {
+  const payWith = method ? `, pay_with: "${method}"` : "";
+  return `  solve({ intent: "${intent}", input: <same>, budget: ${budget}${payWith}, confirmed: true })`;
+}
+
+export function makeSolvePendingKey(
+  intent: string,
+  input: Record<string, unknown>,
+  budget: number,
+): string {
+  return JSON.stringify({ intent, input, budget });
+}
+
+export function formatPaymentChoicePrompt(
+  subject: string,
+  methods: string[],
+  commands: string[],
+): string {
+  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");
+}