@metalntwx/metal-agent 0.3.0 → 0.3.1

package/README.md

@@ -2,7 +2,8 @@
 
 The `metal-agent` CLI an agent pays x402 payees on Metal with: create or
 import a key, fund it, pay a URL, look up a settlement, or serve `pay`,
-`fund` and `status` as MCP tools.
+`fund` and `status` as MCP tools, and under a mandate its payouts, status
+and verification.
 
 ```bash
 npm install -g @metalntwx/metal-agent
@@ -52,8 +53,11 @@ which the devnet funds at genesis.
 offer above `--max`, 1 `*USDZ` per payment by default. A refusal at
 verification, by the facilitator or the seller's own check, prints
 `payment refused: <reason>`.
-A refusal at settlement prints `payment refused at settlement: <reason>`,
-with the transaction hash when there is one.
+A refusal at settlement for a reason that moves nothing prints
+`payment refused at settlement: <reason>`, with the transaction hash when
+there is one; both refusals end `nothing was paid`. Any other failed
+settlement, such as one whose answer the seller lost, prints
+`payment in doubt at settlement: <reason>`: it may have settled.
 
 `pay` sends `--method` (GET by default, POST with a body), `--body` (as `application/json`
 unless a `--header` names a content type) and each repeated
@@ -110,7 +114,8 @@ never resets.
 `account create --out <owner key file>` writes the owner's key and creates the
 owner's Metal account on chain, a smart account that key controls with
 threshold one; `--key <file>` uses a key that exists. The owner's key pays the
-gas, and one that holds none is funded first. Fund the account and name it as
+gas, and one that holds too little is funded first. When a later step
+fails, such as a faucet refusal, the error says why and names the key file; the same command continues from it. Fund the account and name it as
 the credential's `--principal`; `bind` refuses an address with no account.
 The account factory is the one `@metalntwx/metal-pay` names for the network;
 on a devnet `just deploy` deploys it there, and `--factory <address>` names
@@ -120,8 +125,9 @@ another. `@metalntwx/metal-pay` names the testnet's.
 its threshold needs. `--key` names the gas sponsor and defaults as the sole
 signer; repeat `--signer-key <file>` to supply the owners' keys of an account
 with several instead. The SDK's `authorizeMandateCall` accepts a signing
-callback for mixed keys and passkeys. Keep owner keys outside the agent's
-reach: an owner key moves the account's funds outside any mandate's limits. `replace` revokes the mandate
+callback for mixed keys and passkeys; the CLI's signatures expire fifteen
+minutes after signing. Keep owner keys outside the agent's reach: an owner key
+moves the account's funds outside any mandate's limits. `replace` revokes the mandate
 `--replaces` names and carries its spend into the new one; `renew` binds the
 new one and revokes the old in one batch, starting its spend at nothing, which
 is how a budget starts over.
@@ -146,10 +152,17 @@ and pays its gas; `--key` names a funded key to submit it instead. A pull
 the mandate refuses when checked is not sent: it reports the reason and
 exits 1. With `--key`, `--record-refusal` sends it, so the refusal is
 recorded on chain in a transaction that succeeds and moves nothing. The
-outcome is read from the chain: `paid`, `refused`, `held` when the payee's
-receive policy sends it to escrow, or `pending`. A pending pull is kept in
-the directory beside the credential, `mandate.pulls` for `mandate.json`, and
-running the same command again sends that same pull, which pays at most once.
+outcome is read from the chain: `paid` (exit 0), `refused` (exit 1), `held`
+(exit 4) when the payee's receive policy sends it to escrow, or `pending`
+(exit 3); an `error:` line also exits 1. Each pull is kept under `~/.metal-agent/pulls/<mandate>/`, and
+running the same command again sends a pending pull again, which pays at
+most once. `--payment-id <id>` names the payment: two payouts of one amount
+to one payee are two payments under two ids, an id whose payout was paid or
+held reports it again, after an `already paid` or `already held` line, and
+sends nothing, and one the account refused may be sent with other values.
+Without it, a payout is known by its payee and amount. A retry from another
+home directory, or under a credential that renewed or replaced this one,
+signs a new payout.
 
 `mandate verify` checks the mandate and every payment under it from the
 chain alone, through any RPC endpoint: the binding on the owner's account,
@@ -158,7 +171,8 @@ refusal as the mandate key's own signed per-payment mandate, rebuilt from its
 transaction. Anyone holding the credential and the issuer's public file,
 passed as `--issuer`, can run it; `--tx <hash>`
 verifies one transaction, with `--signed-offer <text>` the offer the agent
-signed for it, and a check that fails exits 1. A seller that asks for the
+signed for it, and a check that fails exits 1, as does an event under the
+mandate that the SDK does not decode, as an account of another version emits. A seller that asks for the
 agent's signed order (`requireSignedOffer` in `@metalntwx/metal-pay/mandates`,
 with `extra.signedOffer: "required"` on the route) is paid with it, and
 `pay` prints it. From code, `verifyMandate` and `verifyMandatePayment` do
@@ -169,21 +183,29 @@ an agent, then the commands.
 
 `metal-agent mcp` serves `pay`, `fund` and `status` over stdio, each taking
 a `network`, and `pay` the request as optional `method`, `body` and
-`headers`. What `pay` spends is fixed when the server starts: its key and
-`--max` (the default key file and 1 `*USDZ` when omitted), or one mandate
-with `--mandate <credential>`. The model calling the tools chooses no key,
-no mandate and no higher limit; under a key, a `max` it passes can only
-lower the server's. The mandate commands enter only through the CLI. An MCP host
-starts it with:
+`headers`. What `pay` spends is set when the server starts, by whoever
+starts it: a key file and `--max` (the default key file and 1 `*USDZ` when
+omitted), or one mandate's credential file with `--mandate <credential>`,
+which each call reads. Under a mandate it also serves `mandate_pull`,
+`mandate_status` and `mandate_verify`, which run those commands on the
+server's mandate and read the chain through its `METAL_RPC_URL`, or devnet's
+default endpoint. The model calling the tools chooses no key, no mandate and
+no higher limit; under a key, a `max` it passes can only lower the server's.
+The other mandate commands enter only through the CLI. An MCP host starts it
+with:
 
 ```json
 { "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp"] }
 ```
 
-or, under one mandate:
+or, under one mandate, with the endpoint the mandate tools read on testnet:
 
 ```json
-{ "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"] }
+{
+  "command": "npx",
+  "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"],
+  "env": { "METAL_RPC_URL": "<endpoint>" }
+}
 ```
 
 ## Develop

package/dist/commands/fund.js

@@ -8,7 +8,7 @@ const DEVNET_PRINCIPAL_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efc
 // Gas and the 1-per-gas fee are explicit for the reason
 // `buildSubmitAuthorizationTx` gives.
 const FUND_GAS_LIMIT = 200000n;
-export async function fund(target, addressArg, amountArg, print, fetchImpl = fetch) {
+export async function fund(target, addressArg, amountArg, print, fetchImpl = fetch, keyImport = true) {
     if (!addressArg || !isAddress(addressArg))
         throw new Error("fund needs the agent's address");
     const to = getAddress(addressArg);
@@ -16,7 +16,7 @@ export async function fund(target, addressArg, amountArg, print, fetchImpl = fet
         if (amountArg !== undefined) {
             throw new Error("on testnet the faucet sets the amount; run fund without --amount");
         }
-        await fundFromFaucet(target, to, print, fetchImpl);
+        await fundFromFaucet(target, to, print, fetchImpl, keyImport);
         return;
     }
     const publicClient = rpcClient(target);
@@ -29,20 +29,24 @@ export async function fund(target, addressArg, amountArg, print, fetchImpl = fet
     });
     print(`balance ${formatUsdz(balance)} ${USDZ.symbol}`);
 }
-async function fundFromFaucet(target, to, print, fetchImpl) {
+async function fundFromFaucet(target, to, print, fetchImpl, keyImport) {
     if (!target.faucetUrl)
         throw new Error(`no faucet is configured for ${target.network.name}`);
     const url = new URL("/api/fund", target.faucetUrl);
+    // The Metal console funds through the same faucet, so an unreachable one is not sent there.
     const response = await fetchImpl(url, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ address: to, symbol: "USDZ" }),
+    }).catch((error) => {
+        const cause = error.cause;
+        throw new Error(`the faucet at ${url} could not be reached (${typeof cause?.code === "string" ? cause.code : error instanceof Error ? error.message : String(error)}); retry shortly`);
     });
     const text = await response.text();
     if (response.ok) {
         const grant = safeJson(text);
         if (!grant?.txHash || !grant.amount)
-            throw new Error(unexpectedAnswer(url, response, "a transaction"));
+            throw new Error(`${unexpectedAnswer(url, response)} without a transaction`);
         // The faucet answers 200 only once the grant's receipt shows success.
         print(`funded ${to} with ${formatUsdz(grant.amount)} ${USDZ.symbol} from the testnet faucet`);
         print(`transaction ${grant.txHash}`);
@@ -56,27 +60,37 @@ async function fundFromFaucet(target, to, print, fetchImpl) {
         return;
     }
     if (!error && response.status === 429) {
-        throw new Error("faucet answered 429: the faucet's edge rate limit refused this client; retry shortly");
+        throw new Error(`faucet answered 429: the faucet's edge rate limit refused this client; retry shortly${consoleFaucet(target)}`);
     }
+    if (!error && response.status >= 500)
+        throw new Error(`${unexpectedAnswer(url, response)}: the faucet could not be reached; retry shortly`);
     if (!error)
-        throw new Error(unexpectedAnswer(url, response, "an error code"));
-    throw new Error(`faucet answered ${response.status} ${error.code}: ${faucetRefusal(error)}`);
+        throw new Error(`${unexpectedAnswer(url, response)} without an error code`);
+    throw new Error(`faucet answered ${response.status} ${error.code}: ${faucetRefusal(error, consoleFaucet(target), keyImport ? ", or load a funded key with `metal-agent key import`" : "")}`);
+}
+// The public faucet limits every client behind one IP address together; the
+// Metal console's faucet grants per signed-in user, so a refused client is sent there.
+function consoleFaucet(target) {
+    if (!("consoleUrl" in target.network.rpc))
+        return "";
+    // The console's host alone, so a URL redacted to its host still reads.
+    return `, or fund it from the Faucet page of the Metal console at ${target.network.rpc.consoleUrl}, which grants per signed-in user`;
 }
 // Describes the response instead of quoting it, because a proxy in front of
 // the faucet answers with a full HTML document.
-function unexpectedAnswer(url, response, missing) {
+function unexpectedAnswer(url, response) {
     const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim() || "no content type";
-    return `faucet answered ${response.status} ${mediaType} from ${url} without ${missing}`;
+    return `faucet answered ${response.status} ${mediaType} from ${url}`;
 }
-function faucetRefusal(error) {
-    const keyImport = "or load a funded key with `metal-agent key import`";
+function faucetRefusal(error, console, orKeyImport) {
     switch (error.code) {
         case "client_rate_limited":
-            return `this client asked the faucet too recently; ${error.retryAfter === undefined ? "retry shortly" : `retry in ${error.retryAfter} s`}`;
+            return `this client asked the faucet too recently; ${error.retryAfter === undefined ? "retry shortly" : `retry in ${error.retryAfter} s`}${console}`;
         case "client_daily_limit_reached":
-            return `this client reached its daily faucet limit; try tomorrow, ${keyImport}`;
+            return `this client reached its daily faucet limit; try tomorrow${console}${orKeyImport}`;
         case "daily_limit_reached":
-            return `the faucet reached its daily grant limit for every client; try tomorrow, ${keyImport}`;
+            // The Metal console's faucet counts against the same daily limit.
+            return `the faucet reached its daily grant limit for every client; try tomorrow${orKeyImport}`;
         default:
             return error.message;
     }

package/dist/commands/key.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
-import { DEFAULT_KEY_PATH, isPrivateKey, writeKey } from "../keystore.js";
+import { defaultKeyPath, isPrivateKey, writeKey } from "../keystore.js";
 export async function keyCreate(out, print) {
     await store(generatePrivateKey(), out, print);
 }
@@ -13,7 +13,7 @@ export async function keyImport(source, out, print) {
     await store(privateKey, out, print);
 }
 async function store(privateKey, out, print) {
-    const path = out ?? DEFAULT_KEY_PATH;
+    const path = out ?? defaultKeyPath();
     const { address } = privateKeyToAccount(privateKey);
     await writeKey(path, { address, privateKey });
     print(`address ${address}`);