@paydlux/agent 0.1.17 → 0.1.18

package/README.md

@@ -234,11 +234,19 @@ 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.
 
+**The budget survives a restart.** `paydlux sell` asks the ledger what the vault
+already paid that payee today and starts from that number, so `ctrl-c` and
+`npm run app` again does not hand the day back. If the day is already spent it
+refuses to start and says so; if the ledger cannot be read it refuses to start
+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)`.
+
 ### What is enforced where (said honestly)
 
 | enforced by Stellar | enforced by the desk (`policy.ts`) |
 |---|---|
-| 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 |
+| 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 **seeded from the ledger's own payment history**, 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

@@ -227,6 +227,29 @@ async function sell() {
     // payment with no valid payee is a payment that fails an hour later, after
     // the human already said yes.
     const payee = await ensurePayee(path, data, vault);
+    // The daily budget has to survive a restart. Counting only what this process
+    // has seen means `ctrl-c`, `npm run app` again, and the day's total is back to
+    // zero — so the mandate in the banner is a promise the code does not keep.
+    // Ask the ledger what the vault already paid this payee today and start from
+    // there. If the query fails, refuse to start rather than run with a budget
+    // that silently reads as unspent.
+    let alreadyPaid = 0;
+    try {
+        alreadyPaid = Number(await vault.paidToday(payee));
+    }
+    catch (e) {
+        bad(`cannot read today's spending from the ledger (${e?.message ?? e}).\n  `
+            + `the daily budget of ${daily} cannot be enforced without it, so nothing was started. `
+            + `Check the network and try again.`);
+    }
+    policy.seedFromLedger(alreadyPaid);
+    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  `
+                + `the mandate would refuse every payment. Raise --daily or wait for the UTC day to roll over.`);
+        }
+    }
     if (network === "public") {
         console.log(`
   MAINNET — real money.
@@ -316,7 +339,7 @@ async function sell() {
   ${split
         ? "approvals need your phone. this machine holds one of the two keys."
         : "WARNING: this process holds BOTH human keys. Anyone with this machine can approve. Use --split for anything real."}
-  policy: max ${maxPer} per payment, ${daily} per day
+  policy: max ${maxPer} per payment, ${daily} per day${alreadyPaid > 0 ? ` (${(daily - alreadyPaid).toFixed(2)} left today)` : ""}
   ctrl-c to stop
 `);
     // The desk is a queue, not a database. If it dies with a payment parked, the

package/dist/policy.d.ts

@@ -36,6 +36,15 @@ export declare class PolicyEngine {
     policy: Policy;
     constructor(policy?: Partial<Policy>);
     record(e: SpendEvent): void;
+    /**
+     * Seed the day's total from the ledger instead of from this process's memory.
+     *
+     * `events` starts empty, so a fresh seller process believes it has spent
+     * nothing today. The mandate printed in the banner ("20 per day") then only
+     * holds until the next restart. Seeding from the ledger makes the budget a
+     * property of the vault, not of the uptime of whichever machine ran `sell`.
+     */
+    seedFromLedger(amount: number): void;
     /** Everything spent in the current UTC day. */
     spentToday(): number;
     today(): SpendEvent[];

package/dist/policy.js

@@ -13,6 +13,23 @@ export class PolicyEngine {
         this.policy = { ...DEFAULT_POLICY, ...policy };
     }
     record(e) { this.events.push(e); }
+    /**
+     * Seed the day's total from the ledger instead of from this process's memory.
+     *
+     * `events` starts empty, so a fresh seller process believes it has spent
+     * nothing today. The mandate printed in the banner ("20 per day") then only
+     * holds until the next restart. Seeding from the ledger makes the budget a
+     * property of the vault, not of the uptime of whichever machine ran `sell`.
+     */
+    seedFromLedger(amount) {
+        if (!(amount > 0))
+            return;
+        // One synthetic event at the start of the day: it counts toward the total
+        // without pretending to be a payment this process can re-enact.
+        const start = new Date();
+        start.setUTCHours(0, 0, 0, 0);
+        this.record({ at: start.getTime(), amount, payee: "ledger" });
+    }
     /** Everything spent in the current UTC day. */
     spentToday() {
         const start = new Date();

package/dist/vault.d.ts

@@ -103,6 +103,18 @@ export declare class StellarVault {
      */
     txExists(hash: string): Promise<boolean>;
     balance(account?: string): Promise<Amount>;
+    /**
+     * What this vault already paid `payee` in the current UTC day, according to
+     * the ledger — not according to this process's memory.
+     *
+     * Why this exists: the daily budget was counted in a `PolicyEngine` array that
+     * lives only in RAM. Restart the seller and the counter resets to zero, so the
+     * mandate the banner advertises is only as strong as the process uptime. A
+     * seller with `--daily 20` who restarts twice can pay out 60. The ledger
+     * already recorded every payment that went through, so the honest number is a
+     * query away, and it survives restarts, crashes and redeploys.
+     */
+    paidToday(payee: string): Promise<Amount>;
     /**
      * Build a mandate and register it on the vault.
      *

package/dist/vault.js

@@ -191,6 +191,51 @@ export class StellarVault {
         return b?.balance ?? "0";
     }
     // --------------------------------------------------------------- mandates
+    /**
+     * What this vault already paid `payee` in the current UTC day, according to
+     * the ledger — not according to this process's memory.
+     *
+     * Why this exists: the daily budget was counted in a `PolicyEngine` array that
+     * lives only in RAM. Restart the seller and the counter resets to zero, so the
+     * mandate the banner advertises is only as strong as the process uptime. A
+     * seller with `--daily 20` who restarts twice can pay out 60. The ledger
+     * already recorded every payment that went through, so the honest number is a
+     * query away, and it survives restarts, crashes and redeploys.
+     */
+    async paidToday(payee) {
+        const start = new Date();
+        start.setUTCHours(0, 0, 0, 0);
+        let total = 0;
+        let cursor;
+        // Payments are walked backwards from newest, stopping at the UTC midnight
+        // boundary, so the cost is proportional to today's traffic and not to the
+        // account's whole history.
+        for (let page = 0; page < 10; page++) {
+            const url = `${HORIZON_URL[this.network]}/accounts/${this.address}/payments`
+                + `?order=desc&limit=200${cursor ? `&cursor=${cursor}` : ""}`;
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(`ledger payments query failed: ${res.status}`);
+            const recs = (await res.json())?._embedded?.records ?? [];
+            if (!recs.length)
+                break;
+            for (const e of recs) {
+                if (new Date(e.created_at).getTime() < start.getTime())
+                    return total.toFixed(7);
+                if (e.type !== "payment" && e.type !== "claimable_balance_claim")
+                    continue;
+                if (e.to !== payee)
+                    continue;
+                if (e.asset_type === "native")
+                    continue;
+                if (e.asset_code !== this.token.getCode() || e.asset_issuer !== this.token.getIssuer())
+                    continue;
+                total += Number(e.amount);
+            }
+            cursor = recs[recs.length - 1].paging_token;
+        }
+        return total.toFixed(7);
+    }
     /**
      * Build a mandate and register it on the vault.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paydlux/agent",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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",