@fluxa-pay/planner 0.2.3 → 0.2.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fluxa-pay/planner",
-  "version": "0.2.3",
-  "description": "FluxA Planner CLI. Recommend the right models, APIs and skills for a task, run paid calls via x402, and manage your oneshot APIs.",
+  "version": "0.2.5",
+  "description": "FluxA Planner CLI. Recommend the right models, APIs and skills for a task, and manage your oneshot APIs.",
   "type": "module",
   "bin": {
     "planner": "planner.mjs"
@@ -10,7 +10,8 @@
     "node": ">=20"
   },
   "files": [
-    "planner.mjs"
+    "planner.mjs",
+    "plan-format.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/plan-format.mjs

@@ -0,0 +1,49 @@
+// Pure formatting of a `planner plan` result into terminal lines. No I/O and no
+// color of its own — the caller passes a helpers bag (h) so planner.mjs injects
+// ANSI while tests pass identity helpers and assert on plain text.
+//
+// When the plan carries capability `groups`, each capability prints its options
+// (the recommended one first, tagged) so the agent sees the alternatives. Older
+// / template plans without groups fall back to the flat `tools` list.
+export function planLines(plan, h) {
+  const lines = [];
+  const heading = h.unesc(plan.reason || plan.task || "Recommended");
+  lines.push("");
+  lines.push("  " + h.bold("Recommended") + "  " + h.dim(heading));
+
+  const groups = Array.isArray(plan.groups) ? plan.groups : null;
+  let total = 0;
+
+  if (groups && groups.length) {
+    for (const g of groups) {
+      lines.push("  " + h.dim(h.unesc(g.capability || "")));
+      const lead = g.options.find((o) => o.recommended) || g.options[0];
+      const ordered = lead ? [lead, ...g.options.filter((o) => o !== lead)] : g.options;
+      if (lead) total += lead.units || 0;
+      for (const o of ordered) {
+        const k = h.kind(o.kind);
+        const tag = o === lead ? "  " + h.lime("recommended") : "";
+        lines.push(
+          `    ${k}  ${h.bold(h.pad(o.slug, 34))} ${h.dim(h.pad(h.unesc(o.detail || ""), 24))} ${h.lime("~" + (o.units || 0).toLocaleString() + " Units")}${tag}`,
+        );
+      }
+    }
+  } else {
+    for (const t of plan.tools || []) {
+      total += t.units || 0;
+      const k = h.kind(t.kind);
+      lines.push(
+        `    ${k}  ${h.bold(h.pad(t.slug, 36))} ${h.dim(h.pad(h.unesc(t.detail || ""), 30))} ${h.lime("~" + (t.units || 0).toLocaleString() + " Units")}`,
+      );
+    }
+  }
+
+  lines.push(h.gray("    " + "─".repeat(78)));
+  lines.push(`    ${h.bold("est")} ${h.lime("~" + total.toLocaleString() + " Units")} ${h.dim("(~" + h.usd(total) + ")")}`);
+  if (plan.instructions) {
+    lines.push("");
+    lines.push("  " + h.dim(h.unesc(plan.instructions)));
+  }
+  lines.push(h.dim("\n  → Run these yourself. Paid endpoints answer HTTP 402; settle with fluxa-wallet (planner info pay)."));
+  return { lines, total };
+}

package/planner.mjs

@@ -26,6 +26,7 @@ import { promisify } from "node:util";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { stdout, argv, env, exit } from "node:process";
+import { planLines } from "./plan-format.mjs";
 
 const pexec = promisify(execFile);
 
@@ -281,12 +282,9 @@ async function keysRevoke(id) {
   console.log(c.green("✓") + ` revoked ${id} — it stops authenticating on its next call`);
 }
 
-// --- paid call (the x402 v3 dance, wrapped) ---------------------------------
-// `planner call <url>` collapses the 10-step manual flow into one command:
-// register → discover → ensure a signed mandate → call → on 402 settle via
-// `fluxa-wallet x402-v3` → retry with the payment token → return the raw body.
-// Signing the mandate is the one human step; planner reuses a signed, unexpired
-// mandate so you sign once per budget window, not once per call.
+// --- wallet helpers (x402 v3 settlement, shared by topup) --------------------
+// The wallet CLI does the signing; planner reuses a signed, unexpired mandate so
+// the user signs once per budget window, not once per settlement.
 async function walletRaw(args) {
   const { stdout: out } = await pexec("fluxa-wallet", args);
   return out;
@@ -319,39 +317,6 @@ async function rawCall(url, method, data, extraHeaders = {}, auth = false) {
   return { status: res.status, text };
 }
 
-// The proxy's API/MCP lanes bill the caller identified by the X-Agent-ID header
-// and reject every non-discovery request without it. Default to the agent_id
-// (UUID) from `fluxa-wallet status`; configs with require_agent_auth need a JWT
-// instead, so agentCall() retries with a freshly minted wallet JWT on the
-// "valid JWT" 401. Both values are cached for the process.
-let _agentId = null;
-async function agentId() {
-  if (_agentId) return _agentId;
-  const s = unwrap(await walletJson(["status"]).catch(() => ({})));
-  const id = s.agent_id || s.agentId || s.id;
-  if (!id) die("could not read agent_id from `fluxa-wallet status` — register once with `fluxa-wallet init`.");
-  return (_agentId = id);
-}
-let _walletJwt = null;
-async function walletJwt() {
-  if (_walletJwt) return _walletJwt;
-  const j = unwrap(await walletJson(["refreshJWT"]).catch(() => ({})));
-  const jwt = j.jwt || j.token;
-  if (!jwt) die("could not mint a wallet JWT (`fluxa-wallet refreshJWT`).");
-  return (_walletJwt = jwt);
-}
-// rawCall + X-Agent-ID, with the UUID→JWT fallback for require_agent_auth configs.
-// Auto-attached headers go FIRST so a caller-supplied `extra` (e.g. a user's
-// `--header "X-Agent-ID: …"`) can override — collisions are surfaced upstream
-// in cmdCall so the override isn't silent.
-async function agentCall(url, method, data, extra = {}) {
-  const r = await rawCall(url, method, data, { "X-Agent-ID": await agentId(), ...extra });
-  if (r.status === 401 && /valid JWT/i.test(r.text)) {
-    return rawCall(url, method, data, { "X-Agent-ID": await walletJwt(), ...extra });
-  }
-  return r;
-}
-
 async function ensureMandate(currency, budget, seconds, url) {
   const cfg = loadConfig();
   // only reuse a signed mandate of the SAME currency with budget left
@@ -381,101 +346,7 @@ async function ensureMandate(currency, budget, seconds, url) {
     const mm = s.mandate || s;
     if (mm && mm.status === "signed") { console.error(c.green("  ✓ mandate signed")); return mandateId; }
   }
-  die("mandate not signed in time — re-run `planner call` once you've approved the link.");
-}
-
-function descriptorEndpoints(text) {
-  try { const j = JSON.parse(text); if (j && Array.isArray(j.endpoints)) return j; } catch {}
-  return null;
-}
-
-async function cmdCall(url, opts = {}) {
-  if (!url) {
-    return die("usage: planner call <url|slug> [--endpoint <path>] [--data '<json>'] [--header 'K: V']… [--pay credits|usdc] [--method GET|POST] [--budget <units>] [--raw]");
-  }
-  // accept a bare AgentMarket slug (e.g. `web-search-api`) → the proxy API base.
-  // full http(s) URLs are used as-is.
-  if (!/^https?:\/\//.test(url)) url = `${PROXY}/api/${encodeURIComponent(url)}`;
-  const pay = (opts.pay || loadConfig().pay || "credits").toLowerCase();
-  const currency = pay === "usdc" ? "USDC" : "FLUXA_MONETIZE_CREDITS";
-  const budget = opts.budget ? Number(opts.budget) : (pay === "usdc" ? 5000000 : 500); // ~$5 default
-  const seconds = opts.seconds ? Number(opts.seconds) : 28800; // 8h
-
-  // user-supplied request headers (repeatable --header "K: V") are merged
-  // into every outbound call below. A user value wins over the auto-attached
-  // X-Agent-ID; X-Payment is the one exception, see the retry step. We warn
-  // up front when a user header would override an auto-attached one so the
-  // override isn't silent.
-  const userHeaders = opts.headers || {};
-  const reservedNames = ["x-agent-id", "x-payment"];
-  for (const k of Object.keys(userHeaders)) {
-    if (reservedNames.includes(k.toLowerCase())) {
-      console.error(c.dim(`! --header ${k} overrides the auto-attached value`));
-    }
-  }
-
-  await ensureAgent();
-
-  let targetUrl = url;
-  let method = (opts.method || (opts.data ? "POST" : "GET")).toUpperCase();
-  const data = opts.data;
-
-  // proxy endpoints are two-level: GET <base> returns a descriptor listing the
-  // real paid sub-endpoints. Resolve it (unless --raw) so the agent doesn't have
-  // to read the catalog itself. We never spend without a supplied body.
-  if (!opts.raw) {
-    const probe = await agentCall(url, "GET", undefined, userHeaders);
-    const desc = probe.status === 200 ? descriptorEndpoints(probe.text) : null;
-    if (desc) {
-      const eps = desc.endpoints.filter((e) => e.enabled !== false);
-      const norm = (p) => "/" + String(p || "").replace(/^\//, "");
-      let ep = opts.endpoint ? eps.find((e) => norm(e.path) === norm(opts.endpoint)) : null;
-      if (!ep) {
-        const paid = eps.filter((e) => Number(e.price || 0) > 0);
-        ep = paid.length === 1 ? paid[0] : null;
-      }
-      if (!ep) {
-        console.error(c.bold(`\n  ${desc.name || "endpoint"}`) + c.dim(" — pick one with --endpoint <path>:"));
-        for (const e of eps) {
-          console.error(`    ${pad(e.method || "GET", 5)} ${c.bold(pad(e.path, 22))} ${c.lime(pad(e.price ? `${e.price} ${e.currency || ""}` : "free", 12))} ${c.gray(e.description || "")}`);
-        }
-        return;
-      }
-      targetUrl = url.replace(/\/$/, "") + norm(ep.path);
-      method = opts.method ? opts.method.toUpperCase() : (ep.method || "GET").toUpperCase();
-      const bodyFields = ep.inputSchema && Array.isArray(ep.inputSchema.bodyFields) ? ep.inputSchema.bodyFields : [];
-      if (bodyFields.length > 0 && !data) {
-        console.error(c.bold(`\n  ${method} ${norm(ep.path)}`) + c.dim(`  ${ep.price ? `${ep.price} ${ep.currency || ""}` : "free"}`));
-        console.error(c.dim("  needs a JSON body — pass it with --data '<json>'. Expected shape:"));
-        const ex = bodyFields[0]?.description;
-        if (ex) console.error(c.gray("    " + String(ex).replace(/\n/g, "\n    ")));
-        return;
-      }
-    }
-  }
-
-  // call the resolved endpoint — pay if it answers 402
-  let r = await agentCall(targetUrl, method, data, userHeaders);
-  if (r.status !== 402) {
-    if (r.status >= 400) die(`${r.status} — ${r.text.slice(0, 300)}`);
-    return console.log(r.text); // raw body, no post-processing
-  }
-
-  console.error(c.dim(`· 402 Payment Required — settling via x402 v3 (${currency})`));
-  const mandateId = await ensureMandate(currency, budget, seconds, targetUrl);
-
-  // 2. sign the payment for this exact 402 challenge (pass the FULL body)
-  const paid = unwrap(await walletJson(["x402-v3", "--mandate", mandateId, "--payload", r.text]));
-  const xPayment = paid.xPaymentB64 || paid.xPayment;
-  if (!xPayment) die("x402-v3 did not return a payment token (xPaymentB64).");
-
-  // 3. retry with the payment token (against the resolved endpoint, with
-  // X-Agent-ID + user headers). The freshly-minted X-Payment is appended
-  // LAST so it wins over any user-supplied X-Payment — preserving the x402
-  // settlement that the CLI just signed for this exact 402 challenge.
-  r = await agentCall(targetUrl, method, opts.data, { ...userHeaders, "X-Payment": xPayment });
-  if (r.status >= 400) die(`paid retry failed: ${r.status} — ${r.text.slice(0, 300)}`);
-  console.log(r.text); // raw body, no post-processing
+  die("mandate not signed in time — re-run once you've approved the link.");
 }
 
 // --- topup (prepay Units to a merchant) -------------------------------------
@@ -577,7 +448,7 @@ async function cmdApiCreate(opts) {
   if (data.proxyUrl) console.log(c.dim(`  proxy: ${data.proxyUrl}`));
   console.log(c.dim(
     data.status === "published"
-      ? `  test it:  planner call ${data.proxyUrl || data.slug}`
+      ? `  test it:  curl ${data.proxyUrl || `${PROXY}/api/${data.slug}`}`
       : `  publish:  planner api edit ${data.slug || data.configId} --publish`,
   ));
 }
@@ -649,19 +520,12 @@ function printAnswer(a) {
 
 // Render a PlanOrAnswer plan: tools carry kind/slug/name/units/detail.
 function printPlan(plan) {
-  const tools = plan.tools || [];
-  const heading = unesc(plan.reason || plan.task || "Recommended");
-  console.log("\n  " + c.bold("Recommended") + "  " + c.dim(heading));
-  let total = 0;
-  for (const t of tools) {
-    const k = KIND[t.kind] || pad(t.kind, 5);
-    total += t.units || 0;
-    console.log(`    ${k}  ${c.bold(pad(t.slug, 36))} ${c.dim(pad(unesc(t.detail || ""), 30))} ${c.lime("~" + (t.units || 0).toLocaleString() + " Units")}`);
-  }
-  console.log(c.gray("    " + "─".repeat(78)));
-  console.log(`    ${c.bold("est")} ${c.lime("~" + total.toLocaleString() + " Units")} ${c.dim("(~" + usd(total) + ")")}`);
-  if (plan.instructions) console.log("\n  " + c.dim(unesc(plan.instructions)));
-  console.log(c.dim("\n  → call these tools directly — FluxA settles each paid call from your wallet. No keys, no subs."));
+  const { lines, total } = planLines(plan, {
+    bold: c.bold, dim: c.dim, lime: c.lime, gray: c.gray,
+    kind: (k) => KIND[k] || pad(k, 5),
+    pad, usd, unesc,
+  });
+  for (const l of lines) console.log(l);
   return total;
 }
 
@@ -683,15 +547,14 @@ ${c.bold("planner")} ${c.dim("— what you're working with")}
     Balances are ${c.bold("per merchant")} (prepaid Units). ${c.cyan("planner topup <merchant>")} to prefund.
 
   ${c.bold("Paying (x402)")}
-    A paid call returns HTTP 402 → planner settles it via ${c.dim("fluxa-wallet")} inside a spending
-    mandate you sign once (budget + window), then reuses it. planner never holds keys.
+    A paid call returns HTTP 402 → settle it with the ${c.dim("fluxa-wallet")} CLI inside a spending
+    mandate you sign once (budget + window), then reuse it. ${c.cyan("planner topup")} prefunds instead.
 
   ${c.bold("Auth")}  an ${c.dim("fxa_live_")} key OR an auto-minted agent VC. Nothing to log in.
   ${c.bold("Bases")} platform ${c.dim(new URL(PLATFORM).host)} · proxy ${c.dim(new URL(PROXY).host)}
 
   ${c.bold("Commands")}
     ${c.cyan('plan "<task>"')}           recommend tools for a task
-    ${c.cyan("call <url> --data '…'")}   make one paid API call (handles the 402)
     ${c.cyan("topup <merchant>")}        prepay Units
     ${c.cyan('search "<q>"')}            discover apis/models/skills
     ${c.dim("models · balance · ledger · keys · whoami")}
@@ -729,19 +592,21 @@ ${c.bold("API keys — programmatic management")} ${c.dim("(Agent VC only)")}
   pay: () => `
 ${c.bold("Paying — x402 v3")}
   Prepaid: each merchant has a Units balance; while it's funded, calls just work.
-  On a shortfall a paid endpoint returns HTTP 402 with an x402 challenge. planner then:
-    1. ensures a signed spending ${c.bold("mandate")} (you pre-approve a budget + time window — once)
-    2. signs the 402 via ${c.dim("fluxa-wallet x402-v3")} (planner never holds keys)
-    3. retries with the payment token
-  It reuses the signed mandate for later calls in its window. ${c.cyan("planner topup")} prefunds instead.
+  On a shortfall a paid endpoint returns HTTP 402 with an x402 challenge. Settle it with
+  the ${c.dim("fluxa-wallet")} CLI:
+    1. sign a spending ${c.bold("mandate")} once (you pre-approve a budget + time window)
+       ${c.dim("fluxa-wallet mandate-create --amount <units> --seconds <ttl> --currency <…>")}
+    2. settle the 402 challenge  ${c.dim("fluxa-wallet x402-v3 --mandate <id> --payload <402 body>")}
+    3. retry the call with the returned payment token in the ${c.dim("X-Payment")} header
+  Reuse the signed mandate for later calls in its window. ${c.cyan("planner topup")} prefunds instead.
 `,
   apis: () => `
 ${c.bold("Oneshot APIs")}
   ${c.dim("/api/{config}")} is two-level: ${c.dim("GET <base>")} returns a descriptor of sub-endpoints
   (path, method, price, input schema). The paid action is a sub-endpoint.
-    ${c.cyan("planner call <base>")}                 show the paid endpoint + its required body
-    ${c.cyan("planner call <base> --data '<json>'")} call it; pay the 402 if needed
-  ${c.dim("--endpoint <path>")} picks when there are several; ${c.dim("--raw")} hits a URL directly.
+    ${c.dim(`curl ${new URL(PROXY).host}/api/<slug>`)}   list the sub-endpoints + their input schema
+  Call a sub-endpoint; on a 402, settle with ${c.dim("fluxa-wallet")} (see ${c.cyan("planner info pay")}) and
+  retry with the ${c.dim("X-Payment")} token. ${c.dim("X-Agent-ID")} is optional (attribution only).
   ${c.bold("Manage your APIs")} ${c.dim("(fxa_live_ key or auto-minted Agent VC)")}
     ${c.cyan("planner api create --file <spec.json> [--publish]")}   create (draft unless --publish)
     ${c.cyan("planner api list")}                                    your api configs
@@ -781,9 +646,7 @@ ${c.bold("planner")} ${c.dim("— FluxA Planner CLI (live)")}
 
 ${c.bold("Headline")}
   planner plan "<task>"     recommend the models, APIs & skills for a task
-  planner call <url>        make a paid API call — handles the x402 mandate + payment
-                            [--pay credits|usdc] [--method GET|POST] [--data '<json>']
-                            [--header "Name: Value"]  (repeatable; e.g. an upstream Bearer token)
+                            (run the recommended calls yourself; pay 402s via fluxa-wallet)
 
 ${c.bold("Primitives")}  ${c.dim("(all live)")}
   planner search "<q>" [--type api,skill,model]   discover resources
@@ -811,31 +674,9 @@ function die(msg, ctx) {
 async function main() {
   const args = argv.slice(2);
   const cmd = args[0];
-  const FLAGS = ["--type", "--vendor", "--pay", "--method", "--data", "--budget", "--seconds", "--endpoint", "--credits", "--bundle", "--name", "--cap", "--file", "--upstream", "--wallet", "--header"];
-  const BOOLS = ["--raw", "--publish", "--private", "--require-agent-auth", "--dry-run"];
+  const FLAGS = ["--type", "--vendor", "--budget", "--seconds", "--credits", "--bundle", "--name", "--cap", "--file", "--upstream", "--wallet"];
+  const BOOLS = ["--publish", "--private", "--require-agent-auth", "--dry-run"];
   const getFlag = (n) => { const i = args.indexOf(n); return i !== -1 ? args[i + 1] : null; };
-  // repeatable flag → array of all values (in order)
-  const getFlagAll = (n) => {
-    const out = [];
-    for (let i = 0; i < args.length - 1; i++) if (args[i] === n) out.push(args[i + 1]);
-    return out;
-  };
-  // parse `--header "Name: Value"` (repeatable) into a headers object. Splits
-  // on the FIRST colon so JWTs/URLs in the value are preserved. Malformed
-  // entries are warned and skipped, never thrown — a broken header shouldn't
-  // poison the whole call.
-  const parseHeaders = (specs) => {
-    const out = {};
-    for (const s of specs) {
-      const i = s.indexOf(":");
-      if (i <= 0) { console.error(c.dim(`! ignoring malformed --header "${s}" (expected "Name: Value")`)); continue; }
-      const name = s.slice(0, i).trim();
-      const value = s.slice(i + 1).trim();
-      if (!name) continue;
-      out[name] = value;
-    }
-    return out;
-  };
   const type = getFlag("--type");
   const vendor = getFlag("--vendor");
   const rest = [];
@@ -848,13 +689,6 @@ async function main() {
 
   switch (cmd) {
     case "plan": return cmdPlan(arg);
-    case "call":
-      return cmdCall(rest[0], {
-        pay: getFlag("--pay"), method: getFlag("--method"), data: getFlag("--data"),
-        budget: getFlag("--budget"), seconds: getFlag("--seconds"),
-        endpoint: getFlag("--endpoint"), raw: args.includes("--raw"),
-        headers: parseHeaders(getFlagAll("--header")),
-      });
     case "search": return cmdSearch(arg, type);
     case "models": return cmdModels(vendor);
     case "vendors": return cmdVendors();