@agentwonderland/mcp 0.1.53 → 0.1.54

package/src/tools/playbooks.ts

@@ -0,0 +1,1100 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
+import { uploadLocalFiles } from "../core/file-upload.js";
+import { hasWalletConfigured, getConfiguredMethods, getWalletAddress } from "../core/payments.js";
+import { requiresSpendConfirmation } from "../core/config.js";
+import { canSpend, recordSpend, requiresPolicyConfirmation } from "../core/spend-policy.js";
+import { formatRunResult } from "../core/formatters.js";
+import { storeFeedbackToken } from "./_token-cache.js";
+import {
+  formatPaymentLabel,
+  resolveConfirmationMethod,
+} from "./_payment-confirmation.js";
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_MS = 300000;
+
+type PlaybookStepQuote = {
+  id: string;
+  source_step_id?: string;
+  index: number;
+  node_type: "aw_agent" | "external_x402";
+  agent_slug: string | null;
+  agent_id: string | null;
+  provider_id: string | null;
+  agent_name: string;
+  description: string;
+  quantity: number;
+  iteration?: number;
+  default_input?: Record<string, unknown>;
+  unit_price_usd: number;
+  quoted_cost_usd: number;
+  support_status: string;
+};
+
+type PlaybookRecord = {
+  id: string;
+  slug: string;
+  version: number;
+  name: string;
+  persona: string;
+  tags: string[];
+  description: string;
+  outcome: string;
+  support_status: "supported" | "catalog_only";
+  support_note?: string;
+  input_schema: Record<string, unknown>;
+  sample_input: Record<string, unknown>;
+  budget_notes: string[];
+  risks: string[];
+  stats?: {
+    favorite_count?: number;
+    rating_count?: number;
+    average_rating?: number | null;
+  };
+  current_quote: {
+    estimated_cost_usd: number;
+    step_count: number;
+    blocking_issues: string[];
+    steps: PlaybookStepQuote[];
+  };
+};
+
+type PlaybookRunReceipt = {
+  run_id: string;
+  status: string;
+  playbook_id: string;
+  playbook_slug: string;
+  playbook_version: number;
+  input?: Record<string, unknown>;
+  limits?: Record<string, number>;
+  budget_usd: number;
+  quoted_cost_usd: number;
+  charged_usd: number;
+  refunded_usd: number;
+  remaining_budget_usd: number;
+  output?: unknown;
+  error_code?: string;
+  failure_message?: string;
+  steps: Array<{
+    playbook_step_id: string;
+    step_index: number;
+    node_type: string;
+    agent_slug: string | null;
+    agent_id: string | null;
+    provider_id: string | null;
+    job_id: string | null;
+    consumption_mode?: "direct_charge" | "credit_pack" | "not_charged";
+    status: string;
+    quoted_cost_usd: number;
+    charged_usd: number;
+    refunded_usd: number;
+    output?: unknown;
+    error_code?: string;
+    failure_message?: string;
+  }>;
+};
+
+type AgentSchemaDetails = {
+  id?: string;
+  schema?: {
+    input?: {
+      inputSchema?: unknown;
+    };
+  };
+  mcpSchema?: {
+    inputSchema?: unknown;
+  };
+};
+
+const pendingPlaybookRuns = new Map<string, {
+  playbook: PlaybookRecord;
+  input: Record<string, unknown>;
+  budget: number;
+  method?: string;
+  limits?: Record<string, number>;
+}>();
+
+function text(t: string) {
+  return { content: [{ type: "text" as const, text: t }] };
+}
+
+function multiText(...blocks: string[]) {
+  return { content: blocks.map((t) => ({ type: "text" as const, text: t })) };
+}
+
+function money(value: number): string {
+  return `$${value.toFixed(value < 1 ? 4 : 2)}`;
+}
+
+async function collectWalletAddresses(paymentMethod?: string): Promise<string[]> {
+  const addresses = new Set<string>();
+  const primary = await getWalletAddress(paymentMethod);
+  if (primary) addresses.add(primary);
+  for (const chain of ["tempo", "base", "solana"]) {
+    const addr = await getWalletAddress(chain);
+    if (addr) addresses.add(addr);
+  }
+  return [...addresses];
+}
+
+async function pollJobUntilDone(
+  jobId: string,
+  paymentMethod?: string,
+): Promise<{ status: string; output?: unknown; error_code?: string }> {
+  const deadline = Date.now() + POLL_MAX_MS;
+  const walletAddresses = await collectWalletAddresses(paymentMethod);
+  const walletParams = walletAddresses.length > 0
+    ? walletAddresses.map((a) => `?wallet=${encodeURIComponent(a)}`)
+    : [""];
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    for (const walletParam of walletParams) {
+      try {
+        const job = await apiGet<{
+          status: string;
+          output?: unknown;
+          error_code?: string;
+        }>(`/jobs/${jobId}${walletParam}`);
+
+        if (job.status === "completed") return { status: "completed", output: job.output };
+        if (job.status === "failed") return { status: "failed", output: job.output, error_code: job.error_code };
+        break;
+      } catch (err) {
+        const status = (err as { status?: number })?.status;
+        if (status !== 404) break;
+      }
+    }
+  }
+
+  return { status: "failed", error_code: "POLL_TIMEOUT" };
+}
+
+function formatPlaybookList(playbooks: PlaybookRecord[], query?: string) {
+  if (playbooks.length === 0) {
+    return query
+      ? `No playbooks found matching "${query}". Try search_playbooks({ persona: "gtm" }) or search_playbooks({ tag: "research" }).`
+      : "No playbooks found.";
+  }
+
+  const lines = playbooks.map((playbook) => {
+  const support = playbook.support_status === "supported" ? "supported" : `catalog-only: ${playbook.support_note ?? "not launch executable"}`;
+    return [
+      `  ${playbook.name} (${playbook.slug})`,
+      `    ${playbook.outcome}`,
+      `    ${playbook.current_quote.step_count} step${playbook.current_quote.step_count === 1 ? "" : "s"} · ${money(playbook.current_quote.estimated_cost_usd)} est. · ${support}`,
+      `    Favorites: ${playbook.stats?.favorite_count ?? 0} · Rating: ${playbook.stats?.average_rating ? `${playbook.stats.average_rating}/5` : "unrated"} (${playbook.stats?.rating_count ?? 0})`,
+      `    Inspect: get_playbook({ slug: "${playbook.slug}" })`,
+    ].join("\n");
+  });
+
+  return [
+    query ? `Found ${playbooks.length} playbook${playbooks.length === 1 ? "" : "s"} matching "${query}":` : `Found ${playbooks.length} playbook${playbooks.length === 1 ? "" : "s"}:`,
+    "",
+    ...lines,
+  ].join("\n");
+}
+
+function formatPlaybook(playbook: PlaybookRecord) {
+  const q = playbook.current_quote;
+  const lines = [
+    `${playbook.name} (${playbook.slug})`,
+    `${playbook.outcome}`,
+    "",
+    playbook.description,
+    "",
+    `Support: ${playbook.support_status}${playbook.support_note ? ` — ${playbook.support_note}` : ""}`,
+    `Favorites: ${playbook.stats?.favorite_count ?? 0}`,
+    `Rating: ${playbook.stats?.average_rating ? `${playbook.stats.average_rating}/5` : "unrated"} (${playbook.stats?.rating_count ?? 0})`,
+    `Estimated cost: ${money(q.estimated_cost_usd)} across ${q.step_count} paid step${q.step_count === 1 ? "" : "s"}`,
+    ...(q.blocking_issues.length ? [`Blocking issues: ${q.blocking_issues.join("; ")}`] : []),
+    "",
+    "Inputs:",
+  ];
+
+  const schema = playbook.input_schema as { properties?: Record<string, { type?: string; description?: string }>; required?: string[] };
+  const required = new Set(schema.required ?? []);
+  for (const [name, def] of Object.entries(schema.properties ?? {})) {
+    lines.push(`  ${name}: ${def.type ?? "string"}${required.has(name) ? " (required)" : ""}${def.description ? ` — ${def.description}` : ""}`);
+  }
+
+  lines.push("", "Execution plan:");
+  for (const step of q.steps) {
+    const quantity = step.quantity > 1 ? ` × ${step.quantity}` : "";
+    const status = step.support_status === "ready" ? "" : " [blocking]";
+    lines.push(`  ${step.index + 1}. ${step.agent_name} (${step.agent_slug ?? step.node_type})${quantity} — ${money(step.quoted_cost_usd)}${status}`);
+  }
+
+  if (playbook.budget_notes.length) lines.push("", "Budget notes:", ...playbook.budget_notes.map((note) => `  - ${note}`));
+  if (playbook.risks.length) lines.push("", "Risks:", ...playbook.risks.map((risk) => `  - ${risk}`));
+
+  lines.push(
+    "",
+    "Sample input:",
+    JSON.stringify(playbook.sample_input, null, 2),
+    "",
+    `Run quote: run_playbook({ slug: "${playbook.slug}", input: <input>, budget: ${Math.max(1, Math.ceil(q.estimated_cost_usd + 1))} })`,
+  );
+  return lines.join("\n");
+}
+
+function formatLimitsField(limits?: Record<string, number>): string | undefined {
+  return limits && Object.keys(limits).length > 0
+    ? `limits: ${JSON.stringify(limits)}`
+    : undefined;
+}
+
+function formatRunConfirmationCommand(slug: string, method: string | undefined, budget: number, limits?: Record<string, number>) {
+  const args = [
+    `slug: "${slug}"`,
+    "input: <same>",
+    `budget: ${budget}`,
+    formatLimitsField(limits),
+    method ? `pay_with: "${method}"` : undefined,
+    "confirmed: true",
+  ].filter(Boolean);
+  return `run_playbook({ ${args.join(", ")} })`;
+}
+
+function formatQuoteNotes(playbook: PlaybookRecord): string[] {
+  const lines: string[] = [];
+  if (playbook.budget_notes.length > 0) {
+    lines.push("", "Budget and fanout notes:", ...playbook.budget_notes.map((note) => `  - ${note}`));
+  }
+  if (playbook.risks.length > 0) {
+    lines.push("", "Risks and limitations:", ...playbook.risks.map((risk) => `  - ${risk}`));
+  }
+  return lines;
+}
+
+function formatResumeCommand(receipt: PlaybookRunReceipt, budget = receipt.budget_usd): string {
+  const args = [
+    `resume_run_id: "${receipt.run_id}"`,
+    "confirmed: true",
+    `budget: ${budget}`,
+    formatLimitsField(receipt.limits),
+  ].filter(Boolean);
+  return `run_playbook({ ${args.join(", ")} })`;
+}
+
+async function formatCheaperAlternatives(currentSlug: string, budget: number): Promise<string> {
+  try {
+    const params = new URLSearchParams();
+    params.set("max_budget", String(budget));
+    params.set("limit", "4");
+    params.set("sort", "price");
+    const result = await apiGet<{ playbooks?: PlaybookRecord[] }>(`/playbooks?${params}`);
+    const alternatives = (result.playbooks ?? [])
+      .filter((candidate) => candidate.slug !== currentSlug)
+      .filter((candidate) => candidate.support_status === "supported")
+      .filter((candidate) => candidate.current_quote.blocking_issues.length === 0)
+      .filter((candidate) => candidate.current_quote.estimated_cost_usd <= budget)
+      .slice(0, 3);
+
+    if (alternatives.length === 0) return "";
+    return [
+      "Cheaper supported alternatives under this budget:",
+      ...alternatives.map((candidate) => `  - ${candidate.name} (${candidate.slug}) — ${money(candidate.current_quote.estimated_cost_usd)} est.; inspect with get_playbook({ slug: "${candidate.slug}" })`),
+    ].join("\n");
+  } catch {
+    return "";
+  }
+}
+
+function stepInput(baseInput: Record<string, unknown>, step: PlaybookStepQuote, iteration: number): Record<string, unknown> {
+  const input: Record<string, unknown> = { ...(step.default_input ?? {}), ...baseInput };
+  const itemIndex = Math.max(0, (step.iteration ?? 1) - 1);
+
+  if (Array.isArray(input.leads) && input.leads[itemIndex] && typeof input.leads[itemIndex] === "object") {
+    const lead = input.leads[itemIndex] as Record<string, unknown>;
+    input.lead = lead;
+    input.name = input.name ?? lead.name;
+    input.company = input.company ?? lead.company;
+    input.email = input.email ?? lead.email;
+  }
+
+  if (step.agent_slug === "serpanalyzer" && !("queries" in input)) {
+    input.queries = input.domain ? [`${String(input.domain)} alternatives`, `${String(input.domain)} pricing`] : ["category keywords"];
+  }
+  if (step.agent_slug === "ad-strategy-intel" && input.domain && !("startUrls" in input)) {
+    input.startUrls = [{
+      url: normalizeUrl(input.domain) ?? String(input.domain),
+    }];
+    input.maxAds = input.maxAds ?? 1;
+    delete input.platforms;
+  }
+  if (step.agent_slug === "web-search" && !("q" in input)) {
+    const company = (input.counterparty ?? input.company ?? input.domain ?? input.category ?? input.icp ?? "company") as string;
+    input.q = `${company} recent news`;
+  }
+  if (step.agent_slug === "company-enrichment-deep" && !("name" in input) && !("domain" in input)) {
+    input.name = input.counterparty ?? input.company ?? input.domain;
+  }
+  if (step.agent_slug === "company-enrichment-deep" && !("company_name" in input) && !("domain" in input)) {
+    input.company_name = input.company ?? input.name ?? input.counterparty;
+  }
+  if (step.agent_slug === "cold-email-council" && !("brief" in input)) {
+    const recipient = [
+      input.name ? String(input.name) : undefined,
+      input.company ? `at ${String(input.company)}` : undefined,
+      input.email ? `<${String(input.email)}>` : undefined,
+    ].filter(Boolean).join(" ");
+    input.brief = `Write a concise first-touch cold email${recipient ? ` to ${recipient}` : ""}.`;
+    input.context = {
+      lead: input.lead,
+      company: input.company,
+      email: input.email,
+      research: input.previous_outputs,
+    };
+    input.num_outputs = input.num_outputs ?? 1;
+  }
+  if (step.agent_slug === "email-verification" && !("emails" in input) && input.email) {
+    input.emails = [String(input.email)];
+  }
+  if (step.agent_slug === "scan-contract-for-risks" && !("file" in input) && input.contract) {
+    input.file = input.contract;
+  }
+  if (step.agent_slug === "place-search") {
+    input.location = input.location ?? input.zip;
+  }
+  if (step.quantity > 1) {
+    input.limit = Math.min(Number(input.limit ?? step.quantity), step.quantity);
+  }
+  input.item_index = itemIndex;
+
+  return input;
+}
+
+function valueAtPath(input: Record<string, unknown>, path: string): unknown {
+  return path.split(".").reduce<unknown>((current, key) => {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return undefined;
+    return (current as Record<string, unknown>)[key];
+  }, input);
+}
+
+function present(value: unknown): boolean {
+  return value !== undefined && value !== null && !(typeof value === "string" && value.trim() === "");
+}
+
+function liveInputSchema(agent: AgentSchemaDetails): { properties?: Record<string, unknown>; required?: string[] } | null {
+  const raw = agent.schema?.input?.inputSchema ?? agent.mcpSchema?.inputSchema;
+  return raw && typeof raw === "object" && !Array.isArray(raw)
+    ? raw as { properties?: Record<string, unknown>; required?: string[] }
+    : null;
+}
+
+function aliasCandidates(field: string): string[] {
+  const aliases: Record<string, string[]> = {
+    q: ["query", "search", "domain", "company", "counterparty", "category", "icp", "vertical", "ticker", "compound"],
+    query: ["q", "search", "domain", "company", "counterparty", "category", "icp", "vertical", "ticker", "compound"],
+    search: ["q", "query", "domain", "company", "counterparty", "category", "icp", "vertical"],
+    name: ["company", "counterparty", "domain", "lead.name"],
+    company: ["name", "counterparty", "domain", "lead.company"],
+    company_name: ["company", "name", "counterparty", "lead.company"],
+    domain: ["company", "website", "site"],
+    website: ["domain", "company"],
+    emails: ["email", "lead.email"],
+    url: ["domain", "website"],
+    urls: ["url", "website", "domain"],
+    startUrls: ["startUrl", "url", "website", "domain"],
+    tickers: ["ticker", "symbol"],
+    ticker: ["tickers", "symbol"],
+    file: ["contract", "bill", "document", "path"],
+    text: ["brief", "content", "context"],
+    brief: ["text", "content", "context"],
+    context: ["previous_outputs", "brief", "text", "content"],
+    location: ["zip", "city", "address"],
+    email: ["lead.email"],
+  };
+  return aliases[field] ?? [];
+}
+
+function normalizeUrl(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const trimmed = value.trim();
+  return /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+}
+
+function repairValueForField(field: string, value: unknown, property: unknown): unknown {
+  const propertyDef = property as { type?: unknown; items?: { type?: unknown } } | undefined;
+  const type = propertyDef?.type;
+  if (field === "startUrls" || field === "urls") {
+    const toStartUrl = (candidate: unknown) => {
+      const url = normalizeUrl(candidate);
+      return field === "startUrls" && propertyDef?.items?.type === "object" && url ? { url } : url;
+    };
+    if (Array.isArray(value)) {
+      return value.map(toStartUrl).filter(Boolean);
+    }
+    const url = toStartUrl(value);
+    return url ? [url] : value;
+  }
+  if (type === "array" && !Array.isArray(value)) return [value];
+  return value;
+}
+
+function coerceKnownFieldValue(field: string, value: unknown, property: unknown): { value: unknown; changed: boolean } {
+  const propertyDef = property as { type?: unknown } | undefined;
+  if (field === "startUrls" || field === "urls") {
+    const repaired = repairValueForField(field, value, property);
+    return { value: repaired, changed: JSON.stringify(repaired) !== JSON.stringify(value) };
+  }
+  if (propertyDef?.type === "string" && Array.isArray(value)) {
+    const joined = value
+      .filter((item) => item != null && (typeof item === "string" || typeof item === "number" || typeof item === "boolean"))
+      .map(String)
+      .join("; ");
+    return joined ? { value: joined, changed: true } : { value, changed: false };
+  }
+  if ((propertyDef?.type === "number" || propertyDef?.type === "integer") && typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return { value: parsed, changed: true };
+  }
+  if (propertyDef?.type === "array" && !Array.isArray(value)) {
+    return { value: [value], changed: true };
+  }
+  return { value, changed: false };
+}
+
+function repairInputFromSchema(input: Record<string, unknown>, schema: { properties?: Record<string, unknown>; required?: string[] }) {
+  const repaired = { ...input };
+  const required = schema.required ?? [];
+  const applied: string[] = [];
+  const missing: string[] = [];
+  const properties = schema.properties ?? {};
+
+  for (const field of required) {
+    if (present(repaired[field])) continue;
+
+    const property = properties[field] as { default?: unknown } | undefined;
+    if (property && Object.prototype.hasOwnProperty.call(property, "default")) {
+      repaired[field] = property.default;
+      applied.push(`${field}=default`);
+      continue;
+    }
+
+    const candidate = aliasCandidates(field).find((alias) => present(valueAtPath(input, alias)));
+    if (candidate) {
+      repaired[field] = repairValueForField(field, valueAtPath(input, candidate), property);
+      applied.push(`${field}←${candidate}`);
+      continue;
+    }
+
+    missing.push(field);
+  }
+
+  for (const [field, property] of Object.entries(properties) as Array<[string, { default?: unknown }]>) {
+    if (present(repaired[field]) || !Object.prototype.hasOwnProperty.call(property, "default")) continue;
+    repaired[field] = property.default;
+    applied.push(`${field}=default`);
+  }
+
+  for (const [field, property] of Object.entries(properties)) {
+    if (!present(repaired[field])) continue;
+    const coerced = coerceKnownFieldValue(field, repaired[field], property);
+    if (coerced.changed) {
+      repaired[field] = coerced.value;
+      applied.push(`${field}=coerced`);
+    }
+  }
+
+  const propertyNames = Object.keys(properties);
+  const filtered = propertyNames.length > 0
+    ? Object.fromEntries(Object.entries(repaired).filter(([key]) => Object.prototype.hasOwnProperty.call(properties, key)))
+    : repaired;
+
+  return { input: filtered, applied, missing };
+}
+
+async function recordStep(runId: string, stepId: string, body: Record<string, unknown>) {
+  let lastError: unknown;
+  const encodedRunId = encodeURIComponent(runId);
+  const encodedStepId = encodeURIComponent(stepId);
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    try {
+      await apiPost(`/playbook-runs/${encodedRunId}/steps/${encodedStepId}`, body);
+      return;
+    } catch (err) {
+      lastError = err;
+      if (attempt < 3) {
+        await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Failed to record playbook step receipt");
+}
+
+async function updateRun(runId: string, body: Record<string, unknown>) {
+  await apiPost(`/playbook-runs/${runId}/status`, body);
+}
+
+function formatReceipt(receipt: PlaybookRunReceipt) {
+  const lines = [
+    `Playbook run ${receipt.run_id}`,
+    `${receipt.playbook_slug} v${receipt.playbook_version} — ${receipt.status}`,
+    "",
+    `Budget: ${money(receipt.budget_usd)}`,
+    `Charged: ${money(receipt.charged_usd)}`,
+    `Refunded: ${money(receipt.refunded_usd)}`,
+    `Remaining unspent budget: ${money(receipt.remaining_budget_usd)}`,
+    "",
+    "Steps:",
+  ];
+
+  for (const step of [...receipt.steps].sort((a, b) => a.step_index - b.step_index)) {
+    const job = step.job_id ? ` · job ${step.job_id}` : "";
+    const label = step.agent_slug ?? step.playbook_step_id;
+    const mode = step.consumption_mode === "credit_pack"
+      ? " · credit pack"
+      : step.consumption_mode === "not_charged"
+        ? " · not charged"
+        : "";
+    lines.push(`  ${step.step_index + 1}. ${label}: ${step.status}${mode} · charged ${money(step.charged_usd)} · refunded ${money(step.refunded_usd)}${job}`);
+    if (step.error_code) lines.push(`     error: ${step.error_code}`);
+  }
+
+  if (receipt.error_code) lines.push("", `Error: ${receipt.error_code}${receipt.failure_message ? ` — ${receipt.failure_message}` : ""}`);
+  if (receipt.status === "paused") {
+    lines.push("", `Resume: ${formatResumeCommand(receipt)}`);
+  }
+  if (receipt.output) {
+    lines.push("", "Output:", JSON.stringify(receipt.output, null, 2));
+  }
+
+  return lines.join("\n");
+}
+
+export function registerPlaybookTools(server: McpServer): void {
+  server.tool(
+    "search_playbooks",
+    "Search Agent Wonderland Playbooks by outcome, persona, tag, budget, or popularity. Playbooks are budget-capped multi-agent workflows backed by Agent Wonderland agents.",
+    {
+      query: z.string().optional(),
+      persona: z.string().optional(),
+      tag: z.string().optional(),
+      limit: z.number().optional().default(10),
+      max_budget: z.number().optional(),
+      sort: z.enum(["relevance", "price", "rating", "popularity", "newest"]).optional(),
+    },
+    async ({ query, persona, tag, limit, max_budget, sort }) => {
+      const params = new URLSearchParams();
+      if (query) params.set("q", query);
+      if (persona) params.set("persona", persona);
+      if (tag) params.set("tag", tag);
+      if (limit) params.set("limit", String(limit));
+      if (max_budget != null) params.set("max_budget", String(max_budget));
+      if (sort) params.set("sort", sort);
+      const result = await apiGet<{ playbooks: PlaybookRecord[] }>(`/playbooks?${params}`);
+      return text(formatPlaybookList(result.playbooks, query));
+    },
+  );
+
+  server.tool(
+    "get_playbook",
+    "Inspect an Agent Wonderland Playbook before running it. Shows input schema, live child-agent quote, support status, budget notes, and execution plan.",
+    {
+      playbook_id: z.string().optional(),
+      slug: z.string().optional(),
+    },
+    async ({ playbook_id, slug }) => {
+      const id = slug ?? playbook_id;
+      if (!id) return text("Provide slug or playbook_id.");
+      const playbook = await apiGet<PlaybookRecord>(`/playbooks/${encodeURIComponent(id)}`);
+      return text(formatPlaybook(playbook));
+    },
+  );
+
+  server.tool(
+    "run_playbook",
+    "Quote, confirm, execute, or resume an Agent Wonderland Playbook. One user approval sets a max budget; each child agent is still paid through the existing exact-charge run_agent payment flow. Unused budget is never charged.",
+    {
+      playbook_id: z.string().optional(),
+      slug: z.string().optional(),
+      input: z.record(z.string(), z.unknown()).optional().default({}),
+      budget: z.number().positive().optional(),
+      pay_with: z.string().trim().min(1).optional(),
+      confirmed: z.boolean().optional(),
+      resume_run_id: z.string().optional(),
+      limits: z.record(z.string(), z.number().int().positive()).optional(),
+    },
+    async ({ playbook_id, slug, input, budget, pay_with, confirmed, resume_run_id, limits }) => {
+      let resumeReceipt: PlaybookRunReceipt | null = null;
+      if (resume_run_id) {
+        resumeReceipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${resume_run_id}`);
+        if (!confirmed) {
+          const displayReceipt = { ...resumeReceipt, limits: limits ?? resumeReceipt.limits };
+          return text(`${formatReceipt(displayReceipt)}\n\nTo resume, call ${formatResumeCommand(displayReceipt, budget ?? resumeReceipt.budget_usd)}.`);
+        }
+        if (resumeReceipt.status === "completed") return text(formatReceipt(resumeReceipt));
+        slug = resumeReceipt.playbook_slug;
+        input = Object.keys(input ?? {}).length ? input : (resumeReceipt.input ?? {});
+        budget = budget ?? resumeReceipt.budget_usd;
+        limits = limits ?? resumeReceipt.limits;
+      }
+
+      const id = slug ?? playbook_id;
+      if (!id) return text("Provide slug or playbook_id.");
+      if (!budget) return text("Provide a budget. Example: run_playbook({ slug: \"competitor-ads\", input: { domain: \"notion.so\" }, budget: 5 })");
+
+      let playbook = await apiGet<PlaybookRecord>(`/playbooks/${encodeURIComponent(id)}`);
+      const pending = pendingPlaybookRuns.get(playbook.slug);
+      const method = resolveConfirmationMethod(pay_with, pending?.method, getConfiguredMethods());
+      const spendMethod = method ?? getConfiguredMethods()[0] ?? "auto";
+      const effectiveInput = Object.keys(input ?? {}).length ? input : pending?.input ?? {};
+      const effectiveBudget = budget ?? pending?.budget ?? 0;
+      const effectiveLimits = limits ?? pending?.limits;
+
+      if (!confirmed || effectiveLimits) {
+        try {
+          const quoted = await apiPost<{
+            playbook: PlaybookRecord;
+            budget_usd: number;
+            budget_sufficient: boolean;
+            remaining_budget_usd: number;
+          }>("/playbook-quotes", {
+            playbook_id: playbook.id,
+            slug: playbook.slug,
+            input: effectiveInput,
+            budget: effectiveBudget,
+            limits: effectiveLimits,
+          });
+          playbook = quoted.playbook;
+        } catch {
+          // Quote analytics should not block the user-facing quote.
+        }
+      }
+
+      if (playbook.support_status !== "supported") {
+        return text(`Playbook ${playbook.slug} is catalog-only for MVP execution.${playbook.support_note ? `\n\n${playbook.support_note}` : ""}`);
+      }
+      if (playbook.current_quote.blocking_issues.length > 0) {
+        return text(`Cannot run ${playbook.slug}; child-agent issues must be fixed first:\n${playbook.current_quote.blocking_issues.map((issue) => `- ${issue}`).join("\n")}`);
+      }
+
+      const estimatedCost = playbook.current_quote.estimated_cost_usd;
+      const spendCheck = canSpend({ method: spendMethod, amountUsd: Math.min(effectiveBudget, estimatedCost) });
+      if (!spendCheck.ok) return text(spendCheck.message);
+
+      if (estimatedCost > effectiveBudget) {
+        pendingPlaybookRuns.set(playbook.slug, { playbook, input: effectiveInput, budget: effectiveBudget, method, limits: effectiveLimits });
+        const cheaperAlternatives = await formatCheaperAlternatives(playbook.slug, effectiveBudget);
+        return text([
+          `${playbook.name} quote exceeds the budget.`,
+          "",
+          `Estimated cost: ${money(estimatedCost)}`,
+          `Budget: ${money(effectiveBudget)}`,
+          "",
+          "No paid execution was attempted.",
+          ...(cheaperAlternatives ? ["", cheaperAlternatives] : []),
+          "",
+          `Try a higher budget or reduced limits, then call:`,
+          formatRunConfirmationCommand(playbook.slug, method, Math.ceil(estimatedCost + 1), effectiveLimits),
+        ].join("\n"));
+      }
+
+      if ((requiresSpendConfirmation() || requiresPolicyConfirmation(spendMethod, estimatedCost)) && !confirmed) {
+        pendingPlaybookRuns.set(playbook.slug, { playbook, input: effectiveInput, budget: effectiveBudget, method, limits: effectiveLimits });
+        return text([
+          `Ready to run ${playbook.name}`,
+          "",
+          `  Max budget: ${money(effectiveBudget)}`,
+          `  Estimated child-agent charges: ${money(estimatedCost)}`,
+          `  Payment: ${formatPaymentLabel(method)}`,
+          `  Steps: ${playbook.current_quote.step_count}`,
+          "",
+          "Unused budget is not charged. The runner stops before exceeding the cap.",
+          "",
+          "Execution plan:",
+          ...playbook.current_quote.steps.map((step) => `  ${step.index + 1}. ${step.agent_name} (${step.agent_slug ?? step.node_type}) — ${money(step.quoted_cost_usd)}`),
+          ...formatQuoteNotes(playbook),
+          "",
+          "To proceed, call:",
+          formatRunConfirmationCommand(playbook.slug, method, effectiveBudget, effectiveLimits),
+          "",
+          "To cancel, do nothing.",
+        ].join("\n"));
+      }
+
+      if (!hasWalletConfigured()) {
+        return text([
+          "No payment method configured.",
+          "",
+          "Run wallet_setup({ action: \"start\" }) to configure Tempo, Base, or Solana before executing a paid playbook.",
+        ].join("\n"));
+      }
+
+      let processedInput: Record<string, unknown>;
+      let uploadSummary = "";
+      try {
+        const uploadResult = await uploadLocalFiles(effectiveInput);
+        processedInput = uploadResult.input;
+        if (uploadResult.uploads.length > 0) {
+          uploadSummary = uploadResult.uploads
+            .map((upload) => `Uploaded ${upload.field}: ${upload.originalPath} -> ${upload.url}`)
+            .join("\n");
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "File upload failed";
+        return text(`Error: ${msg}`);
+      }
+
+      const runState = resumeReceipt
+        ? {
+          run_id: resumeReceipt.run_id,
+          steps: playbook.current_quote.steps,
+          completedStepIds: new Set(resumeReceipt.steps
+            .filter((step) => step.status === "succeeded")
+            .map((step) => step.playbook_step_id)),
+          existingOutputs: resumeReceipt.steps
+            .filter((step) => step.status === "succeeded")
+            .map((step) => ({ step: step.playbook_step_id, job_id: step.job_id ?? undefined, output: step.output }))
+            .filter((step) => step.output !== undefined),
+          chargedUsd: Math.max(0, resumeReceipt.charged_usd - resumeReceipt.refunded_usd),
+        }
+        : {
+          ...await apiPost<{
+            run_id: string;
+            steps: PlaybookStepQuote[];
+          }>("/playbook-runs", {
+            playbook_id: playbook.id,
+            slug: playbook.slug,
+            input: processedInput,
+            budget: effectiveBudget,
+            limits: effectiveLimits,
+          }),
+          completedStepIds: new Set<string>(),
+          existingOutputs: [] as Array<{ step: string; job_id?: string; output?: unknown }>,
+          chargedUsd: 0,
+        };
+
+      await apiPost(`/playbook-runs/${runState.run_id}/status`, { status: "running" });
+
+      let charged = runState.chargedUsd;
+      const childOutputs: Array<{ step: string; job_id?: string; output?: unknown }> = [...runState.existingOutputs];
+
+      for (const [iteration, step] of runState.steps.entries()) {
+        if (runState.completedStepIds.has(step.id)) {
+          continue;
+        }
+        if (!step.agent_id || step.node_type !== "aw_agent") {
+          await recordStep(runState.run_id, step.id, {
+            status: "skipped",
+            consumption_mode: "not_charged",
+            error_code: step.node_type === "aw_agent" ? "MISSING_CHILD_AGENT" : "UNSUPPORTED_NODE_TYPE",
+            failure_message: step.node_type === "aw_agent"
+              ? `Missing child agent ${step.agent_slug}`
+              : `Unsupported playbook node type ${step.node_type}`,
+          });
+          await updateRun(runState.run_id, { status: "paused", error_code: step.node_type === "aw_agent" ? "MISSING_CHILD_AGENT" : "UNSUPPORTED_NODE_TYPE" });
+          const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+          return text(formatReceipt(receipt));
+        }
+
+        const nextCost = step.quoted_cost_usd;
+        if (charged + nextCost > effectiveBudget) {
+          await recordStep(runState.run_id, step.id, {
+            status: "skipped",
+            consumption_mode: "not_charged",
+            error_code: "BUDGET_EXHAUSTED",
+            failure_message: "Skipped before payment because the next child step would exceed the budget cap.",
+          });
+          await updateRun(runState.run_id, { status: "paused", error_code: "BUDGET_EXHAUSTED" });
+          const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+          return text(formatReceipt(receipt));
+        }
+
+        await recordStep(runState.run_id, step.id, {
+          status: "running",
+          agent_id: step.agent_id,
+          provider_id: step.provider_id,
+          quoted_cost_usd: step.quoted_cost_usd,
+        });
+
+        const payload = stepInput({ ...processedInput, previous_outputs: childOutputs }, step, iteration);
+        const playbookContext = {
+          playbook_run_id: runState.run_id,
+          playbook_id: playbook.id,
+          playbook_slug: playbook.slug,
+          playbook_step_id: step.id,
+          playbook_step_index: step.index,
+        };
+        let result: Record<string, unknown> | undefined;
+        let schemaError: { status?: number; message?: string } | undefined;
+        let usedPaidMethod = false;
+        const executeChild = async (childInput: Record<string, unknown>) => {
+          try {
+            return await apiPost<Record<string, unknown>>(
+              `/agents/${step.agent_id}/run`,
+              { input: childInput, playbook_context: playbookContext },
+              { ensureConsumerPrincipal: true },
+            );
+          } catch (err) {
+            const status = (err as { status?: number })?.status;
+            if (status !== 402) throw err;
+            usedPaidMethod = true;
+            return await apiPostWithPayment<Record<string, unknown>>(
+              `/agents/${step.agent_id}/run`,
+              { input: childInput, playbook_context: playbookContext },
+              method,
+            );
+          }
+        };
+        try {
+          result = await executeChild(payload);
+        } catch (err) {
+          const apiErr = err as { status?: number; message?: string };
+          const validationFailed = apiErr?.status === 400
+            && /missing required field|validation failed|invalid input|schema/i.test(apiErr.message ?? "");
+          if (validationFailed) {
+            try {
+              const agent = await apiGet<AgentSchemaDetails>(`/agents/${step.agent_id}`);
+              const schema = liveInputSchema(agent);
+              if (schema) {
+                const repaired = repairInputFromSchema(payload, schema);
+                if (repaired.applied.length > 0 && repaired.missing.length === 0) {
+                  result = await executeChild(repaired.input);
+                } else {
+                  schemaError = apiErr;
+                }
+              } else {
+                schemaError = apiErr;
+              }
+            } catch {
+              schemaError = apiErr;
+            }
+          } else {
+            const errorCode = apiErr?.status === 402 ? "PAYMENT_REJECTED" : "CHILD_AGENT_FAILED";
+            await recordStep(runState.run_id, step.id, {
+              status: apiErr?.status === 402 ? "skipped" : "failed",
+              agent_id: step.agent_id,
+              provider_id: step.provider_id,
+              consumption_mode: apiErr?.status === 402 ? "not_charged" : "direct_charge",
+              error_code: errorCode,
+              failure_message: apiErr?.message ?? "Child agent execution failed",
+            });
+            await updateRun(runState.run_id, {
+              status: "paused",
+              error_code: errorCode,
+              failure_message: apiErr?.message,
+            });
+            const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+            const help = apiErr?.status === 402
+              ? "Use wallet_status to inspect payment methods before retrying."
+              : "The child agent failed before a paid run completed.";
+            return text(`${formatReceipt(receipt)}\n\n${help}`);
+          }
+        }
+
+        if (!result) {
+          await recordStep(runState.run_id, step.id, {
+            status: "skipped",
+            agent_id: step.agent_id,
+            provider_id: step.provider_id,
+            consumption_mode: "not_charged",
+            error_code: "SCHEMA_MISMATCH",
+            failure_message: schemaError?.message ?? "Child agent input schema mismatch",
+          });
+          await updateRun(runState.run_id, {
+            status: "paused",
+            error_code: "SCHEMA_MISMATCH",
+            failure_message: schemaError?.message,
+          });
+          const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+          return text(`${formatReceipt(receipt)}\n\nTried the live child schema but could not safely repair the input. Use get_agent({ agent_id: "${step.agent_id}" }) to inspect the child agent schema before retrying.`);
+        }
+
+        const jobId = (result.job_id as string) ?? "";
+        const resultAgentId = (result.agent_id as string) ?? step.agent_id;
+        const status = result.status as string;
+        let output = result.output;
+        let errorCode = result.error_code as string | undefined;
+
+        if (result.feedback_token && jobId) {
+          storeFeedbackToken(jobId, result.feedback_token as string, resultAgentId);
+        }
+
+        if (status === "processing" && jobId) {
+          const pollResult = await pollJobUntilDone(jobId, method);
+          output = pollResult.output;
+          errorCode = pollResult.error_code;
+          if (pollResult.error_code === "POLL_TIMEOUT") {
+            await recordStep(runState.run_id, step.id, {
+              status: "running",
+              agent_id: step.agent_id,
+              provider_id: step.provider_id,
+              job_id: jobId,
+              consumption_mode: usedPaidMethod ? "direct_charge" : "not_charged",
+              error_code: "POLL_TIMEOUT",
+              failure_message: "Child job is still processing after the MCP poll window.",
+            });
+            await updateRun(runState.run_id, {
+              status: "needs_reconciliation",
+              error_code: "POLL_TIMEOUT",
+              failure_message: "A child job is still processing. Use get_playbook_run before retrying this playbook.",
+            });
+            const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+            return multiText(
+              formatReceipt(receipt),
+              `Child job ${jobId} is still processing after the MCP poll window. Do not rerun this step until get_job({ job_id: "${jobId}" }) or get_playbook_run({ run_id: "${runState.run_id}" }) shows a terminal status.`,
+            );
+          }
+          result.status = pollResult.status === "completed" ? "success" : "failed";
+        }
+
+        const usedCreditPack = result.consumption_mode === "credit_pack";
+        const actualCost = usedCreditPack ? 0 : Number(result.cost ?? (result.status === "success" ? step.quoted_cost_usd : 0));
+        if (result.status === "success") {
+          charged += actualCost;
+          if (usedPaidMethod) recordSpend(spendMethod, actualCost);
+          childOutputs.push({ step: step.id, job_id: jobId, output });
+          try {
+            await recordStep(runState.run_id, step.id, {
+              status: "succeeded",
+              agent_id: step.agent_id,
+              provider_id: step.provider_id,
+              job_id: jobId,
+              consumption_mode: usedCreditPack ? "credit_pack" : "direct_charge",
+              charged_usd: actualCost,
+              output,
+              error_code: null,
+              failure_message: null,
+            });
+          } catch (receiptErr) {
+            const message = receiptErr instanceof Error ? receiptErr.message : "Failed to record playbook step receipt";
+            try {
+              await updateRun(runState.run_id, {
+                status: "needs_reconciliation",
+                error_code: "RECEIPT_WRITE_FAILED",
+                failure_message: message,
+                output: {
+                  summary: `${playbook.name} needs reconciliation after a paid child step completed.`,
+                  child_outputs: childOutputs,
+                },
+              });
+            } catch {
+              // The paid child result is still returned below even if the run status update also fails.
+            }
+            return multiText(
+              formatRunResult({ status: "success", job_id: jobId, output }, { paymentMethod: method }),
+              [
+                `Playbook run ${runState.run_id} needs reconciliation.`,
+                `Child step ${step.id} completed${usedCreditPack ? " using a credit pack" : ` after charging ${money(actualCost)}`}, but the gateway receipt write failed after retries.`,
+                "Do not rerun this step until get_playbook_run shows it reconciled.",
+              ].join("\n"),
+            );
+          }
+        } else {
+          const failedCharge = usedCreditPack ? 0 : step.quoted_cost_usd;
+          const stepStatus = failedCharge > 0 ? "refunded" : "failed";
+          await recordStep(runState.run_id, step.id, {
+            status: stepStatus,
+            agent_id: step.agent_id,
+            provider_id: step.provider_id,
+            job_id: jobId,
+            consumption_mode: usedCreditPack ? "credit_pack" : "direct_charge",
+            charged_usd: failedCharge,
+            refunded_usd: failedCharge,
+            output,
+            error_code: errorCode ?? "CHILD_AGENT_FAILED",
+          });
+          await updateRun(runState.run_id, { status: "paused", error_code: errorCode ?? "CHILD_AGENT_FAILED" });
+          const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+          return multiText(
+            formatReceipt(receipt),
+            "The child agent failed. Existing per-agent refund behavior applies to that child step.",
+          );
+        }
+      }
+
+      const finalOutput = {
+        summary: `${playbook.name} completed ${childOutputs.length} child step${childOutputs.length === 1 ? "" : "s"}.`,
+        child_outputs: childOutputs,
+      };
+      await updateRun(runState.run_id, {
+        status: "completed",
+        output: finalOutput,
+        error_code: null,
+        failure_message: null,
+      });
+      const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+      pendingPlaybookRuns.delete(playbook.slug);
+
+      const runBlocks = childOutputs.length > 0
+        ? childOutputs.map((item) => item.output ? formatRunResult({ status: "success", job_id: item.job_id, output: item.output }, { paymentMethod: method }) : "").filter(Boolean)
+        : [];
+      return multiText(
+        uploadSummary ? `${uploadSummary}\n\n${formatReceipt(receipt)}` : formatReceipt(receipt),
+        ...runBlocks,
+        `IMPORTANT: After presenting the result above, you MUST ask the user: "Paid ${money(receipt.charged_usd)} across ${receipt.steps.filter((s) => s.status === "succeeded").length} steps. Was this playbook useful? I can save it with favorite_playbook({ slug: "${playbook.slug}" }) or record feedback with rate_playbook({ slug: "${playbook.slug}", run_id: "${receipt.run_id}", rating: <1-5>, useful: true, comment: "..." })."`,
+      );
+    },
+  );
+
+  server.tool(
+    "favorite_playbook",
+    "Save an Agent Wonderland Playbook for later. Favorites are associated with the configured consumer principal when available.",
+    {
+      playbook_id: z.string().optional(),
+      slug: z.string().optional(),
+    },
+    async ({ playbook_id, slug }) => {
+      const id = slug ?? playbook_id;
+      if (!id) return text("Provide slug or playbook_id.");
+
+      const result = await apiPost<{ ok: boolean; favorite_id: string; playbook_slug: string }>(
+        `/playbooks/${encodeURIComponent(id)}/favorite`,
+        {},
+        { ensureConsumerPrincipal: true },
+      );
+
+      return text(`Saved ${result.playbook_slug} to favorites.`);
+    },
+  );
+
+  server.tool(
+    "rate_playbook",
+    "Record feedback on an Agent Wonderland Playbook after a run. Provide a rating, useful flag, comment, or any combination.",
+    {
+      playbook_id: z.string().optional(),
+      slug: z.string().optional(),
+      run_id: z.string().optional(),
+      rating: z.number().int().min(1).max(5).optional(),
+      useful: z.boolean().optional(),
+      comment: z.string().max(2000).optional(),
+    },
+    async ({ playbook_id, slug, run_id, rating, useful, comment }) => {
+      const id = slug ?? playbook_id;
+      if (!id) return text("Provide slug or playbook_id.");
+      if (rating == null && useful == null && !comment?.trim()) {
+        return text("Provide rating, useful, or comment.");
+      }
+
+      const result = await apiPost<{ ok: boolean; feedback_id: string; playbook_slug: string }>(
+        `/playbooks/${encodeURIComponent(id)}/feedback`,
+        {
+          run_id,
+          rating,
+          useful,
+          comment,
+        },
+        { ensureConsumerPrincipal: true },
+      );
+
+      return text(`Recorded feedback for ${result.playbook_slug}.`);
+    },
+  );
+
+  server.tool(
+    "get_playbook_run",
+    "Inspect current or historical Agent Wonderland Playbook run state, including completed steps, charged/refunded amount, partial output, and resume command when paused.",
+    {
+      run_id: z.string(),
+    },
+    async ({ run_id }) => {
+      const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${run_id}`);
+      return text(formatReceipt(receipt));
+    },
+  );
+}