@agentwonderland/mcp 0.1.54 → 0.1.55

package/src/tools/playbooks.ts

@@ -1,12 +1,16 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { apiGet, apiPost, apiPostWithPayment } from "../core/api-client.js";
+import { apiGet, apiPost, apiPostWithApprovedLinkSpendRequest, 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 { getLinkConfig, setPendingLinkSpendRequest, 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 {
+  decodeMppNetworkId,
+  ensureApprovedLinkSpendRequest,
+  LinkApprovalRequiredError,
+} from "../core/link-cli.js";
 import {
   formatPaymentLabel,
   resolveConfirmationMethod,
@@ -33,6 +37,13 @@ type PlaybookStepQuote = {
   support_status: string;
 };
 
+type PlaybookFanoutControl = {
+  key: string;
+  default: number;
+  max: number;
+  description: string;
+};
+
 type PlaybookRecord = {
   id: string;
   slug: string;
@@ -44,6 +55,9 @@ type PlaybookRecord = {
   outcome: string;
   support_status: "supported" | "catalog_only";
   support_note?: string;
+  default_limits?: Record<string, number>;
+  applied_limits?: Record<string, number>;
+  fanout_controls?: PlaybookFanoutControl[];
   input_schema: Record<string, unknown>;
   sample_input: Record<string, unknown>;
   budget_notes: string[];
@@ -57,6 +71,9 @@ type PlaybookRecord = {
     estimated_cost_usd: number;
     step_count: number;
     blocking_issues: string[];
+    default_limits?: Record<string, number>;
+    applied_limits?: Record<string, number>;
+    fanout_controls?: PlaybookFanoutControl[];
     steps: PlaybookStepQuote[];
   };
 };
@@ -128,6 +145,35 @@ function money(value: number): string {
   return `$${value.toFixed(value < 1 ? 4 : 2)}`;
 }
 
+function cents(valueUsd: number): string {
+  return String(Math.max(1, Math.ceil(valueUsd * 100)));
+}
+
+function nonEmptyLimits(limits?: Record<string, number>): Record<string, number> | undefined {
+  return limits && Object.keys(limits).length > 0 ? limits : undefined;
+}
+
+function appliedPlaybookLimits(playbook: PlaybookRecord): Record<string, number> | undefined {
+  return nonEmptyLimits(playbook.current_quote.applied_limits ?? playbook.applied_limits ?? playbook.default_limits);
+}
+
+function fanoutControls(playbook: PlaybookRecord): PlaybookFanoutControl[] {
+  return playbook.current_quote.fanout_controls ?? playbook.fanout_controls ?? [];
+}
+
+function buildPlaybookLinkApprovalContext(params: {
+  playbook: PlaybookRecord;
+  budget: number;
+  stepCount: number;
+  runId: string;
+}): string {
+  return [
+    `Approve up to ${money(params.budget)} for the Agent Wonderland "${params.playbook.name}" playbook.`,
+    `This playbook run ${params.runId} has ${params.stepCount} child-agent steps and will stop before exceeding the approved budget.`,
+    "Each child agent is still charged at its exact quoted price, unused budget is not spent, and failed child runs keep the existing Agent Wonderland refund behavior.",
+  ].join(" ");
+}
+
 async function collectWalletAddresses(paymentMethod?: string): Promise<string[]> {
   const addresses = new Set<string>();
   const primary = await getWalletAddress(paymentMethod);
@@ -180,11 +226,13 @@ function formatPlaybookList(playbooks: PlaybookRecord[], query?: string) {
   }
 
   const lines = playbooks.map((playbook) => {
-  const support = playbook.support_status === "supported" ? "supported" : `catalog-only: ${playbook.support_note ?? "not launch executable"}`;
+    const support = playbook.support_status === "supported" ? "supported" : `catalog-only: ${playbook.support_note ?? "not launch executable"}`;
+    const limits = appliedPlaybookLimits(playbook);
+    const fanout = limits ? ` · default limits ${JSON.stringify(limits)}` : "";
     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}`,
+      `    ${playbook.current_quote.step_count} step${playbook.current_quote.step_count === 1 ? "" : "s"} · ${money(playbook.current_quote.estimated_cost_usd)} est. · ${support}${fanout}`,
       `    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");
@@ -228,14 +276,25 @@ function formatPlaybook(playbook: PlaybookRecord) {
   }
 
   if (playbook.budget_notes.length) lines.push("", "Budget notes:", ...playbook.budget_notes.map((note) => `  - ${note}`));
+  const limits = appliedPlaybookLimits(playbook);
+  const controls = fanoutControls(playbook);
+  if (controls.length) {
+    lines.push("", "Fanout controls:");
+    for (const control of controls) {
+      const current = limits?.[control.key] ?? control.default;
+      lines.push(`  - ${control.key}: default ${control.default}, current ${current}, max ${control.max} — ${control.description}`);
+    }
+    if (limits) lines.push(`  Override by passing limits, for example limits: ${JSON.stringify(limits)}`);
+  }
   if (playbook.risks.length) lines.push("", "Risks:", ...playbook.risks.map((risk) => `  - ${risk}`));
 
+  const runLimits = formatLimitsField(limits);
   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))} })`,
+    `Run quote: run_playbook({ slug: "${playbook.slug}", input: <input>, budget: ${Math.max(1, Math.ceil(q.estimated_cost_usd + 1))}${runLimits ? `, ${runLimits}` : ""} })`,
   );
   return lines.join("\n");
 }
@@ -260,6 +319,18 @@ function formatRunConfirmationCommand(slug: string, method: string | undefined,
 
 function formatQuoteNotes(playbook: PlaybookRecord): string[] {
   const lines: string[] = [];
+  const controls = fanoutControls(playbook);
+  if (controls.length > 0) {
+    const limits = appliedPlaybookLimits(playbook) ?? {};
+    lines.push("", "Fanout controls:");
+    for (const control of controls) {
+      const current = limits[control.key] ?? control.default;
+      lines.push(`  - ${control.key}: current ${current}, default ${control.default}, max ${control.max}`);
+    }
+    if (Object.keys(limits).length > 0) {
+      lines.push(`  Override by editing limits in the confirmation call: ${JSON.stringify(limits)}`);
+    }
+  }
   if (playbook.budget_notes.length > 0) {
     lines.push("", "Budget and fanout notes:", ...playbook.budget_notes.map((note) => `  - ${note}`));
   }
@@ -356,6 +427,39 @@ function stepInput(baseInput: Record<string, unknown>, step: PlaybookStepQuote,
   if (step.agent_slug === "scan-contract-for-risks" && !("file" in input) && input.contract) {
     input.file = input.contract;
   }
+  if (step.agent_slug === "marketing-copy-council" && !("brief" in input)) {
+    input.brief = input.product ?? input.context ?? input.text;
+  }
+  if (step.agent_slug === "write-landing-page-copy") {
+    const previousOutputs = Array.isArray(input.previous_outputs) ? input.previous_outputs : [];
+    const councilOutput = previousOutputs.find((item) => {
+      const record = item && typeof item === "object" ? item as Record<string, unknown> : null;
+      return record?.step === "council" || record?.step === "marketing-copy-council";
+    }) ?? previousOutputs[previousOutputs.length - 1];
+    const context = {
+      brief: input.brief,
+      product_slug: input.product_slug,
+      council_output: councilOutput,
+      previous_outputs: previousOutputs,
+    };
+    input.product = input.product ?? input.product_name ?? input.product_slug ?? "Landing page";
+    input.context = input.context ?? JSON.stringify(context);
+  }
+  if (step.agent_slug === "publish-html-to-a-public-url") {
+    const previousOutputs = Array.isArray(input.previous_outputs) ? input.previous_outputs : [];
+    const writerOutput = previousOutputs[previousOutputs.length - 1];
+    const outputRecord = writerOutput && typeof writerOutput === "object"
+      ? writerOutput as Record<string, unknown>
+      : null;
+    const output = outputRecord?.output && typeof outputRecord.output === "object"
+      ? outputRecord.output as Record<string, unknown>
+      : outputRecord?.output;
+    input.html = input.html
+      ?? (output && typeof output === "object" ? (output as Record<string, unknown>).html : undefined)
+      ?? (typeof output === "string" ? output : undefined)
+      ?? JSON.stringify(output ?? writerOutput ?? {});
+    input.slug = input.slug ?? input.product_slug;
+  }
   if (step.agent_slug === "place-search") {
     input.location = input.location ?? input.zip;
   }
@@ -660,7 +764,9 @@ export function registerPlaybookTools(server: McpServer): void {
             budget: effectiveBudget,
             limits: effectiveLimits,
           });
-          playbook = quoted.playbook;
+          if (quoted?.playbook) {
+            playbook = quoted.playbook;
+          }
         } catch {
           // Quote analytics should not block the user-facing quote.
         }
@@ -673,12 +779,13 @@ export function registerPlaybookTools(server: McpServer): void {
         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 runLimits = appliedPlaybookLimits(playbook) ?? effectiveLimits;
       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 });
+        pendingPlaybookRuns.set(playbook.slug, { playbook, input: effectiveInput, budget: effectiveBudget, method, limits: runLimits });
         const cheaperAlternatives = await formatCheaperAlternatives(playbook.slug, effectiveBudget);
         return text([
           `${playbook.name} quote exceeds the budget.`,
@@ -690,12 +797,12 @@ export function registerPlaybookTools(server: McpServer): void {
           ...(cheaperAlternatives ? ["", cheaperAlternatives] : []),
           "",
           `Try a higher budget or reduced limits, then call:`,
-          formatRunConfirmationCommand(playbook.slug, method, Math.ceil(estimatedCost + 1), effectiveLimits),
+          formatRunConfirmationCommand(playbook.slug, method, Math.ceil(estimatedCost + 1), runLimits),
         ].join("\n"));
       }
 
       if ((requiresSpendConfirmation() || requiresPolicyConfirmation(spendMethod, estimatedCost)) && !confirmed) {
-        pendingPlaybookRuns.set(playbook.slug, { playbook, input: effectiveInput, budget: effectiveBudget, method, limits: effectiveLimits });
+        pendingPlaybookRuns.set(playbook.slug, { playbook, input: effectiveInput, budget: effectiveBudget, method, limits: runLimits });
         return text([
           `Ready to run ${playbook.name}`,
           "",
@@ -711,7 +818,7 @@ export function registerPlaybookTools(server: McpServer): void {
           ...formatQuoteNotes(playbook),
           "",
           "To proceed, call:",
-          formatRunConfirmationCommand(playbook.slug, method, effectiveBudget, effectiveLimits),
+          formatRunConfirmationCommand(playbook.slug, method, effectiveBudget, runLimits),
           "",
           "To cancel, do nothing.",
         ].join("\n"));
@@ -762,7 +869,7 @@ export function registerPlaybookTools(server: McpServer): void {
             slug: playbook.slug,
             input: processedInput,
             budget: effectiveBudget,
-            limits: effectiveLimits,
+            limits: runLimits,
           }),
           completedStepIds: new Set<string>(),
           existingOutputs: [] as Array<{ step: string; job_id?: string; output?: unknown }>,
@@ -773,6 +880,14 @@ export function registerPlaybookTools(server: McpServer): void {
 
       let charged = runState.chargedUsd;
       const childOutputs: Array<{ step: string; job_id?: string; output?: unknown }> = [...runState.existingOutputs];
+      let linkSpendRequestId: string | undefined;
+      let linkNetworkId: string | undefined;
+      const linkApprovalContext = buildPlaybookLinkApprovalContext({
+        playbook,
+        budget: effectiveBudget,
+        stepCount: playbook.current_quote.step_count,
+        runId: runState.run_id,
+      });
 
       for (const [iteration, step] of runState.steps.entries()) {
         if (runState.completedStepIds.has(step.id)) {
@@ -824,19 +939,44 @@ export function registerPlaybookTools(server: McpServer): void {
         let schemaError: { status?: number; message?: string } | undefined;
         let usedPaidMethod = false;
         const executeChild = async (childInput: Record<string, unknown>) => {
+          const body = { input: childInput, playbook_context: playbookContext };
           try {
             return await apiPost<Record<string, unknown>>(
               `/agents/${step.agent_id}/run`,
-              { input: childInput, playbook_context: playbookContext },
+              body,
               { ensureConsumerPrincipal: true },
             );
           } catch (err) {
             const status = (err as { status?: number })?.status;
             if (status !== 402) throw err;
             usedPaidMethod = true;
+            if ((method ?? spendMethod) === "link") {
+              const linkConfig = getLinkConfig();
+              if (!linkConfig) {
+                throw new Error('Payment method "link" is not configured. Run wallet_setup({ action: "add-link" }).');
+              }
+              const challenge = (err as { headers?: Headers })?.headers?.get("www-authenticate");
+              if (!challenge && !linkNetworkId) {
+                throw new Error("Link payment challenge did not include a WWW-Authenticate header.");
+              }
+              linkNetworkId = linkNetworkId ?? await decodeMppNetworkId(challenge!);
+              linkSpendRequestId = linkSpendRequestId ?? await ensureApprovedLinkSpendRequest({
+                amount: cents(effectiveBudget),
+                currency: "usd",
+                context: linkApprovalContext,
+                expiresAt: Math.floor(Date.now() / 1000) + 3600,
+                networkId: linkNetworkId,
+                paymentMethodId: linkConfig.paymentMethodId,
+              });
+              return await apiPostWithApprovedLinkSpendRequest<Record<string, unknown>>(
+                `/agents/${step.agent_id}/run`,
+                body,
+                linkSpendRequestId,
+              );
+            }
             return await apiPostWithPayment<Record<string, unknown>>(
               `/agents/${step.agent_id}/run`,
-              { input: childInput, playbook_context: playbookContext },
+              body,
               method,
             );
           }
@@ -844,9 +984,26 @@ export function registerPlaybookTools(server: McpServer): void {
         try {
           result = await executeChild(payload);
         } catch (err) {
+          if (err instanceof LinkApprovalRequiredError) {
+            await recordStep(runState.run_id, step.id, {
+              status: "pending",
+              agent_id: step.agent_id,
+              provider_id: step.provider_id,
+              consumption_mode: "not_charged",
+              error_code: null,
+              failure_message: null,
+            });
+            await updateRun(runState.run_id, {
+              status: "paused",
+              error_code: "LINK_APPROVAL_REQUIRED",
+              failure_message: "Approve the Link spend request, then resume the playbook run.",
+            });
+            const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
+            return text(`${formatReceipt(receipt)}\n\n${err.message}`);
+          }
           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 ?? "");
+          const validationFailed = (apiErr?.status === 400 || apiErr?.status === 422)
+            && /missing required field|validation failed|invalid input|schema|provide at least one/i.test(apiErr.message ?? "");
           if (validationFailed) {
             try {
               const agent = await apiGet<AgentSchemaDetails>(`/agents/${step.agent_id}`);
@@ -906,15 +1063,10 @@ export function registerPlaybookTools(server: McpServer): void {
         }
 
         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;
@@ -1020,14 +1172,16 @@ export function registerPlaybookTools(server: McpServer): void {
       });
       const receipt = await apiGet<PlaybookRunReceipt>(`/playbook-runs/${runState.run_id}`);
       pendingPlaybookRuns.delete(playbook.slug);
+      if ((method ?? spendMethod) === "link" && linkSpendRequestId) {
+        setPendingLinkSpendRequest(null);
+      }
 
       const runBlocks = childOutputs.length > 0
         ? childOutputs.map((item) => item.output ? formatRunResult({ status: "success", job_id: item.job_id, output: item.output }, { paymentMethod: method }) : "").filter(Boolean)
         : [];
       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: "..." })."`,
+        ...runBlocks
       );
     },
   );
@@ -1053,39 +1207,6 @@ export function registerPlaybookTools(server: McpServer): void {
     },
   );
 
-  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.",