@metalntwx/metal-agent 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @metalntwx/metal-agent
 
 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 the same
-commands as MCP tools.
+import a key, fund it, pay a URL, look up a settlement, or serve `pay`,
+`fund` and `status` as MCP tools.
 
 ```bash
 npm install -g @metalntwx/metal-agent
@@ -27,8 +27,9 @@ explorer URLs.
 `METAL_RPC_URL` and `METAL_FAUCET_URL` override those defaults, and
 `--rpc-url` and `--faucet-url` override both.
 
-On testnet, `pay` and `fund` need no RPC. `status --network testnet` needs
-an endpoint of your own: sign up in the Metal console,
+On testnet, `pay` and `fund` need no RPC. `status`, `account create` and
+every `mandate` command but `credential create` need an endpoint of your
+own: sign up in the Metal console,
 https://console-testnet.metalntwx.com, create an endpoint, and pass it with
 `--rpc-url` or `METAL_RPC_URL`. On testnet, `pay` and `fund` print
 an `explorer` line with the transaction's page on
@@ -48,7 +49,8 @@ which the devnet funds at genesis.
 
 `pay` refuses, before it signs, an offer in any token but `*USDZ` and any
 offer above `--max`, 1 `*USDZ` per payment by default. A refusal at
-verification prints `payment refused: <reason>`.
+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.
 
@@ -77,28 +79,33 @@ for the mandate's whole life, an expiry and, when `--payee` names any, the
 addresses it may pay; with none named it may pay any address.
 
 ```bash
-metal-agent mandate credential create --principal <MetalAccount address> [--payee <address>]... \
-  --cap 5 --budget 10 --out ./mandate.json --network testnet
+metal-agent mandate credential create --principal <MetalAccount address> [--payee <address>[,<name>[,<website>]]]... \
+  --cap 5 --budget 10 [--description <text>] --key <owner key file> --out ./mandate.json --network testnet
 metal-agent mandate bind --credential ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
 metal-agent pay <url> --mandate ./mandate.json --network testnet
 metal-agent mandate status --credential ./mandate.json --network testnet --rpc-url <endpoint>
+metal-agent mandate pull --credential ./mandate.json --to <address> --amount 2.50 --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --issuer <issuer public key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --issuer <issuer public key file> --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>
 metal-agent mandate replace --credential ./wider.json --replaces ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate renew --credential ./next.json --replaces ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
 metal-agent mandate revoke --credential ./wider.json --key <owner key file> --network testnet --rpc-url <endpoint>
-metal-agent mandate pull --credential ./mandate.json --to <address> --amount 2.50 --network testnet --rpc-url <endpoint>
-metal-agent mandate verify --credential ./mandate.json --network testnet --rpc-url <endpoint>
-metal-agent mandate verify --credential ./mandate.json --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>
 ```
 
 `credential create` writes the limits into a credential file, a Verifiable
 Intent mandate, and the agent's keys beside it: its mandate key in
 `mandate.agent-key.json`, and in `mandate.gas-key.json` the key that pays
 for its pulls. `--agent-key <file>` names a mandate key the agent already
-has instead, with its gas key beside that. The issuer keys that sign the
-credential are created on first use (`~/.metal-agent/issuer.json`, with its
-public half beside it in `issuer.public.json`). Every other command takes
+has instead, with its gas key beside that. The keys that sign the
+credential are the owner's: they live beside the owner's key file, created
+on first use (`owner-key.issuer.json`, with its public half in
+`owner-key.issuer.public.json`), unless `--issuer-key` names their file.
+`--description` says what the mandate is for, and `--payee` takes a name
+and a website after the address. Every other command takes
 that credential file: the owner's account, the mandate's reference, its
-terms and the agent's key files derive from it. Amounts are whole cents; a
-mandate lasts 30 days unless `--expires-in` says otherwise.
+terms and the agent's key files derive from it. Amounts are in `*USDZ`, to the cent; a
+mandate lasts 30 days unless `--expires-in` says otherwise, and its budget
+never resets.
 
 `account create --out <owner key file>` writes the owner's key and names the
 owner's Metal account, a smart account that key controls with threshold one,
@@ -106,8 +113,7 @@ which the owner's first `bind` creates on chain; `--key <file>` uses a key
 that exists. Fund the account and name it as the credential's `--principal`.
 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
-another. The testnet's factory is redeployed with each reset, and
-`@metalntwx/metal-pay` names the current one.
+another. `@metalntwx/metal-pay` names the testnet's.
 
 `bind`, `replace` and `revoke` execute self-calls through the account's weighted
 quorum. `--key` names the gas sponsor and defaults as the sole signer; repeat
@@ -115,30 +121,38 @@ quorum. `--key` names the gas sponsor and defaults as the sole signer; repeat
 The SDK's `authorizeMandateCall` accepts a quorum-signing callback for mixed
 keys and passkeys. Keep owner keys outside the agent's reach: quorum-approved
 transfers remain independent of mandates. `replace` revokes the mandate
-`--replaces` names and carries its spend into the new one.
+`--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.
+`bind`, `replace` and `renew` trust the issuer beside `--key` unless
+`--issuer` names others.
 
 Verification trusts that factory, never one a payer names: it checks the
-account's immutable clone code against the factory's implementation at the
-binding and payment blocks, and checks successful token-transfer receipts.
+account's immutable clone code against the factory's current
+implementation, and checks successful token-transfer receipts.
 
 `pay --mandate <credential>` pays from the owner's account, signed by the
 agent's mandate key, and takes neither `--key` nor `--max`. A payment
-outside the mandate is refused at the facilitator's simulation, which names
-the limit: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
+outside the mandate is refused and moves nothing, usually with a
+`mandate_*` reason: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
 payment's `nonce` as soon as it signs; the facilitator's
 `/settlements?payTo=<payee>` lists a settled payment by an id ending in it.
 
 `mandate pull` pays an address the mandate allows directly, with no seller:
 the agent's mandate key signs, and the `--key` account, the agent's gas key
 by default, submits the transaction and pays its gas, so fund it with a
-little `*USDZ`. A pull outside the mandate is recorded on chain as a
-refusal, in a transaction that succeeds and moves nothing, and exits 1.
+little `*USDZ`. A pull the mandate refuses when checked is not sent: it reports the
+reason and exits 1. `--record-refusal` sends it, so the refusal is recorded
+on chain in a transaction that succeeds and moves nothing. A pull prints
+`transaction <hash>` as soon as it is sent; if its receipt never arrives,
+check that transaction with `metal-agent status <hash>` before pulling again.
 
 `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,
 the credential against it and under its issuer, and each payment and
 refusal as the agent key's own signed per-payment mandate, rebuilt from its
-transaction. Anyone holding the credential can run it; `--tx <hash>`
+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
 agent's signed order (`requireSignedOffer` in `@metalntwx/metal-pay/mandates`,
@@ -149,17 +163,25 @@ the same, the latter for a payee that holds no credential.
 `skills/metal-agent/SKILL.md` is an installable skill: the setup steps for
 an agent, then the commands.
 
-`metal-agent mcp` serves `pay`, `fund` and `status` over stdio,
-each taking a `network`, and `pay` takes the same limit as an optional
-`max`, the request as optional `method`, `body` and `headers`, and a
-credential file as an optional `mandate`, with its `agentKey`. Keys
-enter only through the CLI, and so do the mandate commands: the server has
-no tool that sets or changes a mandate. An MCP host starts it with:
+`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:
 
 ```json
 { "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp"] }
 ```
 
+or, under one mandate:
+
+```json
+{ "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"] }
+```
+
 ## Develop
 
 In the `mx56db/metal` repository, `just agent <command>` runs the CLI from

package/dist/commands/mandate.js

@@ -6,10 +6,11 @@
 // Mandate Binding refuses anything outside the mandate. Every command takes
 // the credential file: the account, the mandate's reference and its terms all
 // derive from it.
-import { readFile, writeFile } from "node:fs/promises";
-import { FEE_PER_GAS, assertMetalAccount, authorizeMandateCall, metalAccountFactoryAbi, MANDATE_MAX_VALIDITY_SECONDS, MANDATE_VALID_AFTER_LEAD_SECONDS, REFUSALS, UNCAPPED_OCCURRENCES, agentKeyOfJwk, bindCall, createCredential, describeRefusal, encodeAgentKey, extractTerms, hashCredential, ingestCredential, mandateBindingAbi, mandateReference, p256DigestSigner, parseCredential, privateKeyHex, pullCall, readMandateState, reasonName, replaceCall, revokeCall, sameAgentKey, sendMandateCall, signL3a, transactionIdOf, trustedIssuer, verifyMandate, verifyMandatePayment, } from "@metalntwx/metal-pay/mandates";
+import { readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { FEE_PER_GAS, assertMetalAccount, authorizeMandateCall, metalAccountFactoryAbi, MANDATE_MAX_VALIDITY_SECONDS, MANDATE_VALID_AFTER_LEAD_SECONDS, REFUSALS, UNCAPPED_OCCURRENCES, agentKeyOfJwk, bindCall, createCredential, describeRefusal, encodeAgentKey, extractTerms, hashCredential, ingestCredential, mandateBindingAbi, mandateReference, p256DigestSigner, parseCredential, privateKeyHex, publicMessage, pullCall, readBoundAgentKey, readCheck, readMandateState, reasonName, replaceCall, revokeCall, sameAgentKey, sendMandateCall, signL3a, transactionIdOf, trustedIssuer, verifyMandate, verifyMandatePayment, } from "@metalntwx/metal-pay/mandates";
 import { USDZ, formatUsdz, usdzBaseUnits } from "@metalntwx/metal-pay";
-import { BaseError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isHash, parseEventLogs, slice, } from "viem";
+import { BaseError, HttpRequestError, TimeoutError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isAddressEqual, isHash, parseEventLogs, slice, } from "viem";
 import { rpcClient } from "../chain.js";
 import { agentKeyPath, exists, gasKeyPath, publicKeyPath, readKey, readOrCreateIssuerKeys, readOrCreateKey, readOrCreateP256Key, readP256Key, readTrustedIssuer, writePublicKeyFile, } from "../keystore.js";
 export async function loadMandate(credentialPath) {
@@ -17,7 +18,7 @@ export async function loadMandate(credentialPath) {
     const terms = extractTerms(credential);
     return { credential, terms, reference: mandateReference(terms.principal, terms.agentKey, hashCredential(credential)) };
 }
-/** A decimal `*USDZ` amount in whole cents, as a credential states its cap and budget. */
+/** A decimal `*USDZ` amount to the cent, as a credential states its cap and budget. */
 export function parseCents(text, option) {
     if (text === undefined || !/^\d+(\.\d{1,2})?$/.test(text) || Number(text) <= 0) {
         throw new Error(`${option} must be a positive ${USDZ.symbol} amount with at most 2 decimals; got "${text ?? ""}"`);
@@ -29,6 +30,19 @@ export function parseAddress(text, option) {
         throw new Error(`${option} must be an address; got "${text ?? ""}"`);
     return getAddress(text);
 }
+/** `<address>[,<name>[,<website>]]`, as `--payee` takes it. */
+export function parsePayee(text, option) {
+    const [address, name, website, ...rest] = (text ?? "").split(",").map((part) => part.trim());
+    if (address === undefined || !isAddress(address))
+        throw new Error(`${option} must start with an address, then optionally a name and a website, comma-separated; got "${text ?? ""}"`);
+    if (rest.length > 0)
+        throw new Error(`${option} takes at most an address, a name and a website; got "${text ?? ""}"`);
+    if (name === "")
+        throw new Error(`${option}'s name is empty; leave it out to show the address; got "${text ?? ""}"`);
+    if (website !== undefined && !/^https?:\/\/[^\s]+$/.test(website))
+        throw new Error(`${option}'s website must be an http or https URL; got "${website}"`);
+    return { address: getAddress(address), ...(name !== undefined && { name }), ...(website !== undefined && { website }) };
+}
 export function parseTxHash(text, option) {
     if (!isHash(text))
         throw new Error(`${option} must be a transaction hash; got "${text}"`);
@@ -46,7 +60,11 @@ export function parseCount(text, option) {
 const usdz = (units) => `${formatUsdz(units)} ${USDZ.symbol}`;
 const utc = (seconds) => new Date(Number(seconds) * 1000).toISOString();
 const day = (seconds) => new Date(seconds * 1000).toISOString().slice(0, 10);
-function printTerms({ principal, agentKey, constraints: c, terms }, print) {
+function printTerms({ principal, agentKey, constraints: c, terms, descriptive }, print) {
+    // The credential's own text is shown with control, line-separator, bidi and invisible characters replaced, so it cannot start a line,
+    // reorder one or hide text; the joiners scripts and emoji need are kept.
+    if (typeof descriptive.promptSummary === "string")
+        print(`description ${descriptive.promptSummary.replace(/[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu, "?")}`);
     print(`principal ${principal}`);
     print(`agent-key ${encodeAgentKey(agentKey)} (P-256)`);
     print(`token ${c.token}`);
@@ -57,8 +75,13 @@ function printTerms({ principal, agentKey, constraints: c, terms }, print) {
         print(`max-occurrences ${c.maxOccurrences}`);
     if (terms.payees.length === 0)
         print("payees any");
-    for (const payee of terms.payees)
-        print(`payee ${payee.account}`);
+    const shown = Array.isArray(descriptive.payees) ? descriptive.payees : [];
+    for (const payee of terms.payees) {
+        const object = shown.find((o) => typeof o.id === "string" && o.id.toLowerCase() === payee.account.toLowerCase());
+        const name = typeof object?.name === "string" && object.name.toLowerCase() !== payee.account.toLowerCase() ? ` ${object.name}` : "";
+        const website = typeof object?.website === "string" && /^https?:/.test(object.website) ? ` ${object.website}` : "";
+        print(`payee ${payee.account}${name}${website}`.replace(/[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu, "?"));
+    }
 }
 function walletFor(publicClient, account) {
     if (!publicClient.chain)
@@ -99,34 +122,46 @@ export async function credentialCreate(target, args, print) {
     const agent = await readOrCreateP256Key(agentPath);
     const gasPath = gasKeyPath(agentPath);
     const gas = await readOrCreateKey(gasPath);
-    const { keys, created } = await readOrCreateIssuerKeys(args.issuerKeyPath);
+    const { keys, created } = await readOrCreateIssuerKeys(args.issuerKeyPath).catch(async (error) => {
+        await Promise.all([agent.created && rm(agentPath), gas.created && rm(gasPath)]);
+        throw error;
+    });
     const now = Math.floor(Date.now() / 1000);
     const expiresAt = now + args.expiresIn;
-    const credential = await createCredential({
-        issuer: keys.issuer,
-        principal: args.principal,
-        principalKey: keys.principalKey,
-        agentKey: agent.key.publicJwk,
-        perPaymentCap: args.cap,
-        budget: args.budget,
-        payees: args.payees.map((address) => ({ address, name: address, website: `eip155:${target.network.chainId}:${address}` })),
-        recurrence: {
-            frequency: "ADHO",
-            startDate: day(now),
-            endDate: day(expiresAt),
-            ...(args.maxOccurrences !== undefined && { maxOccurrences: args.maxOccurrences }),
-        },
-        issuedAt: now,
-        expiresAt,
-        description: args.description,
-    });
-    const ingested = await ingestCredential(credential, { trustedIssuers: [trustedIssuer(keys.issuer)], account: args.principal, now });
+    let credential;
+    let ingested;
+    try {
+        credential = await createCredential({
+            issuer: keys.issuer,
+            principal: args.principal,
+            principalKey: keys.principalKey,
+            agentKey: agent.key.publicJwk,
+            perPaymentCap: args.cap,
+            budget: args.budget,
+            payees: args.payees.map(({ address, name, website }) => ({ address, name: name ?? address, website: website ?? `eip155:${target.network.chainId}:${address}` })),
+            recurrence: {
+                frequency: "ADHO",
+                startDate: day(now),
+                endDate: day(expiresAt),
+                ...(args.maxOccurrences !== undefined && { maxOccurrences: args.maxOccurrences }),
+            },
+            issuedAt: now,
+            expiresAt,
+            description: args.description,
+        });
+        ingested = await ingestCredential(credential, { trustedIssuers: [trustedIssuer(keys.issuer)], account: args.principal, now });
+    }
+    catch (error) {
+        // The keys this run created name nothing yet; removing them lets the corrected command run again.
+        await Promise.all([agent.created && rm(agentPath), gas.created && rm(gasPath), created && rm(args.issuerKeyPath)]);
+        throw error;
+    }
     await writeFile(args.out, `${JSON.stringify(credential, null, 2)}\n`, { flag: "wx" });
     const issuerPublicPath = publicKeyPath(args.issuerKeyPath);
     await writePublicKeyFile(issuerPublicPath, trustedIssuer(keys.issuer));
     print(`credential ${args.out}`);
     print(`reference ${ingested.reference}`);
-    printTerms(ingested, print);
+    printTerms(ingested.extracted, print);
     print(`agent-key-file ${agentPath}${agent.created ? " (created)" : ""}`);
     print(`gas-key-file ${gasPath}${gas.created ? " (created)" : ""}`);
     print(`gas-key-address ${gas.address}`);
@@ -173,6 +208,9 @@ export async function accountCreate(target, args, print) {
     print(`keyfile ${keyPath}${created ? " (created)" : ""}`);
 }
 async function sendOwnerCall(client, args, call, createAccount = false) {
+    const account = (Array.isArray(call) ? call[0] : call)?.to;
+    if (account === undefined)
+        throw new Error("no account call to send");
     const sponsor = await readKey(args.keyPath);
     const signers = await Promise.all((args.signerPaths.length === 0 ? [args.keyPath] : args.signerPaths).map(readKey));
     signers.sort((a, b) => a.address.toLowerCase().localeCompare(b.address.toLowerCase()));
@@ -181,14 +219,14 @@ async function sendOwnerCall(client, args, call, createAccount = false) {
     // A one-owner account is created by its owner's first bind; the sponsor pays.
     // One with several signers is created by the factory beforehand, with its
     // signers, weights and threshold, which these key files alone do not name.
-    const code = createAccount ? await client.getCode({ address: call.to }) : "0x01";
+    const code = createAccount ? await client.getCode({ address: account }) : "0x01";
     if ((code === undefined || code === "0x") && args.signerPaths.length > 0) {
-        throw new Error(`${call.to} has no code: create the account first, through MetalAccountFactory.createAccount with its signers, weights and threshold; only a one-owner account is created by its owner's first bind`);
+        throw new Error(`${account} has no code: create the account first, through MetalAccountFactory.createAccount with its signers, weights and threshold; only a one-owner account is created by its owner's first bind`);
     }
     if (code === undefined || code === "0x") {
         const { config, address } = await ownerAccount(client, args.accountFactory, sponsor.address);
-        if (address.toLowerCase() !== call.to.toLowerCase())
-            throw new Error(`${call.to} is not the account of ${sponsor.address}; it has no code, and only its owner's first bind creates it`);
+        if (address.toLowerCase() !== account.toLowerCase())
+            throw new Error(`${account} is not the account of ${sponsor.address}; it has no code, and only its owner's first bind creates it`);
         await send(client, sponsor, { to: args.accountFactory, data: encodeFunctionData({ abi: metalAccountFactoryAbi, functionName: "createAccount", args: config }), gas: 600000n, maxFeePerGas: FEE_PER_GAS, maxPriorityFeePerGas: FEE_PER_GAS });
     }
     const authorized = await authorizeMandateCall(client, args.accountFactory, call, async (digest) => encodeAbiParameters(parseAbiParameters("bytes[], bytes[]"), [signers.map(s => s.address), await Promise.all(signers.map(s => s.sign({ hash: digest })))]));
@@ -201,11 +239,20 @@ export async function mandateBind(target, args, print) {
     print(`bound ${ingested.reference}`);
     printSent(target, receipt, print);
 }
+/** Checks that the mandate a replace or renew ends is bound and not yet revoked, which the account's revert would not say. */
+async function assertLive(publicClient, mandate, path) {
+    const state = await publicClient.readContract({ address: mandate.terms.principal, abi: mandateBindingAbi, functionName: "mandates", args: [mandate.reference] });
+    if (!isAddressEqual(state.principal, mandate.terms.principal))
+        throw new Error(`${path} is not bound on ${mandate.terms.principal}; bind the new credential with mandate bind`);
+    if (state.revoked)
+        throw new Error(`${path} is already revoked; bind the new credential with mandate bind`);
+}
 /** Binds the credential as the successor of the mandate `replacesPath` describes, which is revoked in the same transaction; the successor carries its spend. */
 export async function mandateReplace(target, args, print) {
     const { ingested } = await ingestFor(args);
     const predecessor = await loadMandate(args.replacesPath);
     const publicClient = rpcClient(target);
+    await assertLive(publicClient, predecessor, args.replacesPath);
     const carried = await readMandateState(publicClient, predecessor.terms.principal, predecessor.reference);
     if (carried.spent >= ingested.constraints.budget)
         throw new Error(`the replacement's budget of ${usdz(ingested.constraints.budget)} is not above the ${usdz(carried.spent)} already spent, which it carries`);
@@ -218,6 +265,28 @@ export async function mandateReplace(target, args, print) {
     print(`spent ${usdz(state.spent)} of ${usdz(ingested.constraints.budget)}`);
     printSent(target, receipt, print);
 }
+/**
+ * Binds the credential as a fresh mandate and revokes the one `replacesPath`
+ * describes, in one account batch: the new budget starts at zero spent, as a
+ * budget never resets on its own. `replace` carries the spend over instead.
+ */
+export async function mandateRenew(target, args, print) {
+    const { ingested } = await ingestFor(args);
+    const predecessor = await loadMandate(args.replacesPath);
+    if (predecessor.reference === ingested.reference)
+        throw new Error(`${args.replacesPath} is the mandate being bound; to end it, use mandate revoke`);
+    if (predecessor.terms.principal.toLowerCase() !== ingested.principal.toLowerCase()) {
+        throw new Error(`${args.replacesPath} is a mandate on ${predecessor.terms.principal}, not on ${ingested.principal}`);
+    }
+    const publicClient = rpcClient(target);
+    await assertLive(publicClient, predecessor, args.replacesPath);
+    const receipt = await sendOwnerCall(publicClient, args, [bindCall(ingested), revokeCall(ingested.principal, predecessor.reference)]);
+    const state = await readMandateState(publicClient, ingested.principal, ingested.reference);
+    print(`revoked ${predecessor.reference}`);
+    print(`bound ${ingested.reference}`);
+    print(`spent ${usdz(state.spent)} of ${usdz(ingested.constraints.budget)}`);
+    printSent(target, receipt, print);
+}
 export async function mandateRevoke(target, args, print) {
     const { reference, terms } = await loadMandate(args.credentialPath);
     const receipt = await sendOwnerCall(rpcClient(target), args, revokeCall(terms.principal, reference));
@@ -278,7 +347,18 @@ export async function mandateVerify(target, args, print) {
 }
 /** The agent's P-256 key, checked to be the one the mandate names. */
 export async function mandateAgentSigner(mandate, agentKeyPath) {
-    const agent = await readP256Key(agentKeyPath);
+    const agent = await readP256Key(agentKeyPath).catch(async (error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+        // A replacement credential names the agent key it was made with, which sits beside the first credential.
+        const dir = dirname(agentKeyPath);
+        for (const file of (await readdir(dir)).filter((name) => name.endsWith(".agent-key.json"))) {
+            const key = await readP256Key(join(dir, file)).catch(() => undefined);
+            if (key && sameAgentKey(agentKeyOfJwk(key.publicJwk), mandate.terms.agentKey))
+                throw new Error(`no agent key at ${agentKeyPath}; this mandate's agent key is ${join(dir, file)}: pass --agent-key ${join(dir, file)}`);
+        }
+        throw new Error(`no agent key at ${agentKeyPath}; pass --agent-key with the agent-key-file that credential create printed for it`);
+    });
     if (!sameAgentKey(agentKeyOfJwk(agent.publicJwk), mandate.terms.agentKey))
         throw new Error(`${agentKeyPath} is not the mandate's agent key`);
     return p256DigestSigner(privateKeyHex(agent));
@@ -301,9 +381,12 @@ function revertName(error) {
 /**
  * A direct payment under the mandate, with no seller: the agent signs it and
  * the `--key` account submits it to `pull` on the principal's account and
- * pays the gas. It settles, or Mandate Binding records its refusal with the
- * reason, in a transaction that succeeds; the outcome is returned so a
- * refusal can fail the command.
+ * pays the gas. One the mandate refuses when checked is reported and not
+ * sent, as an x402 payment is refused before anything is sent, unless
+ * `recordRefusal` asks for Mandate Binding to record the refusal on chain.
+ * The transaction is printed as soon as it is sent, so a pull whose receipt
+ * is lost is still found. The outcome is returned so a refusal can fail the
+ * command.
  */
 export async function mandatePull(target, args, print) {
     const mandate = await loadMandate(args.credentialPath);
@@ -314,6 +397,20 @@ export async function mandatePull(target, args, print) {
         throw error;
     });
     const { terms, reference } = mandate;
+    const publicClient = rpcClient(target);
+    // A mandate not yet bound, or before its dates, can stop refusing; these are
+    // checked before the agent signs, so a pull reported unsent can never pay later.
+    const [bound, block, gas] = await Promise.all([
+        publicClient.getCode({ address: terms.principal }).then((code) => (code === undefined || code === "0x" ? undefined : readBoundAgentKey(publicClient, terms.principal, reference))),
+        publicClient.getBlock(),
+        publicClient.getBalance({ address: sender.address }),
+    ]);
+    if (bound === undefined)
+        throw new Error(`the mandate ${reference} is not bound on ${terms.principal}; the owner binds it with mandate bind`);
+    if (block.timestamp < terms.constraints.recurrenceStart && !args.recordRefusal)
+        return printUnsent("OutsideRecurrence", print);
+    if (gas === 0n)
+        throw new Error(`${sender.address}, which submits the pull, holds no gas: fund it, the gas-key-address credential create printed, and run the pull again`);
     const chainId = target.network.chainId;
     const now = BigInt(Math.floor(Date.now() / 1000));
     const signed = await signL3a({
@@ -336,17 +433,39 @@ export async function mandatePull(target, args, print) {
         iss: terms.terms.kid,
         signDigest,
     });
-    const publicClient = rpcClient(target);
     const call = pullCall(terms.principal, signed.pull, signed.fields);
     try {
         // At the node's own gas ceiling: what the pull costs is sendMandateCall's to estimate.
         await publicClient.call({ account: sender.address, to: call.to, data: call.data });
     }
     catch (error) {
+        if (lostInTransport(error))
+            throw new Error(`the pull could not be checked: ${publicMessage(error)}`);
         throw new Error(`Mandate Binding rejects the pull and records nothing: ${revertName(error)}`);
     }
-    const receipt = await send(publicClient, sender, call);
-    const outcome = parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, eventName: ["MandatePayment", "MandateRefused"] }).find((log) => log.address.toLowerCase() === terms.principal.toLowerCase() && log.args.l3aDigest === slice(signed.pull.nonce, 12));
+    const reason = await readCheck(publicClient, terms.principal, signed.pull, signed.fields);
+    if (reason !== "None" && !args.recordRefusal)
+        return printUnsent(reason, print);
+    const hash = await sendMandateCall(publicClient, walletFor(publicClient, sender), call);
+    // Printed before the wait: a pull whose receipt never arrives is still found by its transaction.
+    print(`transaction ${hash}`);
+    const receipt = await confirm(publicClient, hash).catch((error) => {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}; the pull was sent in transaction ${hash}: check it with metal-agent status ${hash} before pulling again`);
+    });
+    return printPull(target, terms, slice(signed.pull.nonce, 12), receipt, print);
+}
+/** Whether the request failed on its way, so the node may or may not have acted on it. */
+function lostInTransport(error) {
+    return error instanceof BaseError && error.walk((e) => e instanceof HttpRequestError || e instanceof TimeoutError) !== null;
+}
+function printUnsent(reason, print) {
+    print("outcome refused, not sent");
+    print(`reason ${describeRefusal(reason)}`);
+    print("recorded no");
+    return "refused";
+}
+function printPull(target, terms, l3aDigest, receipt, print) {
+    const outcome = parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, eventName: ["MandatePayment", "MandateRefused"] }).find((log) => log.address.toLowerCase() === terms.principal.toLowerCase() && log.args.l3aDigest === l3aDigest);
     if (outcome?.eventName === "MandatePayment") {
         print("outcome paid");
         print(`spent ${usdz(outcome.args.spent)} of ${usdz(terms.constraints.budget)}`);
@@ -362,12 +481,14 @@ export async function mandatePull(target, args, print) {
         throw new Error(`transaction ${receipt.transactionHash} carries neither a payment nor a refusal for the pull`);
     }
     print(`payer ${terms.principal}`);
-    print(`payee ${signed.pull.to}`);
-    print(`amount ${usdz(signed.pull.value)}`);
-    printSent(target, receipt, print);
+    print(`payee ${outcome.args.to}`);
+    print(`amount ${usdz(outcome.args.amount)}`);
+    if (target.explorerUrl)
+        print(`explorer ${target.explorerUrl}/tx/${receipt.transactionHash}`);
+    print(`gas ${receipt.gasUsed}`);
     return outcome.eventName === "MandatePayment" ? "paid" : "refused";
 }
-/** A decimal `*USDZ` amount a mandate can pay: positive, in whole cents. */
+/** A decimal `*USDZ` amount a mandate can pay: positive, to the cent. */
 export function parsePullAmount(text, option) {
     return BigInt(usdzBaseUnits(parseCents(text, option)));
 }

package/dist/commands/pay.js

@@ -102,6 +102,9 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
             const how = raise !== undefined && aborted[1].endsWith("limit per payment") ? `; ${raise}` : "";
             throw new Error(`payment refused before signing: ${aborted[1]}${how}`);
         }
+        if (signed !== undefined) {
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; a payment was signed and may have settled; look it up by its nonce before paying again`);
+        }
         throw error;
     });
     const body = await response.text();
@@ -113,14 +116,17 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
         const priced = offer ? `${formatUsdz(offer.amount)} ${USDZ.symbol} on ${offer.network}` : "no offer";
         throw new Error(`payment refused: ${describeRefusalReason(required.error)} (offer: ${priced})`);
     }
-    if (response.status === 402 && paymentResponse) {
-        throw new Error(`payment refused at settlement: ${settleRefusal(decodePaymentResponseHeader(paymentResponse))}`);
+    const settlement = paymentResponse ? decodePaymentResponseHeader(paymentResponse) : undefined;
+    if (settlement !== undefined && !settlement.success)
+        throw new Error(`payment refused at settlement: ${settleRefusal(settlement)}`);
+    // A redirect is reported, not an error: the payment may have settled, and `location` says where it points.
+    if (response.status >= 400) {
+        // A seller that fails after the payment was signed may have settled it first.
+        const doubt = signed !== undefined && response.status >= 500 ? "; a payment was signed and may have settled; look it up by its nonce before paying again" : "";
+        throw new Error(`${url} answered ${response.status}: ${body}${doubt}`);
     }
-    if (!response.ok)
-        throw new Error(`${url} answered ${response.status}: ${body}`);
     print(`status ${response.status}`);
-    if (paymentResponse) {
-        const settlement = decodePaymentResponseHeader(paymentResponse);
+    if (settlement !== undefined) {
         print(`payer ${settlement.payer ?? payer}`);
         if (signed) {
             print(`payee ${signed.payTo}`);
@@ -131,6 +137,9 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
         if (target.explorerUrl)
             print(`explorer ${target.explorerUrl}/tx/${settlement.transaction}`);
     }
+    else if (signed !== undefined) {
+        print("payment unconfirmed (signed, but the seller returned no settlement; look it up by its nonce)");
+    }
     else {
         print("payment none (the resource did not ask for one)");
     }

package/dist/help.js

@@ -0,0 +1,118 @@
+import { DEFAULT_KEY_PATH } from "./keystore.js";
+const NETWORK = "--network devnet|testnet";
+const COMMANDS = [
+    {
+        name: "key create",
+        usage: "metal-agent key create [--out <file>]",
+        about: `Generates the agent's key and writes it to a key file only its owner can read, ${DEFAULT_KEY_PATH} unless --out names another. It never overwrites a key file.`,
+    },
+    {
+        name: "key import",
+        usage: "metal-agent key import <file|hex> [--out <file>]",
+        about: "Loads a key someone funded for you: a hex key, a file holding one, or a key file. Prints the address, never the key.",
+    },
+    {
+        name: "fund",
+        usage: `metal-agent fund <address> --network devnet [--amount <usdz>]\nmetal-agent fund <address> --network testnet`,
+        about: "On testnet, asks the public faucet, which sets the amount. On devnet, moves *USDZ from the devnet's pre-funded account, 10 by default.",
+    },
+    {
+        name: "pay",
+        usage: `metal-agent pay <url> ${NETWORK} [--key <file>] [--max <usdz>]\n                  [--method <method>] [--body <text>] [--header 'name: value']...\nmetal-agent pay <url> --mandate <credential> ${NETWORK} [--agent-key <file>]`,
+        about: "Requests the URL and pays its x402 offer in *USDZ. With --key, the agent pays from its own key and refuses, before signing, any offer above --max (1 *USDZ by default). With --mandate, it pays from the owner's account within the mandate's limits, signed by the agent's mandate key, the <credential>.agent-key.json beside the credential unless --agent-key names another. --method (GET by default, POST with a --body), --body (application/json unless a --header names a content type) and each --header are sent again with the payment.",
+    },
+    {
+        name: "status",
+        usage: `metal-agent status <txHash> ${NETWORK} [--rpc-url <url>]`,
+        about: "Shows a settlement from chain data: status, block, submitter, gas, and the transfer it carried. On testnet it needs an RPC endpoint of your own.",
+    },
+    {
+        name: "mcp",
+        usage: "metal-agent mcp [--key <file>] [--max <usdz>]\nmetal-agent mcp --mandate <credential> [--agent-key <file>]",
+        about: "Serves pay, fund and status as MCP tools over stdio. What pay spends is fixed here, by whoever starts the server: its key and --max, or one mandate. The model calling the tools reads pages and offers anyone can write, so it can choose no other key, no mandate and no higher limit; under a key, a max it passes can only lower the server's.",
+    },
+    {
+        name: "account create",
+        usage: `metal-agent account create --out <owner key file to create> | --key <owner key file> ${NETWORK}`,
+        about: "Names the owner's Metal account, a smart account the owner's key controls, and prints its address, the --principal of the owner's credentials. It sends nothing: the owner's first bind creates the account on chain. Keep the owner's key where no agent can read it.",
+    },
+    {
+        name: "mandate credential create",
+        usage: `metal-agent mandate credential create --principal <address> --cap <usdz> --budget <usdz> --out <file>\n                  --key <owner key file> | --issuer-key <file> ${NETWORK}\n                  [--payee <address>[,<name>[,<website>]]]... [--expires-in <seconds>] [--max-occurrences <n>]\n                  [--description <text>] [--agent-key <file>]`,
+        about: "Writes the limits an agent pays within into a credential file: the most per payment (--cap), the most in total over the mandate's whole life (--budget, which never resets), an expiry (--expires-in, 30 days by default) and, when --payee names any, the addresses it may pay, each with an optional name and website. Amounts are in *USDZ, to the cent. The agent's mandate key and the gas key for its pulls are written beside the credential unless --agent-key names a mandate key the agent already has. The keys that sign the credential are the owner's: they live beside the owner's key file, <key>.issuer.json, created on first use, unless --issuer-key names their file.",
+    },
+    {
+        name: "mandate bind",
+        usage: `metal-agent mandate bind --credential <file> --key <owner key file> ${NETWORK} [--issuer <file>]... [--signer-key <file>]...`,
+        about: "Binds the credential on the owner's account, which then pays under it. The account's quorum signs: --key pays the gas and is the sole signer unless repeated --signer-key names the quorum's keys. --issuer names the issuers whose credentials the owner accepts, the <key>.issuer.public.json beside the owner's key by default.",
+    },
+    {
+        name: "mandate replace",
+        usage: `metal-agent mandate replace --credential <file> --replaces <file> --key <owner key file> ${NETWORK}\n                  [--issuer <file>]... [--signer-key <file>]...`,
+        about: "Binds the credential in place of the mandate --replaces names, which is revoked in the same transaction. What was spent carries over into the new budget.",
+    },
+    {
+        name: "mandate renew",
+        usage: `metal-agent mandate renew --credential <file> --replaces <file> --key <owner key file> ${NETWORK}\n                  [--issuer <file>]... [--signer-key <file>]...`,
+        about: "Binds the credential as a fresh mandate and revokes the one --replaces names, in one transaction. The new budget starts with nothing spent; this is how a budget starts over, since it never resets on its own.",
+    },
+    {
+        name: "mandate revoke",
+        usage: `metal-agent mandate revoke --credential <file> --key <owner key file> ${NETWORK} [--signer-key <file>]...`,
+        about: "Revokes the mandate: every later payment under it is refused.",
+    },
+    {
+        name: "mandate status",
+        usage: `metal-agent mandate status --credential <file> ${NETWORK}`,
+        about: "Shows the mandate's limits and where it stands: bound or not, revoked or not, what is spent of the budget and how many payments were made.",
+    },
+    {
+        name: "mandate pull",
+        usage: `metal-agent mandate pull --credential <file> --to <address> --amount <usdz> ${NETWORK}\n                  [--key <file>] [--agent-key <file>] [--record-refusal]`,
+        about: "Pays an address the mandate allows, with no seller. The --key account, the agent's gas key by default, submits it and pays its gas. A payout the mandate would refuse is reported and not sent, and the command exits 1; --record-refusal sends it so the refusal is recorded on chain. It prints the transaction as soon as it is sent; if the receipt never arrives, check it with metal-agent status before pulling again.",
+    },
+    {
+        name: "mandate verify",
+        usage: `metal-agent mandate verify --credential <file> --issuer <file>... ${NETWORK} [--tx <hash> [--signed-offer <text>]]`,
+        about: "Checks the mandate and every payment under it from the chain alone, or one --tx: the binding, the credential against it and under an --issuer you trust, and each payment as the agent key's signed per-payment mandate. With --signed-offer, the order the agent signed for that payment, as pay printed it. A check that fails exits 1.",
+    },
+];
+const SHARED = `Chain commands also take --rpc-url and --faucet-url, which override
+METAL_RPC_URL and METAL_FAUCET_URL, which override each network's defaults.
+On testnet, status, account create and the mandate commands other than
+credential create need an RPC endpoint of your own:
+sign up in the Metal console and create one. account create and the mandate
+commands take --factory <address> when the network's MetalAccountFactory is
+not the one metal-agent knows.
+
+metal-agent <command> --help explains one command.`;
+/** The whole command list, or the commands the given words name, with what each does. */
+export function helpFor(words) {
+    // The longest run of leading words that names a command or a group: arguments after it are not part of the name.
+    for (let n = words.length; n > 0; n--) {
+        const asked = words.slice(0, n).join(" ");
+        const exact = COMMANDS.find((c) => c.name === asked);
+        if (exact)
+            return `${exact.usage}\n\n${wrap(exact.about)}`;
+        const group = COMMANDS.filter((c) => c.name.startsWith(`${asked} `));
+        if (group.length > 0)
+            return group.map((c) => `${c.usage}\n\n${wrap(c.about)}`).join("\n\n");
+    }
+    return `metal-agent: pay x402 sellers on Metal, and set spending limits Metal enforces for an agent\n\n${COMMANDS.map((c) => c.usage).join("\n")}\n\n${SHARED}`;
+}
+function wrap(text, width = 78) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line !== "" && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line === "" ? word : `${line} ${word}`;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    return lines.join("\n");
+}

package/dist/index.js

@@ -5,82 +5,12 @@ import { redactUrls } from "@metalntwx/metal-pay/mandates";
 import { target } from "./chain.js";
 import { fund } from "./commands/fund.js";
 import { keyCreate, keyImport } from "./commands/key.js";
-import { credentialCreate, accountCreate, mandateBind, mandatePull, mandateReplace, mandateRevoke, mandateStatus, mandateVerify, parseAddress, parseCents, parseCount, parseTxHash, parsePullAmount, } from "./commands/mandate.js";
+import { credentialCreate, accountCreate, mandateBind, mandatePull, mandateRenew, mandateReplace, mandateRevoke, mandateStatus, mandateVerify, parseAddress, parseCents, parseCount, parsePayee, parseTxHash, parsePullAmount, } from "./commands/mandate.js";
 import { parseHeaders, parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.js";
-import { DEFAULT_ISSUER_KEY_PATH, DEFAULT_KEY_PATH, agentKeyPath, gasKeyPath, publicKeyPath, readKey } from "./keystore.js";
-import { serveMcp } from "./mcp.js";
-const USAGE = `metal-agent: pay x402 sellers on Metal
-
-  metal-agent key create [--out <file>]
-  metal-agent key import <file|hex> [--out <file>]
-  metal-agent fund <address> --network devnet [--amount <usdz>]
-  metal-agent fund <address> --network testnet      from the public faucet, which sets the amount
-  metal-agent pay <url> --network devnet|testnet [--key <file>] [--max <usdz>]
-                    [--method <method>] [--body <text>] [--header 'name: value']...
-  metal-agent pay <url> --mandate <credential> --network devnet|testnet [--agent-key <file>]
-  metal-agent status <txHash> --network devnet|testnet [--rpc-url <url>]
-  metal-agent mcp                                   serve pay, fund and status as MCP tools over stdio
-
-Spending limits an account's owner sets for an agent, which Metal enforces:
-
-  metal-agent account create --out <owner key file to create> | --key <owner key file> --network devnet|testnet
-
-  metal-agent mandate credential create --principal <address> --cap <usdz> --budget <usdz> --out <file>
-                    --network devnet|testnet [--payee <address>]... [--expires-in <seconds>] [--max-occurrences <n>]
-                    [--description <text>] [--agent-key <file>] [--issuer-key <file>]
-  metal-agent mandate bind --credential <file> --key <owner key file> --network devnet|testnet [--issuer <file>]...
-  metal-agent mandate replace --credential <file> --replaces <file> --key <owner key file> --network devnet|testnet
-                    [--issuer <file>]...
-  metal-agent mandate revoke --credential <file> --key <owner key file> --network devnet|testnet
-  metal-agent mandate status --credential <file> --network devnet|testnet
-  metal-agent mandate pull --credential <file> --to <address> --amount <usdz> --network devnet|testnet
-                    [--key <file>] [--agent-key <file>]
-  metal-agent mandate verify --credential <file> --network devnet|testnet [--tx <hash> [--signed-offer <text>]]
-                    [--issuer <file>]...
-
-Chain commands also take --rpc-url and --faucet-url, which override
-METAL_RPC_URL and METAL_FAUCET_URL, which override each network's defaults:
-the RPC from @metalntwx/metal-pay, the faucet from the shipped networks.json.
-status reads the chain: on devnet the network default applies; on testnet,
-sign up in the Metal console, create an endpoint, and pass it.
-
-pay refuses, before signing, any offer above --max *USDZ (1 by default). It
-sends --method (GET by default, POST with a --body), --body (as
-application/json unless a --header names a content type) and each --header,
-and sends them again with the payment.
-
-A mandate lets an agent pay from its owner's account (the principal) with a
-key of its own, within limits: the most per payment (--cap), a budget for
-the mandate's whole life (--budget), an expiry (--expires-in, 30 days by
-default) and, when --payee names any, the addresses it may pay; with none
-named it may pay any address. credential create writes those into a
-credential file, <out>.json, and the agent's keys beside it: its mandate key,
-<out>.agent-key.json, and the key that pays for its pulls, <out>.gas-key.json;
---agent-key names a mandate key the agent already has instead, with its gas
-key beside that. The issuer keys that sign the credential are created on
-first use. account create names the owner's Metal account, a smart account
-the owner's key controls, created on chain by the first bind, and its address
-is --principal. bind, replace and
-revoke are signed by the account's quorum: --key pays gas and is the default
-sole signer; repeated --signer-key supplies EOA quorum signers. The account
-factory is the network's; --factory names another on any of these commands.
-Keep owner keys apart from the agent's keys. pay --mandate
-pays from the principal's account, signed by the agent's key; a payment
-outside the mandate is refused on chain and the refusal names the limit.
-pull makes a payment with no seller, such as moving funds to an allowed
-address; the --key account, the agent's gas key by default, submits it and
-pays its gas, and a refused pull exits 1. verify checks the mandate and every
-payment under it from the chain alone, or one --tx: the binding, the
-credential against it and under its issuer, and each payment as the agent
-key's own signed per-payment mandate, rebuilt from its transaction; with
---signed-offer, the offer the agent signed for that payment, as pay printed
-it, against the payment. A check that fails exits 1. A seller that asks for
-the agent's signed order gets it with the payment; pay prints it. Amounts under a mandate are whole cents. The mandate
-commands read and write the chain, so on testnet they need an endpoint.
-
-The key file defaults to ${DEFAULT_KEY_PATH}, the agent's keys to the files
-beside its credential, and the issuer keys to ${DEFAULT_ISSUER_KEY_PATH}.`;
+import { helpFor } from "./help.js";
+import { DEFAULT_KEY_PATH, agentKeyPath, gasKeyPath, issuerKeyPath, publicKeyPath, readKey } from "./keystore.js";
+import { mcpAuthority, serveMcp } from "./mcp.js";
 const print = (line) => console.log(line);
 async function main(argv) {
     const { values, positionals } = parseArgs({
@@ -115,12 +45,13 @@ async function main(argv) {
             "signed-offer": { type: "string" },
             description: { type: "string" },
             to: { type: "string" },
+            "record-refusal": { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
     const [command, sub] = positionals;
     if (values.help || command === undefined || command === "help") {
-        print(USAGE);
+        print(helpFor(command === "help" ? positionals.slice(1) : positionals.slice(0, 3)));
         return command === undefined && !values.help ? 2 : 0;
     }
     const on = () => target(values.network, {
@@ -167,14 +98,18 @@ async function main(argv) {
             const OWNER_KEY = "--key, the account owner's key file";
             const need = (value, option) => {
                 if (value === undefined)
-                    throw new Error(`mandate ${sub ?? ""} needs ${option}`);
+                    throw new Error(`mandate ${sub === "credential" ? "credential create" : (sub ?? "")} needs ${option}`);
                 return value;
             };
             const accountFactory = () => accountFactoryFor(on().network, values.factory === undefined ? undefined : parseAddress(values.factory, "--factory"), "pass --factory");
             const owner = () => ({ accountFactory: accountFactory(), signerPaths: values["signer-key"] ?? [] });
-            const issuerPaths = values.issuer ?? [publicKeyPath(DEFAULT_ISSUER_KEY_PATH)];
+            // The issuers the owner accepts: theirs, beside their key, unless --issuer names others.
+            const ownerIssuers = () => values.issuer ?? [publicKeyPath(issuerKeyPath(need(values.key, OWNER_KEY)))];
             if (sub === "credential" && positionals[2] === "create") {
-                const payees = (values.payee ?? []).map((payee) => parseAddress(payee, "--payee"));
+                const payees = (values.payee ?? []).map((payee) => parsePayee(payee, "--payee"));
+                // The owner's key must be there: a mistyped path would put new issuer keys beside nothing.
+                if (values["issuer-key"] === undefined && values.key !== undefined)
+                    await readKey(values.key);
                 await credentialCreate(on(), {
                     principal: parseAddress(values.principal, "--principal"),
                     payees,
@@ -185,22 +120,23 @@ async function main(argv) {
                     description: values.description ?? "A mandate issued by metal-agent",
                     out: need(values.out, "--out"),
                     agentKeyPath: values["agent-key"],
-                    issuerKeyPath: values["issuer-key"] ?? DEFAULT_ISSUER_KEY_PATH,
+                    // The keys that sign the owner's credentials are as private as the owner's key: they live beside it.
+                    issuerKeyPath: values["issuer-key"] ?? issuerKeyPath(need(values.key, "--key, the account owner's key file, beside which the keys that sign its credentials live, or --issuer-key")),
                 }, print);
             }
             else if (sub === "bind") {
-                const args = { ...owner(), credentialPath: need(values.credential, "--credential"), issuerPaths, keyPath: need(values.key, OWNER_KEY) };
+                const args = { ...owner(), credentialPath: need(values.credential, "--credential"), issuerPaths: ownerIssuers(), keyPath: need(values.key, OWNER_KEY) };
                 await mandateBind(on(), args, print);
             }
-            else if (sub === "replace") {
+            else if (sub === "replace" || sub === "renew") {
                 const args = {
                     credentialPath: need(values.credential, "--credential"),
                     replacesPath: need(values.replaces, "--replaces"),
-                    issuerPaths,
+                    issuerPaths: ownerIssuers(),
                     ...owner(),
                     keyPath: need(values.key, OWNER_KEY),
                 };
-                await mandateReplace(on(), args, print);
+                await (sub === "replace" ? mandateReplace : mandateRenew)(on(), args, print);
             }
             else if (sub === "revoke") {
                 await mandateRevoke(on(), { ...owner(), credentialPath: need(values.credential, "--credential"), keyPath: need(values.key, OWNER_KEY) }, print);
@@ -217,16 +153,20 @@ async function main(argv) {
                     to: parseAddress(values.to, "--to"),
                     amount: parsePullAmount(values.amount, "--amount"),
                     keyPath: values.key ?? gasKeyPath(agentKey),
+                    recordRefusal: values["record-refusal"] === true,
                 };
                 return (await mandatePull(on(), args, print)) === "paid" ? 0 : 1;
             }
             else if (sub === "verify") {
                 const tx = values.tx === undefined ? undefined : parseTxHash(values.tx, "--tx");
+                const issuerPaths = values.issuer ?? [];
+                if (issuerPaths.length === 0)
+                    throw new Error("mandate verify needs --issuer: the issuer-public-file credential create printed, or another issuer you trust");
                 const args = { accountFactory: accountFactory(), credentialPath: need(values.credential, "--credential"), issuerPaths, tx, signedOffer: values["signed-offer"] };
                 return (await mandateVerify(on(), args, print)) === "verified" ? 0 : 1;
             }
             else {
-                throw new Error(`unknown mandate subcommand "${sub ?? ""}"; try: credential create, bind, replace, revoke, status, pull, verify`);
+                throw new Error(`unknown mandate subcommand "${sub ?? ""}"; try: credential create, bind, replace, renew, revoke, status, pull, verify`);
             }
             return 0;
         }
@@ -234,11 +174,11 @@ async function main(argv) {
             await status(on(), sub, print);
             return 0;
         case "mcp":
-            await serveMcp();
+            await serveMcp(mcpAuthority(values));
             await new Promise(() => { });
             return 0;
         default:
-            throw new Error(`unknown command "${command}"\n\n${USAGE}`);
+            throw new Error(`unknown command "${command}"\n\n${helpFor([])}`);
     }
 }
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {

package/dist/keystore.js

@@ -9,8 +9,6 @@ export function isPrivateKey(value) {
     return typeof value === "string" && isHex(value) && value.length === 66;
 }
 export const DEFAULT_KEY_PATH = join(homedir(), ".metal-agent", "key.json");
-/** The keys that sign a credential `mandate credential create` issues. */
-export const DEFAULT_ISSUER_KEY_PATH = join(homedir(), ".metal-agent", "issuer.json");
 /** `foo.json` to `foo.<suffix>.json`: a file that belongs beside another. */
 function beside(path, suffix) {
     const ext = extname(path);
@@ -18,6 +16,8 @@ function beside(path, suffix) {
 }
 /** The P-256 key an agent signs payments with under the mandate at `credentialPath`: `mandate.json` to `mandate.agent-key.json`. */
 export const agentKeyPath = (credentialPath) => beside(credentialPath, "agent-key");
+/** The keys that sign the owner's credentials, beside the owner's key file and as private as it: `owner-key.json` to `owner-key.issuer.json`. */
+export const issuerKeyPath = (ownerKeyPath) => beside(ownerKeyPath, "issuer");
 /** The funded key that submits the agent's direct pulls and pays their gas, beside its mandate key: `mandate.agent-key.json` to `mandate.gas-key.json`, `shared.json` to `shared.gas-key.json`. */
 export function gasKeyPath(agentKeyPath) {
     const ext = extname(agentKeyPath);

package/dist/mcp.js

@@ -6,8 +6,23 @@ import { target } from "./chain.js";
 import { fund } from "./commands/fund.js";
 import { parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.js";
+import { loadMandate, mandateAgentSigner } from "./commands/mandate.js";
 import { DEFAULT_KEY_PATH, agentKeyPath, readKey } from "./keystore.js";
+import { USDZ, formatUsdz } from "@metalntwx/metal-pay";
 import { redactUrls } from "@metalntwx/metal-pay/mandates";
+/** The authority `metal-agent mcp` serves under, from its options. */
+export function mcpAuthority(options) {
+    if (options.mandate !== undefined) {
+        if (options.key !== undefined || options.max !== undefined) {
+            throw new Error("mcp --mandate takes neither --key nor --max: the mandate sets the limit, and the agent's key is --agent-key");
+        }
+        return { kind: "mandate", credentialPath: options.mandate, agentKeyPath: options["agent-key"] ?? agentKeyPath(options.mandate) };
+    }
+    if (options["agent-key"] !== undefined)
+        throw new Error("--agent-key goes with --mandate");
+    return { kind: "key", keyPath: options.key ?? DEFAULT_KEY_PATH, maxAmount: parseMax(options.max, "--max") };
+}
+const usdz = (units) => `${formatUsdz(units)} ${USDZ.symbol}`;
 const network = z.enum(["devnet", "testnet"]).describe("Which Metal network; there is no default");
 const rpcUrl = z
     .string()
@@ -15,45 +30,46 @@ const rpcUrl = z
     .optional()
     .describe("JSON-RPC endpoint; on devnet the network's default when omitted. On testnet, status needs an endpoint of the user's own, created after signing up in the Metal console");
 const RPC_HOW = "pass rpcUrl or set METAL_RPC_URL in the server's environment";
-export function createMcpServer() {
+export function createMcpServer(authority) {
     const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
     const server = new McpServer({ name: "metal-agent", version });
-    server.registerTool("pay", {
-        description: "Request a URL and pay its x402 challenge in *USDZ on Metal with the agent's key. Returns the settlement transaction hash, the response headers and the body. With mandate, the payment comes from the mandate's account within the limits its owner set, and a payment outside them is refused on chain with the limit named. To buy Metal RPC, POST a JSON-RPC body to the RPC URL; the rpc-aas-endpoint header is the endpoint the payment bought, so send further RPC calls there without paying again.",
-        inputSchema: {
-            url: z.string().url(),
-            network,
-            key: z.string().optional().describe(`Agent key file; ${DEFAULT_KEY_PATH} by default`),
-            max: z
-                .string()
-                .optional()
-                .describe("The most this payment may cost, in decimal *USDZ; 1 by default. A higher offer is refused before signing"),
-            mandate: z
-                .string()
-                .optional()
-                .describe("Credential file of a mandate to pay under. The mandate's limits apply in place of key and max, and only its owner can change them"),
-            agentKey: z
-                .string()
-                .optional()
-                .describe("The agent's mandate key file; the <credential>.agent-key.json beside the credential by default"),
-            method: z.string().optional().describe("HTTP method; GET by default, POST with a body"),
-            body: z.string().optional().describe("Request body, sent as application/json unless headers names a content type"),
-            headers: z.record(z.string(), z.string()).optional().describe("Request headers, by name"),
-        },
-    }, ({ url, network: net, key, max, mandate, agentKey, method, body, headers }) => collect(async (print) => {
-        const request = { method, body, headers };
-        if (mandate !== undefined) {
-            if (max !== undefined || key !== undefined) {
-                throw new Error("with mandate, pass neither max nor key: the mandate sets the limit, and the agent's key is agentKey");
+    const request = {
+        url: z.string().url(),
+        network,
+        method: z.string().optional().describe("HTTP method; GET by default, POST with a body"),
+        body: z.string().optional().describe("Request body, sent as application/json unless headers names a content type"),
+        headers: z.record(z.string(), z.string()).optional().describe("Request headers, by name"),
+    };
+    const BUY_RPC = "To buy Metal RPC, POST a JSON-RPC body to the RPC URL; the rpc-aas-endpoint header is the endpoint the payment bought, so send further RPC calls there without paying again.";
+    if (authority.kind === "mandate") {
+        server.registerTool("pay", {
+            description: `Request a URL and pay its x402 challenge in *USDZ on Metal under this server's mandate: the payment comes from the mandate's account, signed by the agent's key, within the limits its owner set, and a payment outside them is refused with the limit named. Only the owner can change the limits. Returns the settlement transaction hash, the response headers and the body. ${BUY_RPC}`,
+            // Strict: a key or limit the model names is refused, not dropped.
+            inputSchema: z.object(request).strict(),
+        }, ({ url, network: net, method, body, headers }) => collect((print) => payUnderMandate(target(net), authority, url, print, { method, body, headers })));
+    }
+    else {
+        const limit = usdz(authority.maxAmount);
+        server.registerTool("pay", {
+            description: `Request a URL and pay its x402 challenge in *USDZ on Metal with this server's key, refusing before signing any offer above ${limit}. Returns the settlement transaction hash, the response headers and the body. ${BUY_RPC}`,
+            inputSchema: z
+                .object({
+                ...request,
+                max: z
+                    .string()
+                    .optional()
+                    .describe(`A lower limit for this payment, in decimal *USDZ; it can only lower the server's ${limit}`),
+            })
+                .strict(),
+        }, ({ url, network: net, max, method, body, headers }) => collect(async (print) => {
+            const maxAmount = max === undefined ? authority.maxAmount : parseMax(max, "max");
+            if (maxAmount > authority.maxAmount) {
+                throw new Error(`max can only lower this server's limit of ${limit} per payment; its --max sets the limit`);
             }
-            const payer = { credentialPath: mandate, agentKeyPath: agentKey ?? agentKeyPath(mandate) };
-            await payUnderMandate(target(net), payer, url, print, request);
-            return;
-        }
-        const maxAmount = parseMax(max, "max");
-        const account = await readKey(key ?? DEFAULT_KEY_PATH);
-        await pay(target(net), account, url, { maxAmount, raise: "raise max to allow it" }, print, request);
-    }));
+            const raise = `the server's limit is ${limit}, set by its --max`;
+            await pay(target(net), await readKey(authority.keyPath), url, { maxAmount, raise }, print, { method, body, headers });
+        }));
+    }
     server.registerTool("fund", {
         description: "Fund an address with *USDZ. On devnet, from the devnet's pre-funded principal account; on testnet, from the public faucet, which sets the amount itself and reports an address that already holds a full grant as funded.",
         inputSchema: {
@@ -81,6 +97,10 @@ async function collect(run) {
         return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
     }
 }
-export async function serveMcp() {
-    await createMcpServer().connect(new StdioServerTransport());
+/** Serves over stdio. A mandate and its agent key are checked first, so a wrong path fails the host's launch; a key is read when pay needs
+ * it, so fund and status work without one. */
+export async function serveMcp(authority) {
+    if (authority.kind === "mandate")
+        await mandateAgentSigner(await loadMandate(authority.credentialPath), authority.agentKeyPath);
+    await createMcpServer(authority).connect(new StdioServerTransport());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalntwx/metal-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The `metal-agent` CLI and MCP server: create or import an agent key, fund it on Metal devnet or testnet, pay x402 offers in *USDZ, look up a settlement, and set spending limits for an agent that Metal enforces.",
   "license": "MIT",
   "repository": {
@@ -18,8 +18,8 @@
     "skills"
   ],
   "dependencies": {
-    "@metalntwx/metal-ts": "^0.3.0",
-    "@metalntwx/metal-pay": "^0.1.0",
+    "@metalntwx/metal-ts": "^0.3.2",
+    "@metalntwx/metal-pay": "^0.2.0",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@x402/core": "2.21.0",
     "viem": "^2.54.6",

package/skills/metal-agent/SKILL.md

@@ -12,8 +12,8 @@ Every command that touches the chain takes `--network testnet`. Metal's
 demo seller is at `https://x402-demo-testnet.metalntwx.com/quote` and the
 block explorer at `https://testnet.metalntwx.com`.
 
-`key`, `fund` and `pay` need no RPC endpoint. `status` and the `mandate`
-commands need the user's own: ask for it, unless `METAL_RPC_URL` is already
+`key`, `fund` and `pay` need no RPC endpoint. `status`, `account create` and
+the `mandate` commands other than `credential create` need the user's own: ask for it, unless `METAL_RPC_URL` is already
 set, and pass it with `--rpc-url`. A user without one creates it as
 `https://docs.metalntwx.com/network/endpoints` describes.
 
@@ -64,6 +64,10 @@ Run the steps in order. After each step, show the user its output.
    }
    ```
 
+   The server pays with the default key file. If the user's key is in
+   another file, or the agent pays under a mandate, add `--key <file>` or
+   `--mandate <credential>` after `mcp`.
+
    The tools appear after the host reloads. If you cannot reload it, tell
    the user to, and carry on with the CLI.
 
@@ -100,7 +104,7 @@ Run the steps in order. After each step, show the user its output.
 - Before you pass a `--max` above the default of 1 `*USDZ`.
 - Before you import a key, or write a key anywhere but the default file.
 - Before you run `account create`, `mandate credential create`, `bind`,
-  `replace` or `revoke`. They are the account owner's to run.
+  `replace`, `renew` or `revoke`. They are the account owner's to run.
 
 Never print a private key or the contents of a key file. Never move, copy
 or delete a key file. If the owner's key file is within your reach, tell
@@ -183,11 +187,15 @@ A refusal exits 1 with the reason:
   `offer signs for the EIP-712 domain …` means the offer asks for something
   other than `*USDZ`. Tell the user; a larger `--max` does not change it.
 - `error: payment refused: <reason>` means the facilitator refused at
-  verification.
+  verification, or the seller's own check refused.
 - `error: payment refused at settlement: <reason>` means the facilitator
   refused at settlement, with the transaction hash when there is one. On
-  `daily_limit_reached`, retry later. On `settlement_in_doubt`, run
-  `status` on the hash before paying again.
+  `daily_limit_reached`, retry later.
+- On `settlement_in_doubt`, or any error after the `nonce` line that is
+  not a `payment refused` line, such as `fetch failed` or an HTTP status
+  from the seller, the payment may have settled. Do not pay again. Tell
+  the user, with the `nonce` line `pay` printed; when the error names a
+  transaction hash, `status` on it shows whether it landed.
 
 ## `pay --mandate`
 
@@ -205,11 +213,13 @@ metal-agent pay https://example.com/report --mandate ./mandate.json --network te
 apply. A payment outside the mandate exits 1 with
 `error: payment refused: <reason> (…)`, a reason starting `mandate_`. Tell
 the user which limit it was; only the owner can change a mandate. After
-`mandate_revoked`, ask the user for the credential that replaced it.
+`mandate_revoked`, ask the user for the credential that replaced it, and
+pay with that. If the error says there is no agent key, pass the
+`--agent-key` it names.
 
 A seller that asks for your signed order gets it with the payment, and
 `pay` prints it as `signed-offer <text>`. Keep it, and pass it to
-`mandate verify --tx <hash> --signed-offer <text>` to check the two
+`mandate verify --issuer <file> --tx <hash> --signed-offer <text>` to check the two
 together.
 
 `mandate status` shows what is left: read `spent <amount> of <budget>`,
@@ -221,8 +231,11 @@ metal-agent mandate status --credential ./mandate.json --network testnet --rpc-u
 
 `mandate pull` pays an address the mandate allows, with no seller. The gas
 key beside the credential, `mandate.gas-key.json`, submits it and pays the
-gas. `outcome paid` or `outcome refused` with a `reason` line says what
-happened.
+gas, so ask the user to fund its `gas-key-address` first. `outcome paid`, or `outcome refused, not sent` with `reason` and `recorded no` lines,
+says what happened; a pull refused when checked sends nothing and costs no gas. Pass
+`--record-refusal` only when the user asks for the refusal to be recorded
+on chain. If a pull fails after printing `transaction <hash>`, run
+`metal-agent status <hash>` before pulling again; it may have paid.
 
 ```bash
 metal-agent mandate pull --credential ./mandate.json --to <payee address> --amount 2.50 --network testnet --rpc-url <endpoint>
@@ -231,12 +244,17 @@ metal-agent mandate pull --credential ./mandate.json --to <payee address> --amou
 `mandate verify` checks the mandate and every payment under it from the
 chain alone, or one `--tx <hash>`, and exits 1 when a check fails. Run it
 when the user asks whether a payment was within the mandate; read
-`verified yes|no`, and a failed `step` line names what differs.
+`verified yes|no`, and a failed `step` line names what differs. It needs
+the issuer's public key file, the `issuer-public-file` that `credential
+create` printed; ask the user for it.
 
 ```bash
-metal-agent mandate verify --credential ./mandate.json --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --issuer <issuer public key file> --network testnet --rpc-url <endpoint>
 ```
 
+`--issuer` is the issuer's public key file the user gave you with the
+credential; ask for it if you do not have it.
+
 ## status
 
 Show a settlement from chain data: status, block, submitter, gas paid in
@@ -251,13 +269,14 @@ metal-agent status <transaction hash> --network testnet --rpc-url <endpoint>
 ## mcp
 
 Serve `pay`, `fund` and `status` as MCP tools, each taking a `network`, over
-stdio for an MCP host. `pay` takes the same limit as an optional `max`,
-`"1"` by default, the request as optional `method`, `body` and `headers`,
-and a credential file as `mandate` to pay under it, with an optional
-`agentKey`. `status` takes the endpoint as `rpcUrl`, which it requires.
-Keys are created and imported through the CLI; `pay` takes an existing
-key file as `key`.
+stdio for an MCP host. What `pay` spends is fixed when the server starts,
+by its key and `--max`, or by one mandate; `pay` takes the request as
+optional `method`, `body` and `headers`, and under a key a `max` that can
+only lower the server's limit. `status` takes the endpoint as `rpcUrl`, which testnet
+needs unless the server's environment sets `METAL_RPC_URL`. No tool chooses a key, a mandate or a higher limit, and none
+sets or changes a mandate.
 
 ```bash
 metal-agent mcp
+metal-agent mcp --mandate /path/to/mandate.json
 ```