aeron-wallet 0.2.0 → 0.3.0

package/README.md

@@ -37,7 +37,32 @@ need ETH: the facilitator relays the transaction and pays gas.
 | `session revoke <id>` | Kill a session. It stops paying on its next call. |
 | `mcp` | Run as an MCP server over stdio. The default with no arguments. |
 
-## MCP
+## Install it in an agent
+
+**Claude Code**
+
+```
+/plugin marketplace add aeronlabs/aeron-wallet
+/plugin install aeron-wallet@aeronlabs
+```
+
+**Cursor**
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=aeron-wallet&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFlcm9uLXdhbGxldCIsIm1jcCJdfQ==)
+
+**Gemini CLI**
+
+```bash
+gemini extensions install https://github.com/aeronlabs/aeron-wallet
+```
+
+**VS Code**
+
+```bash
+code --add-mcp '{"name":"aeron-wallet","command":"npx","args":["-y","aeron-wallet","mcp"]}'
+```
+
+**Anything else that speaks MCP**
 
 ```json
 {
@@ -117,6 +142,31 @@ The wallet refuses to sign above either cap, so a loop cannot drain it.
 | `MAX_PER_CALL_USD` | `0.05` | Largest single payment. |
 | `DAILY_CAP_USD` | `1` | Total for the current UTC day. |
 
+## What a result means
+
+A request that comes back 4xx is not one situation, it is three, and they
+differ in the only way that matters: whether the money left the wallet. The
+signal is the settlement receipt — a service that settled returns
+`X-PAYMENT-RESPONSE` with a transaction hash, and one that did not, does not.
+
+| `status` | Charged | What happened |
+|---|---|---|
+| `settled` | yes | The service answered. `reason` is set only in the bad case below. |
+| `rejected` | no | HTTP 402. The service refused the payment; the authorization is unspent. |
+| `failed` | no | The service returned an error *and declined to charge* — usually its own upstream failed. |
+
+The case worth naming: a `settled` row **with** a `reason` means the money
+moved and nothing came back. That is the only outcome where the wallet is out
+of pocket for nothing, so it is reported as itself rather than folded in with
+refusals that cost nothing.
+
+Only `settled` counts against `DAILY_CAP_USD`. A refusal and an upstream
+failure leave the balance untouched, so neither eats into the cap.
+
+`reason` quotes the service's own message when it gave one, instead of a
+generic phrase — an agent operator reading a log needs to know whether to
+retry, top up, or fix the seller.
+
 ## Configuration
 
 | Variable | Default |
@@ -128,6 +178,13 @@ The wallet refuses to sign above either cap, so a loop cannot drain it.
 | `AERON_WALLET_KEY` | unset. Overrides the stored key. |
 | `AERON_WALLET_SESSION` | unset. Binds the whole process to one session. |
 
+## Releases
+
+Published from a tag by GitHub Actions using npm trusted publishing, so no
+long-lived npm token exists to leak and every tarball carries a provenance
+attestation: proof of the commit and workflow it was built from. Verify with
+`npm audit signatures` after installing.
+
 ## Where payments go
 
 Payments settle on Robinhood Chain mainnet in USDG through the Aeron

package/dist/history.js

@@ -30,6 +30,8 @@ export function createHistory(cfg) {
             const midnight = new Date(now);
             midnight.setHours(0, 0, 0, 0);
             return readAll()
+                // Only 'settled' rows moved money. A refusal and an upstream failure both
+                // leave the balance untouched, so neither may eat into the daily cap.
                 .filter((r) => r.status === 'settled' && new Date(r.ts) >= midnight)
                 .reduce((sum, r) => sum + r.amountUsd, 0);
         },

package/dist/outcome.js

@@ -0,0 +1,71 @@
+/**
+ * What actually happened after the wallet handed over a payment.
+ *
+ * "The request came back 4xx" is not one situation, it is three, and they
+ * differ in the only way an agent operator cares about: whether the money
+ * left the wallet.
+ *
+ *   - the service answered           → paid, got the goods
+ *   - the service refused the payment → not charged, the authorization stands
+ *   - the service refused to charge   → not charged, its upstream failed
+ *   - the service charged and failed  → charged, got nothing  ← say this loudly
+ *
+ * The signal is the settlement receipt. A service that settles returns
+ * X-PAYMENT-RESPONSE with a transaction hash; one that did not, does not.
+ */
+/** The service's own words, dug out of whatever shape it used to say them. */
+export function serviceMessage(body) {
+    if (!body.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const error = parsed.error;
+        if (typeof error === 'string' && error.trim())
+            return error.trim();
+        if (error && typeof error === 'object') {
+            const message = error.message;
+            if (typeof message === 'string' && message.trim())
+                return message.trim();
+        }
+        return null;
+    }
+    catch {
+        // Not JSON. A short plain-text body is still better than a generic phrase.
+        const text = body.trim();
+        return text.length <= 200 ? text : null;
+    }
+}
+const withMessage = (fallback, body) => {
+    const message = serviceMessage(body);
+    return message ? `${fallback}: ${message}` : fallback;
+};
+export function describeOutcome(httpStatus, transaction, body) {
+    const charged = transaction !== null;
+    if (httpStatus < 400)
+        return { ok: true, charged, status: 'settled' };
+    if (charged) {
+        // The worst case and the quietest one: the money moved and the caller has
+        // nothing to show for it. Named explicitly so it cannot be mistaken for a
+        // refusal that cost nothing.
+        return {
+            ok: false,
+            charged: true,
+            status: 'settled',
+            reason: withMessage(`charged (${transaction}) but the service then returned HTTP ${httpStatus}`, body),
+        };
+    }
+    if (httpStatus === 402) {
+        return {
+            ok: false,
+            charged: false,
+            status: 'rejected',
+            reason: withMessage('the service refused the payment; you were not charged', body),
+        };
+    }
+    return {
+        ok: false,
+        charged: false,
+        status: 'failed',
+        reason: withMessage(`the service returned HTTP ${httpStatus} and did not charge you`, body),
+    };
+}

package/dist/payer.js

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { hashDomain } from 'viem';
 import { checkSession } from './sessions.js';
+import { describeOutcome } from './outcome.js';
 /** EIP-3009 typed data, mirrored from the facilitator side. */
 const TRANSFER_WITH_AUTHORIZATION_TYPES = {
     TransferWithAuthorization: [
@@ -169,8 +170,10 @@ export async function payX402(url, init, deps) {
             /* receipt header is informational */
         }
     }
-    const settled = second.status < 400;
-    if (settled && binding)
+    // Whether money moved is the settlement receipt's business, not the status
+    // code's: a service can refuse to charge and still answer 4xx.
+    const outcome = describeOutcome(second.status, transaction, secondBody);
+    if (outcome.charged && binding)
         binding.recordSpend(amountUsd);
     history.append({
         ts: new Date().toISOString(),
@@ -178,11 +181,11 @@ export async function payX402(url, init, deps) {
         amountUsd,
         payer: account.address,
         transaction,
-        status: settled ? 'settled' : 'rejected',
-        reason: settled ? undefined : secondBody.slice(0, 200),
+        status: outcome.status,
+        ...(outcome.reason ? { reason: outcome.reason } : {}),
     });
     return {
-        paid: settled, status: second.status, amountUsd, transaction, body: secondBody,
-        reason: settled ? undefined : 'payment rejected by the service',
+        paid: outcome.ok, status: second.status, amountUsd, transaction, body: secondBody,
+        ...(outcome.reason ? { reason: outcome.reason } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aeron-wallet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "io.github.aeronlabs/aeron-wallet",
   "description": "Non-custodial agent wallet for Robinhood Chain. Pays x402 requests in USDG. Ships as a CLI and an MCP server.",
   "license": "MIT",