@paydlux/agent 0.1.22 → 0.1.24

package/README.md

@@ -7,6 +7,9 @@ real money has already been drained this way.
 
 Paydlux puts the guardrails **on the ledger** instead of in your code.
 
+**Homepage: [paydlux.com](https://paydlux.com)** — product, pricing and the
+live demo. Source: this repo. Docs and setup: below.
+
 ## The Stellar path (primary — no smart contract, no faucet, no gas fight)
 
 There is no contract to audit. The whole mechanism is three native Stellar
@@ -30,6 +33,7 @@ injection cannot talk its way past a signature check.
 stellar/vault.ts     create a 2-of-2 vault, register mandates, settle, revoke
 stellar/gateway.ts   HTTP 402 resource server; serves only after the ledger agrees
 stellar/agent.ts     the buyer side — one class, one method call
+stellar/mcp.ts       the same buyer side as an MCP server, for any agent client
 stellar/desk.ts      approval queue: a human decides, in the clear
 stellar/portal.ts    the page that human looks at
 stellar/policy.ts    daily budget / seller allowlist (the part a ledger can't count)
@@ -75,6 +79,57 @@ What the desk enforces once it is public (`npx tsx stellar/tls-check.ts`, 19 che
 
 No wallet, no faucet, no config.
 
+### MCP server: your agent calls Paydlux instead of a wallet
+
+The buyer side also speaks [Model Context Protocol](https://modelcontextprotocol.io),
+so an agent in Claude, Cursor, LobeHub, Codex or any other MCP client gets Paydlux's
+tools directly — no wallet, no signing library, no payment code in the agent:
+
+```bash
+npx -y @paydlux/agent mcp --file /absolute/path/to/paydlux-vault.json
+```
+
+Add it to the client the same way you add any stdio server:
+
+```json
+{
+  "mcpServers": {
+    "paydlux": {
+      "command": "npx",
+      "args": ["-y", "@paydlux/agent", "mcp", "--file", "/absolute/path/to/paydlux-vault.json"]
+    }
+  }
+}
+```
+
+| tool | what the agent gets |
+|---|---|
+| `paydlux_status` | which vault, which token, live balance, who can sign, how many mandates are live |
+| `paydlux_payment_rules` | the ceiling the human set — plus what the ledger says is already spent today |
+| `paydlux_check_payment` | dry run: would *this* amount to *this* seller pass, and which rule breaks if not |
+| `paydlux_buy` | pay a 402-gated seller. If a human has to approve, the answer is a handle and a status URL |
+| `paydlux_payment_status` | has the human decided yet |
+| `paydlux_recent_payments` | the last payments in/out, with transaction hashes an explorer can check |
+| `paydlux_escrow_status` / `paydlux_pending_escrows` | what is locked in escrow, and who can still take it back |
+
+Two things this server deliberately cannot do:
+
+- **It cannot release money on its own.** It loads the agent key and nothing
+  else — one signer of weight 1 against a release threshold of 2. There is no
+  flag that accepts the principal or approver key, so it cannot be talked into
+  using a key it never holds. A payment the mandate does not cover comes back as
+  `needs_approval`, with the handle and the desk link for the human.
+- **It cannot read a carelessly stored key file.** If the vault file is readable
+  by other users, the server refuses to start until you `chmod 600` it, and no
+  tool result will ever print a secret seed.
+
+Run it with `--read-only` and the two tools that touch money disappear from the
+tool listing entirely — useful for an agent that should report on spend but not
+cause any. `npx tsx stellar/mcp-check.ts` drives the server with a real MCP
+client and asserts all of the above (20 checks, testnet).
+
+Product page, pricing and the hosted demo: **[https://paydlux.com](https://paydlux.com)**.
+
 ### The human key does not live on the seller's machine
 
 The vault needs two signatures. If both keys sit in one process, that is really
@@ -242,6 +297,31 @@ too, because a budget that silently reads as unspent is worse than no budget.
 The banner shows what is left: `policy: max 10 per payment, 50 per day (27.50
 left today)`.
 
+### Spend it by category, and edit the rules in a browser
+
+One vault, several pockets. Open **spending rules** on the approvals page (or
+`/rules` on the desk) and set, per named category, its own per-payment ceiling and
+daily budget — then say which seller wallet belongs to which category:
+
+```
+data-api    max 3 / payment    6 / day     ← api.example.com wallet
+coding      max 1 / payment    2 / day     ← assistant wallet
+```
+
+A category can only be **tighter** than the limits above it; it can never raise
+them, because the base ceilings are checked first. That asymmetry is the security
+property, and `npm run test:policy` proves it, along with the queue counting
+inside a category and the fact that a form posted from another site cannot raise
+your budget.
+
+Edits are saved to the vault's config file, so they survive a restart. Once you
+have edited them there, the saved numbers win over `--max`/`--daily` on the next
+start, and the seller prints which it is using — a rule that quietly reverts by
+morning is worse than no rule.
+
+`stellar/policy.ts` is the engine; the page is a plain HTML form, so it works with
+JavaScript off.
+
 ### What is enforced where (said honestly)
 
 | enforced by Stellar | enforced by the desk (`policy.ts`) |

package/dist/cli.js

@@ -15,7 +15,7 @@
 // into their bot.
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:http";
-import { execSync } from "node:child_process";
+import { execSync, spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, chmodSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
@@ -29,6 +29,7 @@ import { DEMO_HOST, DEMO_ROUTE, startDemo } from "./showcase.js";
 import { DONATE_HOST, DONATE_PORT, startDonate } from "./donate.js";
 import { claimEscrow, pendingEscrows, prepareEscrowRelease, refundEscrow } from "./escrow.js";
 import { describeChallenge } from "./phone.js";
+import { start as startMcp } from "./mcp.js";
 export const VAULT_FILE_DEFAULT = "paydlux-vault.json";
 const arg = (name) => {
     const i = process.argv.indexOf(`--${name}`);
@@ -221,7 +222,26 @@ async function sell() {
     // desk is even built.
     const maxPer = Number(arg("max") ?? data.policy?.maxPerPayment ?? 2);
     const daily = Number(arg("daily") ?? data.policy?.dailyBudget ?? 10);
-    const policy = new PolicyEngine({ maxPerPayment: maxPer, dailyBudget: daily });
+    // Categories and the wallet map come from the config file only: they are set
+    // at the desk (/rules), not from the command line. A flag for them would be a
+    // second, easier way to say the same thing, and the page would drift from it.
+    //
+    // The same is true of the two ceilings once an owner edits them at the desk:
+    // the saved file wins over the flags, because the app scripts pass --max and
+    // --daily on every start and would otherwise silently undo whatever was set in
+    // the browser. The line printed below is what keeps that from being a
+    // surprise — a rule that quietly reverts is worse than no rule at all.
+    const saved = data.policy?.savedByOwner === true;
+    const maxPerFinal = saved ? Number(data.policy.maxPerPayment ?? maxPer) : maxPer;
+    const dailyFinal = saved ? Number(data.policy.dailyBudget ?? daily) : daily;
+    if (saved && (maxPerFinal !== maxPer || dailyFinal !== daily)) {
+        log(`using the rules you saved at the desk (max ${maxPerFinal}, daily ${dailyFinal}) instead of the command line (${maxPer}/${daily}).\n  to change them: open the approvals link and press "spending rules".`);
+    }
+    const policy = new PolicyEngine({
+        maxPerPayment: maxPerFinal, dailyBudget: dailyFinal,
+        allowlist: data.policy?.allowlist, denylist: data.policy?.denylist,
+        categories: data.policy?.categories, payeeCategory: data.policy?.payeeCategory,
+    });
     // A ceiling below the price blocks every payment, and the failure looks like
     // a bug in the desk: the buyer waits, the human never sees an approvable
     // item, and the log says "mandate refused". Say it now, before anything is
@@ -233,16 +253,16 @@ async function sell() {
     // takes money IN from the buyer, so the ceiling does not apply to it — and
     // applying it would refuse a perfectly good escrow price for no reason.
     if (mode === "escrow") {
-        if (priceNum > maxPer) {
-            log(`note: --escrow price ${price} is above --max ${maxPer}. That is fine here — escrow money comes FROM the buyer, so your spending mandate never touches it.`);
+        if (priceNum > maxPerFinal) {
+            log(`note: --escrow price ${price} is above --max ${maxPerFinal}. That is fine here — escrow money comes FROM the buyer, so your spending mandate never touches it.`);
         }
     }
     else {
-        if (priceNum > maxPer) {
-            bad(`--price ${price} is above --max ${maxPer}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
+        if (priceNum > maxPerFinal) {
+            bad(`--price ${price} is above --max ${maxPerFinal}, so every payment would be refused by your own mandate.\n  raise --max to at least ${price} (for example --max ${price}) or lower --price.`);
         }
-        if (priceNum > daily) {
-            bad(`--price ${price} is above --daily ${daily}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
+        if (priceNum > dailyFinal) {
+            bad(`--price ${price} is above --daily ${dailyFinal}: one payment would spend the whole day's budget and the second would be refused.\n  set --daily to at least ${price}.`);
         }
     }
     const vault = await StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
@@ -267,20 +287,31 @@ async function sell() {
             + `the daily budget of ${daily} cannot be enforced without it, so nothing was started. `
             + `Check the network and try again.`);
     }
-    policy.seedFromLedger(alreadyPaid);
+    policy.seedFromLedger(alreadyPaid, policy.categoryOf(payee));
     if (alreadyPaid > 0) {
-        log(`ledger says ${alreadyPaid.toFixed(2)} of the ${daily} daily budget is already spent today`);
-        if (alreadyPaid >= daily) {
-            bad(`today's budget is already gone: ${alreadyPaid.toFixed(2)} paid, ${daily} allowed.\n  `
+        log(`ledger says ${alreadyPaid.toFixed(2)} of the ${dailyFinal} daily budget is already spent today`);
+        if (alreadyPaid >= dailyFinal) {
+            bad(`today's budget is already gone: ${alreadyPaid.toFixed(2)} paid, ${dailyFinal} allowed.\n  `
                 + `the mandate would refuse every payment. Raise --daily or wait for the UTC day to roll over.`);
         }
     }
+    // Say out loud what the rules are, including the categories, so the numbers
+    // an owner set in a browser are visible to whoever starts the seller. A rule
+    // nobody can see is a rule nobody trusts.
+    const catNames = Object.keys(policy.policy.categories ?? {});
+    if (catNames.length) {
+        const mapped = Object.entries(policy.policy.payeeCategory ?? {});
+        log(`spending categories: ${catNames.map((c) => {
+            const r = policy.policy.categories[c];
+            return `${c} (${r.maxPerPayment ?? policy.policy.maxPerPayment}/payment, ${r.dailyBudget ?? dailyFinal}/day)`;
+        }).join(", ")}${mapped.length ? ` · ${mapped.length} wallet(s) mapped` : ""}`);
+    }
     if (network === "public") {
         console.log(`
   MAINNET — real money.
     token            ${data.token.code}
-    max per payment  ${maxPer}
-    daily budget     ${daily}
+    max per payment  ${maxPerFinal}
+    daily budget     ${dailyFinal}
     vault            ${vault.address}
     balance          ${await vault.balance()} ${data.token.code}
 `);
@@ -337,6 +368,25 @@ async function sell() {
         ],
         // The banner prints these numbers. This line is what makes them true.
         policy,
+        // Rules edited at the desk must survive the next restart, or the mandate in
+        // the banner is a promise that lasts until ctrl-c. Written back to the same
+        // config file, with the same 0600 as everywhere else in this file, because
+        // it also holds key material.
+        onPolicyChange: (p) => {
+            data.policy = {
+                ...(data.policy ?? {}),
+                // The marker that says "a human set these in a browser". Without it the
+                // app scripts' --max/--daily flags win on every restart and the edit is
+                // lost by morning.
+                savedByOwner: true,
+                maxPerPayment: p.maxPerPayment, dailyBudget: p.dailyBudget,
+                allowlist: p.allowlist ?? [], denylist: p.denylist ?? [],
+                categories: p.categories ?? {}, payeeCategory: p.payeeCategory ?? {},
+            };
+            writeFileSync(path, JSON.stringify(data, null, 2));
+            chmodSync(path, 0o600);
+            log(`rules saved to ${path}`);
+        },
     });
     let tunnel = null;
     if (tls) {
@@ -372,7 +422,7 @@ async function sell() {
             bad(`port ${demoPort} (showcase) is already in use by ${who}.`);
         await startDemo({
             port: demoPort, price, network, vault: vault.address, token: data.token.code,
-            explorer: data.explorer ?? "", gateway: gw,
+            explorer: data.explorer ?? "", gateway: gw, route: uri, payee,
             onKeys: (pubs) => { gw.agentKeys = [pub(keys.agent), ...pubs]; },
         });
         log(`showcase is listening on 127.0.0.1:${demoPort} for https://${DEMO_HOST}`);
@@ -455,6 +505,257 @@ ${flag("donate") ? `  donations  https://${DONATE_HOST}   (they pay YOU from THE
     process.on("SIGINT", bye);
     process.on("SIGTERM", bye);
 }
+/**
+ * paydlux demo — the funder meeting, as one command.
+ *
+ * `sell` is the right command for a seller: it takes flags, and it refuses to
+ * start when anything is off (port taken, budget already spent). That is correct
+ * for a seller and fatal in front of an investor, who is watching a terminal go
+ * red thirty seconds before the money shot.
+ *
+ * This is a preset, not a second implementation. It fixes the two things that
+ * actually break a live demo, then runs the SAME sell() — same mandate, same
+ * desk, same ledger, same phone signature:
+ *
+ *   1. A port already held by Paydlux is not an error. It means the demo is
+ *      already running, so print the links and open the tabs instead of dying.
+ *   2. A daily budget already spent today IS fatal (the mandate would refuse
+ *      every payment), so raise it, save it to the vault file, and say so out
+ *      loud. Raising the *daily* counter is safe: the per-payment ceiling is
+ *      still pinned into the signed transaction hash.
+ *
+ * It then opens the two tabs and prints the runbook, so nobody has to remember
+ * a URL or a portal key while someone is watching.
+ */
+async function demo() {
+    const path = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT);
+    if (!existsSync(path))
+        bad(`no vault here. Run:  paydlux setup`);
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    const network = (data.network ?? "testnet");
+    const price = arg("price") ?? data.policy?.defaultPrice ?? "1";
+    const ports = [
+        Number(arg("port") ?? 4021), Number(arg("desk") ?? 4022),
+        Number(arg("demo-port") ?? 4023),
+    ];
+    // The donation door (4024) is deliberately NOT in this list and NOT started
+    // by the demo. It runs against the MAINNET vault, where real people send real
+    // USDC. A demo preset that restarted it would point a public money address at
+    // a testnet vault, and a donation to a testnet account is gone forever.
+    // 1. Something already on those ports? Two different things happened in real
+    // meetings and neither may end in a red error:
+    //   a) the demo IS up and answering — reuse it, just open the tabs;
+    //   b) a leftover Paydlux (a donation door from this morning, a seller that
+    //      lost its tunnel) is squatting on one port — the public URLs then 530
+    //      and `sell` refuses to start. Stop the leftover, say exactly what was
+    //      stopped, and start a clean demo.
+    const live = await surfacesLive();
+    if (live.desk && live.demo && !flag("restart") && await surfacesServe(path)) {
+        const key = data.desk?.portalKey;
+        log("the demo is already running and answering — nothing to start");
+        openUrl(`https://${DEMO_HOST}`);
+        if (key)
+            openUrl(`https://${PUBLIC_HOST}/phone/?k=${key}`);
+        demoCard(`https://${PUBLIC_HOST}`, key, data);
+        return;
+    }
+    if (live.desk && live.demo) {
+        // Answering, but on a different vault. desk.paydlux.com and demo.paydlux.com
+        // are ONE address: a testnet demo and a mainnet demo cannot both be live on
+        // it. Reusing whichever happens to be up is how a founder ends up showing
+        // play money while believing the real vault is on the screen — or the other
+        // way round, with real money moving during a "safe" demo. Stop it, say so,
+        // and start the one that was asked for.
+        log(`something else is answering ${DEMO_HOST} — stopping it so the ${network} demo can take the address`);
+    }
+    await clearDemoPorts(ports);
+    // 2. Budget headroom. `sell` refuses to start when the ledger says today's
+    // budget is gone, and the demo would then die at the worst possible moment.
+    // Seed the counter from the ledger here and lift the ceiling if needed.
+    // NB: `payee` in the vault file is an object ({address, seed}) when `setup`
+    // generated one, and a bare address string when the seller passed --payee.
+    // Reading only the string form silently skips this check — which is exactly
+    // how the demo died once, on "1.00 of the 50 daily budget is already spent".
+    const payeeAddr = typeof data.payee === "string" ? data.payee : data.payee?.address;
+    const daily = Number(data.policy?.dailyBudget ?? 50);
+    if (typeof payeeAddr === "string" && /^G[A-Z2-7]{55}$/.test(payeeAddr)) {
+        try {
+            const vault = await vaultHandle(data, network);
+            const spent = Number(await vault.paidToday(payeeAddr));
+            // Enough headroom for ten more demo payments, whatever the price is.
+            const want = spent + Math.max(10, Math.ceil(Number(price) * 10));
+            if (daily < want) {
+                data.policy = { ...(data.policy ?? {}), savedByOwner: true, dailyBudget: Math.ceil(want) };
+                writeFileSync(path, JSON.stringify(data, null, 2));
+                chmodSync(path, 0o600);
+                log(`today's spend is ${spent.toFixed(2)} of ${daily}; raised the daily budget to ${data.policy.dailyBudget} so the demo has room`);
+                log(`  per-payment ceiling unchanged (${data.policy.maxPerPayment ?? "?"}) — that one is pinned into the signed transaction hash`);
+            }
+        }
+        catch (e) {
+            // Do not block the demo on this check. If the ledger really is
+            // unreachable, sell() will say so plainly before it starts anything.
+            log(`could not pre-check today's spend (${e?.message ?? e}) — starting anyway`);
+        }
+    }
+    // 3. Run the real thing. sell() reads its options from process.argv, so the
+    // preset is expressed there rather than by duplicating the seller's startup.
+    const extra = ["sell", "--split", "--tls", "--showcase",
+        "--price", price, "--route", "/market/data", "--file", path];
+    for (const f of ["max", "daily", "port", "desk", "demo-port", "donate-port"]) {
+        const v = arg(f);
+        if (v !== undefined)
+            extra.push(`--${f}`, v);
+    }
+    process.argv = [process.argv[0], process.argv[1], ...extra];
+    // Open the tabs as soon as the desk actually answers — not before, because a
+    // tab that loads an error page is what a funder remembers. Scheduled rather
+    // than awaited: sell() never returns, it stays up serving payments.
+    const key = data.desk?.portalKey;
+    demoCard(`https://${PUBLIC_HOST}`, key, data);
+    if (!flag("no-open")) {
+        setTimeout(async () => {
+            if (await tunnelLive()) {
+                openUrl(`https://${DEMO_HOST}`);
+                if (key)
+                    openUrl(`https://${PUBLIC_HOST}/phone/?k=${key}`);
+            }
+        }, 1000);
+    }
+    await sell();
+}
+/** Are the public URLs actually answering? A port can be held by a process
+ *  whose tunnel died, which is worse than no process at all: the browser gets
+ *  a Cloudflare 530 and the founder has no idea why. */
+async function surfacesLive() {
+    const get = async (url) => {
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(4000) });
+            return r.status < 500;
+        }
+        catch {
+            return false;
+        }
+    };
+    const [desk, demo] = await Promise.all([
+        get(`https://${PUBLIC_HOST}/healthz`), get(`https://${DEMO_HOST}/`),
+    ]);
+    return { desk, demo };
+}
+/**
+ * Is the Paydlux answering those ports the SAME vault that was asked for?
+ *
+ * The public addresses are singletons: desk.paydlux.com and demo.paydlux.com can
+ * only carry one vault at a time, and the testnet demo and the mainnet demo use
+ * the same two. "It is already running" is therefore not enough — the thing that
+ * is running may be the other network. Answering a funder with play money while
+ * saying it is the real vault (or moving real money during what everyone believes
+ * is a safe demo) is the worst failure this command can have, so the reuse path
+ * checks the vault file of the process actually holding the ports.
+ */
+async function surfacesServe(path) {
+    const want = resolve(process.cwd(), path);
+    for (const port of [Number(arg("desk") ?? 4022), Number(arg("port") ?? 4021)]) {
+        const who = await portHolder(port);
+        const pid = Number((who?.match(/pid (\d+)/) ?? [])[1]);
+        if (!pid)
+            return false;
+        // -ww: a truncated command line would hide the --file argument and make this
+        // say "different vault" about the very demo we are asking to reuse.
+        let cmd = "";
+        try {
+            cmd = execSync(`ps -ww -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+        }
+        catch {
+            return false;
+        }
+        const served = (cmd.match(/--file[= ](\S+)/) ?? [])[1] ?? VAULT_FILE_DEFAULT;
+        if (resolve(process.cwd(), served) !== want)
+            return false;
+    }
+    return true;
+}
+/**
+ * Free the demo's ports when a stale Paydlux is squatting on one.
+ *
+ * Only Paydlux processes are touched, and only after saying which one and why.
+ * Anything else on the port is left alone and reported, because killing a
+ * stranger's server to make a demo fit is not our call to make.
+ */
+async function clearDemoPorts(ports) {
+    for (const port of ports) {
+        const who = await portHolder(port);
+        if (!who)
+            continue;
+        if (!/paydlux|cli|tsx|node/i.test(who)) {
+            bad(`port ${port} is held by ${who}, which is not Paydlux.\n  free it, or move the demo: paydlux demo --desk ${port + 100}`);
+        }
+        const pid = Number((who.match(/pid (\d+)/) ?? [])[1]);
+        if (!pid) {
+            log(`port ${port} is held by ${who}; stopping it`);
+            continue;
+        }
+        try {
+            const cmd = execSync(`ps -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+            log(`stopping the stale Paydlux on port ${port} (pid ${pid}): ${cmd.slice(0, 90)}`);
+            process.kill(pid, "SIGTERM");
+        }
+        catch { /* already gone */ }
+        // Wait for the port to actually free. SIGTERM to a seller runs its bye()
+        // handler, which takes a moment to close listeners and the tunnel.
+        for (let i = 0; i < 20; i++) {
+            if (!(await portHolder(port)))
+                break;
+            await new Promise((r) => setTimeout(r, 250));
+        }
+        const still = await portHolder(port);
+        if (still) {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* gone */ }
+            log(`port ${port} needed a hard stop`);
+        }
+    }
+}
+/** The runbook, printed where the founder is already looking. */
+function demoCard(host, key, data) {
+    const network = data.network ?? "testnet";
+    // The footer used to promise "nothing here costs real money" unconditionally.
+    // On the public network that is a lie, and it is the kind of lie that gets a
+    // founder spending the vault in front of an investor.
+    const real = network !== "testnet";
+    console.log(`
+  ┌── Paydlux demo · the 5-minute script ─────────────────────────────
+  │ 1  https://paydlux.com        "an agent buys from a website"
+  │ 2  https://${DEMO_HOST}      press RUN THE LOOP → 402 → paid
+  │ 3  your iPhone                hold 1.2s. the key never left it
+  │ 4  back on tab 2              step 5 prints the ledger tx hash
+  │ 5  ${host}/rules${key ? `?k=${key}` : ""}   spending limits, categories
+  └───────────────────────────────────────────────────────────────────
+  token ${data.token?.code ?? "?"} · ${network} · ${real
+        ? "REAL MONEY — each approved loop pays out of this vault"
+        : "nothing here costs real money"}
+`);
+}
+/** Open a URL in the default browser. Best-effort: a demo survives it failing. */
+function openUrl(url) {
+    try {
+        const tool = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const p = spawn(tool, args, { stdio: "ignore", detached: true });
+        p.on("error", () => log(`open this yourself: ${url}`));
+        p.unref();
+    }
+    catch {
+        log(`open this yourself: ${url}`);
+    }
+}
+/** The vault handle `sell` uses, shared so the demo checks the same numbers. */
+async function vaultHandle(data, network) {
+    const keys = data.keys ?? {};
+    return StellarVault.load(data.vault, data.token.code, data.token.issuer, { principal: pub(keys.principal), approver: keys.approver ? pub(keys.approver) : undefined, agent: pub(keys.agent) }, network);
+}
 /** XLM the vault must hold to exist, versus what it actually has. */
 async function vaultRent(vault) {
     const acc = await vault.horizon.loadAccount(vault.address);
@@ -770,7 +1071,19 @@ async function withdraw() {
         bad("then run this again — approvals from the phone land automatically.");
     }
     console.log(`sending ${want} ${data.token.code} from the vault to ${to} …`);
-    const res = await vault.release(to, String(want), principal, approver, "paydlux withdraw");
+    // A wallet that has never been funded cannot receive a payment — the ledger
+    // answers op_no_destination. For XLM the fix is the createAccount operation,
+    // which costs the same two signatures. For a token there is no fix at all:
+    // that account would need a trustline too, so say so instead of failing cryptically.
+    const exists = await vault.horizon.loadAccount(to).then(() => true).catch(() => false);
+    if (!exists && !vault.isNative) {
+        bad(`${to} has no account on the ledger, so it cannot hold ${data.token.code}.\n  send it XLM from any exchange first, then withdraw again.`);
+    }
+    if (!exists)
+        console.log(`${to} does not exist on the ledger yet — this payment creates it.`);
+    const res = exists
+        ? await vault.release(to, String(want), principal, approver, "paydlux withdraw")
+        : await vault.fund(to, String(want), principal, approver, "paydlux withdraw");
     console.log(`done. tx ${res?.hash}`);
     console.log(`vault now holds ${await vault.balance()} ${data.token.code}`);
 }
@@ -1027,6 +1340,12 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
       in a claimable balance you cannot touch until --release seconds have
       passed, and the buyer can take it back any time before then. You get paid
       by proving delivery before the timer, not by waiting for it.
+  paydlux demo  [--price 1] [--file ./paydlux-vault.json]
+      the funder meeting as one command. Same seller, same desk, same phone
+      signature — but it refuses to fail in front of an audience: if the demo is
+      already running it opens the tabs instead of dying on a taken port, and if
+      today's daily budget is already spent it raises that budget (the
+      per-payment ceiling is untouched) rather than refusing to start.
   paydlux escrow [--release ORD | --refund ESCROW_ID]
       list what is locked for your vault, release one order, or take a buyer's
       money back. Release needs both human keys; on a --split vault it prints
@@ -1046,6 +1365,11 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
   paydlux withdraw --to G… [--all | --amount N]
       take your money back out of the vault. Needs both human keys; the agent
       key can never do this.
+  paydlux mcp   [--file ./paydlux-vault.json] [--read-only]
+      serve Paydlux as an MCP server, so an agent in Claude, Cursor, LobeHub or
+      any other MCP client buys through the mandate instead of holding a wallet.
+      This process loads only the agent key — one of two vault signers — so it
+      cannot release money alone. --read-only drops the tools that touch money.
 
 one file holds it all: ./paydlux-vault.json (0600, never commit it)
 `;
@@ -1191,6 +1515,8 @@ export async function main() {
         return setup();
     if (cmd === "sell")
         return sell();
+    if (cmd === "demo")
+        return demo();
     if (cmd === "donate")
         return donate();
     if (cmd === "status")
@@ -1203,6 +1529,8 @@ export async function main() {
         return usdc();
     if (cmd === "escrow")
         return escrow();
+    if (cmd === "mcp")
+        return startMcp();
     bad(`unknown command "${cmd}".\n\n${HELP}`);
 }
 // Run only when this file is the entry point, so importing it in a test is safe.

package/dist/desk.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { StellarVault } from "./vault.ts";
-import type { PolicyEngine } from "./policy.ts";
+import type { PolicyEngine, Policy } from "./policy.ts";
 import { type ApprovalChallenge } from "./phone.ts";
 /** A portal link is a capability: whoever holds it can approve. So it is long,
  *  random, and compared without leaking timing. */
@@ -96,10 +96,31 @@ export type DeskConfig = {
      * ceiling can actually hold.
      */
     policy?: PolicyEngine;
+    /**
+     * Called when the human edits the spending rules from the portal. The CLI
+     * wires this to the config file, so a rule set at the desk survives the next
+     * restart instead of resetting to the command-line defaults.
+     *
+     * A callback rather than a path: the desk must not know where secrets live.
+     * The config file also holds key material, so the writer stays with the code
+     * that already handles it (0600, same serialisation).
+     */
+    onPolicyChange?: (policy: Policy) => void;
 };
 export declare class ApprovalDesk {
     private records;
     private seq;
+    /** when /rules last saved, so the page can say "saved" without a query flag */
+    private rulesSavedAt;
+    /**
+     * When the approver app last polled /queue. The desktop portal reads /list and
+     * the phone reads /queue, so a hit here means a phone is pointed at THIS desk
+     * with THIS link. It is how a Mac can tell "the seller's phone is asleep" from
+     * "the phone is still talking to the desk from the last run" — the second one
+     * makes a live demo look dead, because the parked payment goes to a queue
+     * nobody is looking at.
+     */
+    private lastPhonePollAt;
     private server?;
     cfg: DeskConfig;
     constructor(cfg: DeskConfig);
@@ -168,6 +189,35 @@ export declare class ApprovalDesk {
     private mandateBlock;
     /** The mandate has been satisfied: count the money as spent. */
     private recordSpend;
+    /** The rules as they stand, for the /rules page. */
+    policyView(): Policy;
+    /** What today's counters read, per category, for the /rules page. */
+    private spentView;
+    /**
+     * The cross-origin gate used by every route that changes money or the rules
+     * that gate it. A cross-origin fetch POST is a CORS *simple request*: no
+     * preflight, so the attacker's page never sees the reply but the action still
+     * happens. Browsers always send Origin on POST and Sec-Fetch-Site on every
+     * request, so checking both closes that path while leaving local automation
+     * (curl, tests, the phone app on its own origin) alone.
+     *
+     * Returns a reason string when the request must be refused, null when it may
+     * proceed.
+     */
+    private crossOriginGate;
+    /**
+     * Apply an edit from the /rules form.
+     *
+     * The form carries the whole rule set, so this rebuilds rather than patches:
+     * what you see on the page is what gets saved, and a stale field cannot
+     * survive an edit. Names and numbers are validated inside PolicyEngine.update
+     * — this function only decides which fields the form is allowed to touch.
+     *
+     * Deliberately absent: maxMandateTtl and maxLiveMandates. Those are ledger
+     * constraints (sequence binding), not owner preferences, and a form field for
+     * them would be an invitation to configure a mandate the chain will refuse.
+     */
+    private applyRules;
     approve(id: string): Promise<DeskRecord>;
     /** Split mode step 1: ask the phone to sign. Nothing is submitted yet. */
     private requestPhoneSignature;