@fluxa-pay/planner 0.1.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@fluxa-pay/planner",
+  "version": "0.1.0",
+  "description": "FluxA Planner CLI — recommend the right models/APIs/skills for a task, and run paid calls via x402.",
+  "type": "module",
+  "bin": {
+    "planner": "planner.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "planner.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/planner.mjs

@@ -0,0 +1,669 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// planner — FluxA Planner CLI  (LIVE — talks to the real platform)
+//
+// Zero-dependency Node ESM (Node 20+). Nothing to install.
+//   node cli/planner.mjs <command>
+//
+// Config (env or ~/.fluxa/config.json):
+//   FLUXA_KEY        fxa_live_… API key (create at monetize.fluxapay.xyz/keys)
+//   FLUXA_PLATFORM   default https://monetize.fluxapay.xyz   (discovery, models)
+//   FLUXA_PROXY      default https://proxy-monetize.fluxapay.xyz (wallet, llm)
+//
+// The planner RECOMMENDS — it does not execute or pay. `plan` returns the
+// recommended models/APIs/skills + an estimated budget. It stops there: the
+// agent that called planner executes by hitting those endpoints itself, and
+// FluxA settles each paid call. The planner never calls those APIs or spends Units.
+//
+// What's live:
+//   search · models · balance · ledger · whoami   → real read-only HTTP
+//   plan                                           → calls the server-side /api/planner/plan
+// ---------------------------------------------------------------------------
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { stdout, argv, env, exit } from "node:process";
+
+const pexec = promisify(execFile);
+
+const PLATFORM = (env.FLUXA_PLATFORM || "https://monetize.fluxapay.xyz").replace(/\/$/, "");
+const PROXY = (env.FLUXA_PROXY || "https://proxy-monetize.fluxapay.xyz").replace(/\/$/, "");
+const AGENTID = (env.FLUXA_AGENTID || "https://agentid.fluxapay.xyz").replace(/\/$/, "");
+const CONFIG = join(homedir(), ".fluxa", "config.json");
+const UNIT_USD = 0.00001;
+
+// --- ANSI -------------------------------------------------------------------
+const tty = stdout.isTTY;
+const sgr = (n) => (s) => (tty ? `\x1b[${n}m${s}\x1b[0m` : String(s));
+const c = {
+  dim: sgr(2), bold: sgr(1),
+  lime: sgr("38;2;166;224;0"), green: sgr("38;2;87;200;120"),
+  red: sgr("38;2;229;96;77"), cyan: sgr("36"), gray: sgr("90"),
+};
+const KIND = { model: c.cyan("model"), api: c.lime("api  "), skill: c.green("skill") };
+const pad = (s, n) => { s = String(s); return s.length > n ? s.slice(0, n - 1) + "…" : s.padEnd(n); };
+const usd = (units) => { const v = (units || 0) * UNIT_USD; return v < 0.01 ? `$${v.toFixed(4)}` : `$${v.toFixed(2)}`; };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// --- config / auth ----------------------------------------------------------
+function loadConfig() {
+  try { return JSON.parse(readFileSync(CONFIG, "utf8")) || {}; } catch { return {}; }
+}
+function saveConfig(patch) {
+  mkdirSync(join(homedir(), ".fluxa"), { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify({ ...loadConfig(), ...patch }, null, 2));
+}
+function loadKey() {
+  if (env.FLUXA_KEY) return env.FLUXA_KEY;
+  return loadConfig().key || null;
+}
+function saveKey(key) { saveConfig({ key }); }
+// Auth token: prefer an fxa_live_ key (env/config); otherwise auto-mint a
+// short-lived Agent VC via the local fluxa-wallet CLI. Both are accepted by the
+// proxy's credential resolver (Bearer fxa_live_… or Bearer <agent_vc>).
+// Mint a short-lived Agent VC: get the AgentID login JWT from the local
+// fluxa-wallet, then have the AgentID service ISSUE the VC. Note: the
+// `fluxa-wallet agent-vc` subcommand signs locally with a dev key the proxy
+// can't verify — you must use the AgentID issue endpoint instead.
+async function mintVcOnce() {
+  const { stdout: out } = await pexec("fluxa-wallet", ["refreshJWT"]);
+  const jwt = JSON.parse(out.slice(out.indexOf("{")))?.data?.jwt;
+  if (!jwt) throw new Error("no AgentID JWT from fluxa-wallet");
+  const r = await fetch(`${AGENTID}/agent/vc/issue`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${jwt}`, "content-type": "application/json" },
+    body: JSON.stringify({ challenge: "wallet-user-info-lookup", ttl_seconds: 300, audience: "fluxa-wallet-service" }),
+  });
+  const j = await r.json().catch(() => ({}));
+  const vc = j.vc || j?.data?.vc;
+  if (!vc) throw new Error(`AgentID issue ${r.status}`);
+  return vc;
+}
+let _token = null;
+async function authToken() {
+  if (_token) return _token;
+  const k = loadKey();
+  if (k) return (_token = k);
+  let lastErr;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const vc = await mintVcOnce();
+      console.error(c.dim(`· authed via agent VC (${new URL(AGENTID).host})`));
+      return (_token = vc);
+    } catch (e) { lastErr = e; }
+  }
+  die(`could not mint an agent VC (${lastErr?.message}). Set FLUXA_KEY=fxa_live_…, run \`planner login <key>\`, or check fluxa-wallet (\`fluxa-wallet status\`).`);
+}
+// Force an Agent VC, ignoring any fxa_live_ key. Key-management endpoints reject
+// a metered key with 403 (a leaked key must not mint uncapped siblings or revoke
+// others), so `planner keys …` always authenticates with a freshly minted VC.
+let _vc = null;
+async function vcToken() {
+  if (_vc) return _vc;
+  let lastErr;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const vc = await mintVcOnce();
+      console.error(c.dim(`· key mgmt authed via agent VC (${new URL(AGENTID).host})`));
+      return (_vc = vc);
+    } catch (e) { lastErr = e; }
+  }
+  die(`could not mint an agent VC (${lastErr?.message}). Key management needs a VC, not an fxa_live_ key — check fluxa-wallet (\`fluxa-wallet status\`).`);
+}
+
+// --- http -------------------------------------------------------------------
+async function http(url, { method = "GET", auth = false, body, accept = "application/json", timeout = 20000 } = {}) {
+  const headers = { accept };
+  // auth: true → fxa_live_ key if present else a VC; "vc" → always a VC (key mgmt).
+  if (auth === "vc") headers.authorization = `Bearer ${await vcToken()}`;
+  else if (auth) headers.authorization = `Bearer ${await authToken()}`;
+  if (body !== undefined) { headers["content-type"] = "application/json"; body = JSON.stringify(body); }
+  const ctrl = new AbortController();
+  const to = setTimeout(() => ctrl.abort(), timeout);
+  let res;
+  try {
+    res = await fetch(url, { method, headers, body, signal: ctrl.signal });
+  } catch (e) {
+    clearTimeout(to);
+    die(`network error reaching ${new URL(url).host}: ${e.message}`);
+  }
+  clearTimeout(to);
+  const text = await res.text();
+  let data; try { data = JSON.parse(text); } catch { data = text; }
+  if (!res.ok) {
+    const msg = (data && data.error) || (data && data.hint) || (typeof data === "string" ? data.slice(0, 200) : res.statusText);
+    die(`${res.status} ${res.statusText} — ${msg}`, { res, data });
+  }
+  return { data, res };
+}
+
+// --- commands ---------------------------------------------------------------
+async function cmdLogin(key) {
+  if (!key || !key.startsWith("fxa_")) return die('usage: planner login <fxa_live_…>');
+  saveKey(key);
+  console.log(c.green("✓") + ` saved key to ${CONFIG}`);
+  await cmdWhoami();
+}
+
+async function cmdWhoami() {
+  const { data } = await http(`${PROXY}/llm/wallet/balances`, { auth: true });
+  const n = (data.accounts || []).length;
+  console.log(c.green("✓") + ` authenticated · ${n} merchant account${n === 1 ? "" : "s"}`);
+}
+
+async function cmdSearch(query, type) {
+  const u = new URL(`${PLATFORM}/api/discover`);
+  u.searchParams.set("type", type || "api,skill,model");
+  if (query) u.searchParams.set("q", query);
+  const { data } = await http(u);
+  const rows = [
+    ...(data.apiServers || []).map((r) => ({ kind: "api", slug: r.slug, desc: r.description || "", price: r.priceUsd ? (r.priceUsd.min === r.priceUsd.max ? `$${r.priceUsd.min}` : `$${r.priceUsd.min}-${r.priceUsd.max}`) : "" })),
+    ...(data.skills || []).map((r) => ({ kind: "skill", slug: r.slug, desc: r.description || "", price: "" })),
+    ...(data.models || []).map((r) => ({ kind: "model", slug: `${r.provider}/${r.id}`, desc: r.displayName || "", price: r.inputUnitsPer1M != null ? `${r.inputUnitsPer1M.toLocaleString()}u/Mtok in` : "" })),
+  ];
+  if (!rows.length) return console.log(c.dim("  no matches" + (query ? ` for "${query}"` : "")));
+  console.log(c.dim(`  ${rows.length} result${rows.length === 1 ? "" : "s"} · ${PLATFORM}/api/discover`));
+  for (const r of rows) console.log(`  ${KIND[r.kind]}  ${c.bold(pad(r.slug, 28))} ${c.gray(pad(r.desc, 42))} ${c.dim(r.price)}`);
+}
+
+async function cmdModels(vendor) {
+  const u = new URL(`${PLATFORM}/api/llm/models`);
+  if (vendor) u.searchParams.set("vendor", vendor);
+  const { data } = await http(u);
+  const models = data.models || [];
+  if (!models.length) return console.log(c.dim("  no models"));
+  for (const m of models) {
+    const inU = m.rates_units_per_mtok?.input_tokens, outU = m.rates_units_per_mtok?.output_tokens;
+    console.log(`  ${c.bold(pad(`${m.provider}/${m.id}`, 32))} ${c.gray(pad(m.display_name || "", 26))} ${c.dim(`${inU ?? "?"}/${outU ?? "?"} Units/Mtok in/out`)}`);
+  }
+}
+
+async function cmdBalance(vendor) {
+  const url = vendor ? `${PROXY}/llm/wallet/balances/${vendor}` : `${PROXY}/llm/wallet/balances`;
+  const { data } = await http(url, { auth: true });
+  const accounts = vendor ? [data] : (data.accounts || []);
+  if (!accounts.length) return console.log(c.dim("  no merchant balances yet — `planner topup <vendor>` to start"));
+  console.log("  " + c.dim(pad("merchant", 16) + pad("balance", 18) + pad("≈ USD", 12) + pad("7d/day", 12) + "status"));
+  for (const a of accounts) {
+    const low = a.balance < (a.burn7dPerDay || 0) * 3;
+    const status = a.balance < 0 ? c.red("owed " + usd(-a.balance)) : low ? c.red("low") : c.green("ok");
+    console.log(`  ${pad(a.merchant, 16)}${pad((a.balance ?? 0).toLocaleString() + " Units", 18)}${pad(usd(a.balance), 12)}${pad((a.burn7dPerDay ?? 0).toLocaleString(), 12)}${status}`);
+  }
+}
+
+async function cmdLedger(vendor) {
+  if (!vendor) return die("usage: planner ledger <vendor>");
+  const { data } = await http(`${PROXY}/llm/wallet/ledger/${vendor}?limit=20`, { auth: true });
+  const entries = data.entries || [];
+  if (!entries.length) return console.log(c.dim("  no ledger entries for " + vendor));
+  console.log("  " + c.dim(pad("when", 22) + pad("type", 12) + pad("amount", 14) + "balance after"));
+  for (const e of entries) {
+    const amt = (e.amount > 0 ? c.green("+") : c.red("")) + e.amount.toLocaleString();
+    console.log(`  ${pad(new Date(e.ts).toISOString().replace("T", " ").slice(0, 19), 22)}${pad(e.type, 12)}${pad(amt, 14 + (tty ? 9 : 0))}${(e.balanceAfter ?? "").toLocaleString()}`);
+  }
+}
+
+// --- api key management (Agent-VC only) -------------------------------------
+// Provision and rotate the user's fxa_live_ keys programmatically: an agent can
+// hand a fresh, capped key to a sub-process without the human minting one by
+// hand. All four endpoints REQUIRE an Agent VC (a metered fxa_live_ key is 403'd
+// so a leaked key can't mint uncapped siblings or revoke others) and are scoped
+// to the VC owner — so they always auth via `auth: "vc"`.
+const capLabel = (mc) => (mc == null || mc <= 0 ? c.dim("uncapped") : `${mc} MC`);
+
+async function cmdKeys(sub, rest, opts) {
+  switch (sub || "list") {
+    case "list": case "ls": return keysList();
+    case "create": case "new": case "add": return keysCreate(opts);
+    case "update": case "set": return keysUpdate(rest[0], opts);
+    case "revoke": case "rm": case "delete": return keysRevoke(rest[0]);
+    default: return die(`unknown: planner keys ${sub}\n  keys list | create | update <id> | revoke <id>`);
+  }
+}
+
+async function keysList() {
+  const { data } = await http(`${PROXY}/llm/keys`, { auth: "vc" });
+  const keys = data.keys || [];
+  if (!keys.length) return console.log(c.dim("  no API keys yet — `planner keys create` to mint one"));
+  // ids are full UUIDs (never truncated — you need them for update/revoke)
+  console.log("  " + c.dim(pad("id", 38) + pad("name", 16) + pad("prefix", 16) + pad("cap", 11) + pad("spent", 11) + "status"));
+  for (const k of keys) {
+    const status = k.revokedAt ? c.red("revoked") : c.green("active");
+    console.log(`  ${pad(k.id, 38)}${pad(k.name || "—", 16)}${pad(k.keyPrefix || "", 16)}${pad(capLabel(k.spendCapCredits), 11)}${pad((k.spentCredits ?? 0) + " MC", 11)}${status}`);
+  }
+}
+
+async function keysCreate(opts) {
+  const body = {};
+  if (opts.name) body.name = opts.name;
+  if (opts.cap != null) body.spendCapCredits = Number(opts.cap);
+  const { data } = await http(`${PROXY}/llm/keys`, { method: "POST", auth: "vc", body });
+  console.log(c.green("✓") + ` created key ${c.bold(data.name || data.id)} · cap ${capLabel(data.spendCapCredits)}`);
+  console.log(c.dim(`  id: ${data.id}   ${c.dim("(use it to update/revoke)")}`));
+  console.log(`\n  ${c.bold("raw key — shown once, store it now:")}\n  ${c.lime(data.rawKey)}\n`);
+  console.log(c.dim(`  use it:  planner login ${data.rawKey}   (or export FLUXA_KEY=…)`));
+}
+
+async function keysUpdate(id, opts) {
+  if (!id) return die("usage: planner keys update <id> [--name <n>] [--cap <MC>]");
+  const body = {};
+  if (opts.name != null) body.name = opts.name;
+  if (opts.cap != null) body.spendCapCredits = Number(opts.cap); // --cap 0 clears the cap
+  if (!Object.keys(body).length) return die("nothing to update — pass --name and/or --cap");
+  const { data } = await http(`${PROXY}/llm/keys/${id}`, { method: "PATCH", auth: "vc", body });
+  console.log(c.green("✓") + ` updated ${c.bold(data.name || data.id)} · cap ${capLabel(data.spendCapCredits)}`);
+}
+
+async function keysRevoke(id) {
+  if (!id) return die("usage: planner keys revoke <id>");
+  await http(`${PROXY}/llm/keys/${id}`, { method: "DELETE", auth: "vc" });
+  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.
+async function walletRaw(args) {
+  const { stdout: out } = await pexec("fluxa-wallet", args);
+  return out;
+}
+function parseWalletJson(out) {
+  const i = String(out).indexOf("{");
+  if (i < 0) return {};
+  try { return JSON.parse(String(out).slice(i)); } catch { return {}; }
+}
+async function walletJson(args) { return parseWalletJson(await walletRaw(args)); }
+const unwrap = (j) => (j && j.data) ? j.data : j; // wallet wraps some payloads in {data}
+
+async function ensureAgent() {
+  try {
+    await walletRaw(["status"]);
+  } catch {
+    die('no Agent ID — register once: `fluxa-wallet init --name "<agent>" --client "<client>"`, then retry.');
+  }
+}
+
+async function rawCall(url, method, data, extraHeaders = {}, auth = false) {
+  const headers = { accept: "application/json", ...extraHeaders };
+  if (auth) headers.authorization = `Bearer ${await authToken()}`;
+  let body;
+  if (data !== undefined && data !== null) { headers["content-type"] = "application/json"; body = data; }
+  let res;
+  try { res = await fetch(url, { method, headers, body }); }
+  catch (e) { die(`network error reaching ${new URL(url).host}: ${e.message}`); }
+  const text = await res.text();
+  return { status: res.status, text };
+}
+
+async function ensureMandate(currency, budget, seconds, url) {
+  const cfg = loadConfig();
+  // only reuse a signed mandate of the SAME currency with budget left
+  if (cfg.mandateId && cfg.mandateCurrency === currency) {
+    const m = unwrap(await walletJson(["mandate-status", "--id", cfg.mandateId]).catch(() => ({})));
+    const mm = m.mandate || m;
+    if (mm && mm.status === "signed" && Number(mm.remainingAmount ?? 0) >= budget) {
+      console.error(c.dim(`· reusing signed mandate ${cfg.mandateId} (remaining ${mm.remainingAmount})`));
+      return cfg.mandateId;
+    }
+  }
+  const host = new URL(url).host;
+  const desc = `Spend up to ${budget} for planner on ${host}`;
+  const created = unwrap(await walletJson(["mandate-create", "--desc", desc, "--amount", String(budget), "--seconds", String(seconds), "--currency", currency]));
+  const mandateId = created.mandateId || created.id;
+  const authUrl = created.authorizationUrl || created.authUrl;
+  if (!mandateId) die("mandate-create did not return a mandateId");
+  saveConfig({ mandateId, mandateCurrency: currency });
+
+  console.error(`\n  ${c.bold("Sign the spending mandate")} ${c.dim(`(budget ${budget} ${currency}, valid ${seconds}s)`)}`);
+  if (authUrl) console.error(`  ${c.cyan(authUrl)}`);
+  console.error(c.dim("  open the link, approve, then this continues automatically…\n"));
+
+  for (let i = 0; i < 60; i++) {
+    await sleep(2000);
+    const s = unwrap(await walletJson(["mandate-status", "--id", mandateId]).catch(() => ({})));
+    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 || !/^https?:\/\//.test(url)) {
+    return die("usage: planner call <url> [--endpoint <path>] [--data '<json>'] [--pay credits|usdc] [--method GET|POST] [--budget <units>] [--raw]");
+  }
+  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
+
+  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 rawCall(url, "GET");
+    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 rawCall(targetUrl, method, data);
+  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
+  r = await rawCall(url, method, opts.data, { "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
+}
+
+// --- topup (prepay Units to a merchant) -------------------------------------
+// `POST /llm/topup/initiate` (authed) returns a 402 with an orderId + a
+// `resource` finalize URL; pay it in Monetize Credits via the wallet, then
+// `POST` the finalize URL with the X-Payment token to credit the balance.
+async function cmdTopup(vendor, opts = {}) {
+  if (!vendor) return die("usage: planner topup <vendor> [--credits <N>] [--bundle <slug>]");
+  await ensureAgent();
+
+  const body = { vendorSlug: vendor };
+  if (opts.bundle) body.packageSlug = opts.bundle;
+  else body.costCredits = opts.credits ? Number(opts.credits) : 5; // min 5 MC ($5)
+
+  // 1. initiate — always answers 402 with the x402 challenge on success
+  const init = await rawCall(`${PROXY}/llm/topup/initiate`, "POST", JSON.stringify(body), {}, true);
+  if (init.status !== 402) die(`topup initiate ${init.status} — ${init.text.slice(0, 200)}`);
+  let ch; try { ch = JSON.parse(init.text); } catch { return die("topup initiate did not return JSON"); }
+  const { orderId, resource, costCredits, creditsToGrant } = ch;
+  if (!resource || !orderId) die("topup initiate missing orderId/resource");
+  console.error(c.dim(`· order ${orderId}: ${costCredits} Monetize Credits → ${Number(creditsToGrant).toLocaleString()} Units to ${vendor}`));
+
+  // 2. mandate (credits) — budget must cover the cost (wallet credits unit = MC × 100)
+  const budget = opts.budget ? Number(opts.budget) : Math.max(500, Math.ceil(Number(costCredits) * 100));
+  const seconds = opts.seconds ? Number(opts.seconds) : 28800;
+  const mandateId = await ensureMandate("FLUXA_MONETIZE_CREDITS", budget, seconds, `${PROXY}/llm/topup`);
+
+  // 3. sign the payment over the FULL 402 body
+  const paid = unwrap(await walletJson(["x402-v3", "--mandate", mandateId, "--payload", init.text]));
+  const xPayment = paid.xPaymentB64 || paid.xPayment;
+  if (!xPayment) die("x402-v3 did not return a payment token (xPaymentB64).");
+
+  // 4. finalize — POST the resource URL with the payment token (no bearer)
+  const fin = await rawCall(resource, "POST", undefined, { "X-Payment": xPayment });
+  if (fin.status >= 400) die(`finalize ${fin.status} — ${fin.text.slice(0, 200)}`);
+  let res; try { res = JSON.parse(fin.text); } catch { res = {}; }
+  const added = Number(res.creditsAdded ?? creditsToGrant);
+  console.log(c.green("✓") + ` topped up ${vendor} · +${added.toLocaleString()} Units · balance ${Number(res.balance ?? 0).toLocaleString()} Units`);
+}
+
+// --- plan (thin call to server-side endpoint) --------------------------------
+async function cmdPlan(task) {
+  if (!task) return die('usage: planner plan "<task>"');
+  const r = await fetch(`${PROXY}/api/planner/plan`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ task }),
+  });
+  if (!r.ok) return die(`plan failed: HTTP ${r.status}`);
+  const result = await r.json().catch(() => null);
+  if (!result) return die("plan failed: bad response");
+  if (result.kind === "answer") return printAnswer(result);
+  return printPlan(result);
+}
+
+function printAnswer(a) {
+  console.log("\n  " + c.bold(a.answer));
+  if (a.command) {
+    console.log("\n  " + c.dim("run:"));
+    console.log("    " + c.cyan(a.command));
+  }
+  if (a.prompt) {
+    console.log("\n  " + c.dim("copy this prompt for your agent:"));
+    for (const line of a.prompt.split("\n")) console.log("    " + line);
+  }
+  console.log("");
+}
+
+// Render a PlanOrAnswer plan: tools carry kind/slug/name/units/detail.
+function printPlan(plan) {
+  const tools = plan.tools || [];
+  const heading = 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(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(plan.instructions));
+  console.log(c.dim("\n  → call these tools directly — FluxA settles each paid call from your wallet. No keys, no subs."));
+  return total;
+}
+
+// --- info (self-contained explainer; no network, no auth) -------------------
+const INFO = {
+  overview: () => `
+${c.bold("planner")} ${c.dim("— what you're working with")}
+
+  FluxA is an agent-native task layer. The planner ${c.bold("recommends")} the right tools for a
+  task; your agent runs them and FluxA settles each paid call from your wallet.
+
+  ${c.bold("Three kinds of tool")} (all metered in Units):
+    ${KIND.api}  Oneshot APIs  — pay-per-call endpoints (scrape, search, video, …)
+    ${KIND.model}  Models        — LLM endpoints, billed per token, via /llm/{merchant}
+    ${KIND.skill}  Skills        — packaged multi-step routines
+
+  ${c.bold("Money")}
+    1 Unit = $0.00001 · 100,000 Units = $1 = 1 Monetize Credit (MC)
+    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.
+
+  ${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")}
+
+  More:  ${c.cyan("planner info")} ${c.dim("<units|auth|pay|keys|apis|models|skills>")}
+`,
+  units: () => `
+${c.bold("Units & credits")}
+  1 Unit = $0.00001 (USD).  100,000 Units = $1 = 1 Monetize Credit (MC).
+  · Per-call API/skill prices are quoted in USD; model rates in Units per 1M tokens.
+  · Your prepaid balance is in Units, held ${c.bold("per merchant")}.
+  · Topups are charged in Monetize Credits (min 5 MC = $5); 1 MC grants 100,000 Units.
+`,
+  auth: () => `
+${c.bold("Auth")}
+  Two accepted Bearer credentials:
+    ${c.dim("fxa_live_<key>")}   create at ${new URL(PLATFORM).host}/keys · ${c.cyan("planner login <key>")}
+    ${c.dim("agent VC")}         short-lived JWT, auto-minted from your local fluxa-wallet
+  planner auto-mints an agent VC when no key is set — nothing to log in.
+  Discovery (${c.cyan("search")}) is public; everything else is authed.
+  Manage keys programmatically with ${c.cyan("planner keys")} ${c.dim("(VC only — see `planner info keys`)")}.
+`,
+  keys: () => `
+${c.bold("API keys — programmatic management")} ${c.dim("(Agent VC only)")}
+  Provision and rotate your ${c.dim("fxa_live_")} keys so an agent can hand a fresh, capped key
+  to a sub-process without you minting one by hand. ${c.bold("Requires an Agent VC")} — a metered
+  fxa_live_ key is refused (it must not mint uncapped siblings or revoke others).
+    ${c.cyan("planner keys")}                                list your keys (prefixes only)
+    ${c.cyan("planner keys create --name <n> --cap <MC>")}   mint one; raw key shown ONCE
+    ${c.cyan("planner keys update <id> --cap <MC>")}         change name / spend cap (${c.dim("--cap 0")} clears)
+    ${c.cyan("planner keys revoke <id>")}                    revoke (immediate, irreversible)
+  Spend caps (in MC) gate metered LLM usage on that key only. To rotate: create
+  the new key, hand it off, ${c.bold("then")} revoke the old — never leave zero working keys.
+`,
+  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.
+`,
+  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.
+`,
+  models: () => `
+${c.bold("Models — merchant-centric")}
+  A ${c.bold("merchant")} (provider) exposes many models; billing + balance are per merchant.
+  An offering is ${c.dim("(merchant, model)")}; the lane is ${c.dim("POST /llm/{merchant}/v1/chat/completions")}
+  (OpenAI wire format), billed per token.
+    ${c.cyan("planner models [--vendor <slug>]")}   list models + Units rates
+    ${c.cyan("planner topup <merchant>")}           fund that merchant's balance
+`,
+  skills: () => `
+${c.bold("Skills")}
+  Packaged multi-step routines that wrap several tools into one capability.
+    ${c.cyan('planner search "<q>" --type skill')}   discover skills
+  Install via the skills tool: ${c.dim("npx -y skills add <platform> -s <slug>")}.
+`,
+};
+
+function cmdInfo(topic) {
+  const key = (topic || "overview").toLowerCase();
+  const render = INFO[key];
+  if (!render) {
+    return die(`unknown topic: ${topic}\n  topics: ${Object.keys(INFO).filter((k) => k !== "overview").join(", ")}`);
+  }
+  console.log(render());
+}
+
+function help() {
+  console.log(`
+${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>']
+
+${c.bold("Primitives")}  ${c.dim("(all live)")}
+  planner search "<q>" [--type api,skill,model]   discover resources
+  planner models [--vendor <slug>]                 model catalog + Units rates
+  planner balance [vendor]                         prepaid Units per merchant
+  planner topup <vendor> [--credits <N>|--bundle <slug>]   prepay Units (x402, via wallet)
+  planner ledger <vendor>                          spend/topup history
+  planner keys [create|update <id>|revoke <id>]    manage fxa_live_ API keys (Agent VC only)
+  planner login <fxa_live_…> / planner whoami      auth
+  planner info [units|auth|pay|keys|apis|models|skills] explain how the platform works
+
+${c.dim("Config: FLUXA_KEY, FLUXA_PLATFORM (" + PLATFORM + "), FLUXA_PROXY (" + PROXY + ")")}
+`);
+}
+
+function die(msg, ctx) {
+  console.error(c.red("error: ") + msg);
+  exit(1);
+}
+
+// --- arg parse --------------------------------------------------------------
+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"];
+  const BOOLS = ["--raw"];
+  const getFlag = (n) => { const i = args.indexOf(n); return i !== -1 ? args[i + 1] : null; };
+  const type = getFlag("--type");
+  const vendor = getFlag("--vendor");
+  const rest = [];
+  for (let i = 1; i < args.length; i++) {
+    if (FLAGS.includes(args[i])) { i++; continue; }
+    if (BOOLS.includes(args[i])) continue;
+    rest.push(args[i]);
+  }
+  const arg = rest.join(" ").trim();
+
+  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"),
+      });
+    case "search": return cmdSearch(arg, type);
+    case "models": return cmdModels(vendor);
+    case "balance": case "bal": return cmdBalance(rest[0]);
+    case "topup":
+      return cmdTopup(rest[0], {
+        credits: getFlag("--credits"), bundle: getFlag("--bundle"),
+        budget: getFlag("--budget"), seconds: getFlag("--seconds"),
+      });
+    case "ledger": return cmdLedger(rest[0]);
+    case "keys": return cmdKeys(rest[0], rest.slice(1), { name: getFlag("--name"), cap: getFlag("--cap") });
+    case "login": return cmdLogin(rest[0]);
+    case "whoami": return cmdWhoami();
+    case "info": return cmdInfo(rest[0]);
+    case undefined: case "-h": case "--help": case "help": return help();
+    default: return die(`unknown command: ${cmd}\n  run \`planner --help\``);
+  }
+}
+
+main();