@paydlux/agent 0.1.11 → 0.1.13

package/README.md

@@ -213,11 +213,32 @@ if (res.ok) console.log(res.data, "paid in tx", res.tx);
 `npx tsx stellar/onboard.ts` creates the vault and prints that key. The key is
 **one of two signatures** — it cannot spend alone.
 
+### Your spending mandate (one command, enforced at the approve button)
+
+```bash
+paydlux sell --price 4.50 --max 10 --daily 20
+```
+
+No payment above 10, nothing past 20 in a day. The desk checks this **before**
+it asks your phone, and again at submission — the budget can be spent between
+your approval and the ledger call, so a stale signature is refused rather than
+honoured. Approvals already waiting count against the budget, so a queue of six
+4.50 requests against a 20/day cap sends four to your phone and refuses two at
+the button instead of letting you approve six and watch two fail.
+
+A refusal answers the buyer with `error: "mandate_refused"` on the **same**
+handle, so a polite agent cannot park-refuse-park forever. `paydlux sell` also
+refuses to start if `--price` is above `--max` or `--daily`, because that
+combination blocks every payment and looks like a bug in the desk.
+
+Verified on the published package: 6 x 4.50 against `--daily 20` -> four
+settled, two refused, vault balance moved exactly 18.00 and stopped.
+
 ### What is enforced where (said honestly)
 
-| enforced by Stellar | enforced by `policy.ts` |
+| enforced by Stellar | enforced by the desk (`policy.ts`) |
 |---|---|
-| max per payment, payee, token, time window, one-shot execution | payments per day, running daily total, seller allow/deny list |
+| payee, token, time window, one-shot execution, per-payment ceiling as a signer rule | per-payment ceiling and daily total at the approve button and again at submission, running daily total, seller allow/deny list |
 
 The vault is one payment at a time; counting payments is our job. A rule break
 means we never build the transaction, so nothing reaches the ledger.

package/dist/cli.js

@@ -14,6 +14,8 @@
 // A seller should type one command and get a price, a link, and a key to paste
 // into their bot.
 import { createInterface } from "node:readline/promises";
+import { createServer } from "node:http";
+import { execSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, chmodSync, realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
@@ -33,6 +35,39 @@ const log = (...a) => console.log("•", ...a);
 /** Print a reason and stop. Declared as a function (not an arrow in a const) so
  *  TypeScript's control-flow analysis actually narrows the caller after it. */
 function bad(msg) { console.error("\n" + msg + "\n"); process.exit(1); }
+/**
+ * Ask the OS whether a port is free, and if not, who owns it. Returns null when
+ * the port is available. Naming the owning process is what turns "EADDRINUSE"
+ * into something a seller can act on.
+ */
+function portHolder(port) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once("error", (e) => {
+            if (e.code === "EADDRINUSE")
+                resolve(findListener(port) ?? "another process");
+            else
+                resolve(null); // some other bind problem; let the real listen report it
+        });
+        probe.once("listening", () => { probe.close(() => resolve(null)); });
+        probe.listen(port, "127.0.0.1");
+    });
+}
+/** Best-effort: which command is holding this port, from `lsof`. */
+function findListener(port) {
+    try {
+        const out = execSync(`lsof -nP -ti tcp:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf8" });
+        const pid = out.trim().split("\n")[0];
+        if (!pid)
+            return null;
+        const cmd = execSync(`ps -o command= -p ${pid} 2>/dev/null`, { encoding: "utf8" }).trim();
+        const mine = cmd.includes("cli") || cmd.includes("paydlux");
+        return `${mine ? "another Paydlux (pid " + pid + ")" : cmd || "pid " + pid}`;
+    }
+    catch {
+        return null;
+    }
+}
 /** The one file that holds everything. Refuses to read a file that is world-readable. */
 export function loadVault(path = resolve(process.cwd(), arg("file") ?? VAULT_FILE_DEFAULT)) {
     if (!existsSync(path)) {
@@ -219,6 +254,19 @@ async function sell() {
     const publicHost = tls ? PUBLIC_HOST : (arg("host") ?? undefined);
     const deskPort = Number(arg("desk") ?? 4022);
     const gwPort = Number(arg("port") ?? 4021);
+    // A taken port used to surface as an unhandled EADDRINUSE stack trace from
+    // inside Node. To someone following the README that reads as a broken
+    // install, and the stack names neither port nor remedy.
+    for (const [label, port] of [["gateway", gwPort], ["approval desk", deskPort]]) {
+        const who = await portHolder(port);
+        if (who) {
+            // Suggest the pair, not the clashing port twice: --port and --desk with
+            // the same number would fail on the next line.
+            bad(`port ${port} (${label}) is already in use by ${who}.\n` +
+                `  another Paydlux is probably running. Stop it, or move this one:\n` +
+                `  paydlux sell --port ${gwPort + 100} --desk ${deskPort + 100}`);
+        }
+    }
     const gw = new Gateway({
         vault, network, payee,
         deskPort,
@@ -564,8 +612,12 @@ const HELP = `paydlux — get paid by AI agents, with a human in the loop.
 
   paydlux setup [--mainnet] [--token USDC] [--fund-seed S…]
       create a vault. testnet by default (free, no wallet needed).
-  paydlux sell  [--price 1] [--route /api/data] [--split] [--tls] [--preauth]
+  paydlux sell  [--price 1] [--route /api/data] [--max N] [--daily N]
+                [--split] [--tls] [--preauth]
       start the gateway and the approval desk.
+      --max / --daily are your spending mandate: no single payment above --max,
+      and nothing past --daily in a day. The desk refuses at the approve button,
+      so a runaway agent cannot drain the vault even if you approve in error.
   paydlux status
       balances, signers, live mandates, ledger rent.
   paydlux approver [--forget]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Payments for AI agents that a human approves. Spending mandates enforced on the Stellar ledger: 2-of-2 vault, pre-authorised transaction envelopes, HTTP 402, USDC.",
   "type": "module",
   "main": "./dist/index.js",