@metalntwx/metal-agent 0.1.1 → 0.3.0

package/dist/commands/pay.js

@@ -59,7 +59,7 @@ export async function pay(target, account, url, limit, print, request = {}) {
  */
 export async function payUnderMandate(target, payer, url, print, request = {}) {
     const mandate = await loadMandate(payer.credentialPath);
-    const signDigest = await mandateAgentSigner(mandate, payer.agentKeyPath);
+    const signDigest = await mandateAgentSigner(mandate, payer.credentialPath, payer.mandateKeyFile);
     const paying = createMandatePaymentClient({ credential: mandate.credential, signDigest, network: target.network });
     print(`mandate ${paying.reference}`);
     await paidRequest(target, { ...paying, payer: paying.principal }, url, print, request);
@@ -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,119 @@
+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} [--mandate-key-file <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 .key.json file in the credential's directory whose key the credential names, unless --mandate-key-file 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> [--mandate-key-file <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> | --key <owner key file> ${NETWORK}`,
+        about: "Creates the owner's Metal account, a smart account the owner's key controls, and prints its address, the --principal of the owner's credentials. The owner's key pays the gas; one that holds none is funded first, from the faucet on testnet. An account that exists is named, and nothing is sent. 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>] [--starts-in <seconds>] [--max-occurrences <n>]\n                  [--description <text>] [--mandate-key-file <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), a start (--starts-in, at once 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 mandate key the agent signs with is written beside the credential, mandate.key.json for --out mandate.json, unless --mandate-key-file names one that exists, as for a replacement. 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 owners sign: --key pays the gas and is the sole signer unless repeated --signer-key names the owners' 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>] [--mandate-key-file <file>] [--record-refusal]`,
+        about: "Pays an address the mandate allows, with no seller. The facilitator submits it and pays its gas, unless --key names a funded key to submit it. A payout the mandate would refuse is reported and not sent, and the command exits 1; with --key, --record-refusal sends it so the refusal is recorded on chain. The outcome is read from the chain: paid, refused, held in the payee's escrow, or pending. A pending pull is kept beside the credential, and running the same command again sends that same pull, which pays at most once.",
+    },
+    {
+        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 mandate 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, and mandate pull
+--facilitator-url, which override METAL_RPC_URL, METAL_FAUCET_URL and
+METAL_FACILITATOR_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 mandate bind,
+replace, renew, revoke, status and verify 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, 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({
@@ -90,6 +20,7 @@ async function main(argv) {
             network: { type: "string" },
             "rpc-url": { type: "string" },
             "faucet-url": { type: "string" },
+            "facilitator-url": { type: "string" },
             key: { type: "string" },
             factory: { type: "string" },
             "signer-key": { type: "string", multiple: true },
@@ -103,29 +34,36 @@ async function main(argv) {
             credential: { type: "string" },
             replaces: { type: "string" },
             issuer: { type: "string", multiple: true },
-            "agent-key": { type: "string" },
+            "mandate-key-file": { type: "string" },
             "issuer-key": { type: "string" },
             principal: { type: "string" },
             payee: { type: "string", multiple: true },
             cap: { type: "string" },
             budget: { type: "string" },
             "expires-in": { type: "string" },
+            "starts-in": { type: "string" },
             "max-occurrences": { type: "string" },
             tx: { type: "string" },
             "signed-offer": { type: "string" },
             description: { type: "string" },
             to: { type: "string" },
+            "record-refusal": { type: "boolean" },
             help: { type: "boolean", short: "h" },
         },
     });
     const [command, sub] = positionals;
+    const extra = positionals.slice(argumentCount(command, sub));
+    if (extra.length > 0) {
+        throw new Error(`unexpected argument${extra.length > 1 ? "s" : ""} ${extra.map((a) => JSON.stringify(a)).join(" ")}; quote a value that holds a space`);
+    }
     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, {
         rpcUrl: values["rpc-url"],
         faucetUrl: values["faucet-url"],
+        facilitatorUrl: values["facilitator-url"],
     });
     switch (command) {
         case "key":
@@ -143,12 +81,14 @@ async function main(argv) {
             const request = { method: values.method, body: values.body, headers: parseHeaders(values.header, "--header") };
             if (values.mandate !== undefined) {
                 if (values.max !== undefined || values.key !== undefined) {
-                    throw new Error("pay --mandate takes neither --max nor --key: the mandate sets the limit, and the agent's key is --agent-key");
+                    throw new Error("pay --mandate takes neither --max nor --key: the mandate sets the limit, and the agent signs with its mandate key");
                 }
-                const payer = { credentialPath: values.mandate, agentKeyPath: values["agent-key"] ?? agentKeyPath(values.mandate) };
+                const payer = { credentialPath: values.mandate, mandateKeyFile: values["mandate-key-file"] };
                 await payUnderMandate(on(), payer, sub, print, request);
                 return 0;
             }
+            if (values["mandate-key-file"] !== undefined)
+                throw new Error("--mandate-key-file goes with --mandate");
             const limit = { maxAmount: parseMax(values.max, "--max"), raise: "pass --max to allow it" };
             await pay(on(), await readKey(values.key ?? DEFAULT_KEY_PATH), sub, limit, print, request);
             return 0;
@@ -157,7 +97,7 @@ async function main(argv) {
             if (sub !== "create")
                 throw new Error(`unknown account subcommand "${sub ?? ""}"; try: account create`);
             if ((values.key === undefined) === (values.out === undefined))
-                throw new Error("account create needs --out, the owner key file to create, or --key, one that exists");
+                throw new Error("account create needs --out, the owner key file, created when it does not exist, or --key, one that exists");
             const factory = accountFactoryFor(on().network, values.factory === undefined ? undefined : parseAddress(values.factory, "--factory"), "pass --factory");
             await accountCreate(on(), { accountFactory: factory, ...(values.key === undefined ? { out: values.out } : { keyPath: values.key }) }, print);
             return 0;
@@ -167,40 +107,46 @@ 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,
                     cap: parseCents(values.cap, "--cap"),
                     budget: parseCents(values.budget, "--budget"),
                     expiresIn: parseCount(values["expires-in"], "--expires-in") ?? 30 * 86_400,
+                    startsIn: parseCount(values["starts-in"], "--starts-in"),
                     maxOccurrences: parseCount(values["max-occurrences"], "--max-occurrences"),
                     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,
+                    mandateKeyFile: values["mandate-key-file"],
+                    // 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);
@@ -209,24 +155,26 @@ async function main(argv) {
                 await mandateStatus(on(), need(values.credential, "--credential"), accountFactory(), print);
             }
             else if (sub === "pull") {
-                const credentialPath = need(values.credential, "--credential");
-                const agentKey = values["agent-key"] ?? agentKeyPath(credentialPath);
                 const args = {
-                    credentialPath,
-                    agentKeyPath: agentKey,
+                    credentialPath: need(values.credential, "--credential"),
+                    mandateKeyFile: values["mandate-key-file"],
                     to: parseAddress(values.to, "--to"),
                     amount: parsePullAmount(values.amount, "--amount"),
-                    keyPath: values.key ?? gasKeyPath(agentKey),
+                    keyPath: values.key,
+                    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,13 +182,21 @@ 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([])}`);
     }
 }
+/** How many words a command takes before its options: `key import <file|hex>` and `mandate credential create` three, `mcp` one, the other commands two; any number for `help` and for a command the dispatch then names unknown. */
+function argumentCount(command, sub) {
+    if ((command === "key" && sub === "import") || (command === "mandate" && sub === "credential"))
+        return 3;
+    if (command === "mcp")
+        return 1;
+    return ["key", "fund", "pay", "account", "mandate", "status"].includes(command ?? "") ? 2 : Infinity;
+}
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
     // An endpoint's URL can carry its credential, and this output often lands in an agent's transcript.
     console.error(`error: ${redactUrls(error instanceof Error ? error.message : String(error))}`);

package/dist/keystore.js

@@ -9,21 +9,17 @@ 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);
     return `${path.slice(0, path.length - ext.length)}.${suffix}${ext}`;
 }
-/** 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 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);
-    const stem = agentKeyPath.slice(0, agentKeyPath.length - ext.length);
-    return `${stem.endsWith(".agent-key") ? stem.slice(0, -".agent-key".length) : stem}.gas-key${ext}`;
-}
+/** The mandate key `credential create` writes beside the credential at `credentialPath`: `mandate.json` to `mandate.key.json`. */
+export const mandateKeyPath = (credentialPath) => beside(credentialPath, "key");
+/** The directory of pulls `mandate pull` sent without an outcome yet, beside the credential at `credentialPath`: `mandate.json` to `mandate.pulls`. */
+export const pendingPullsPath = (credentialPath) => `${credentialPath.slice(0, credentialPath.length - extname(credentialPath).length)}.pulls`;
+/** 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 secp256k1 key at `path`, generated and written there first when the file does not exist. */
 export async function readOrCreateKey(path) {
     if (await exists(path))

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 { DEFAULT_KEY_PATH, agentKeyPath, readKey } from "./keystore.js";
+import { loadMandate, mandateAgentSigner } from "./commands/mandate.js";
+import { DEFAULT_KEY_PATH, 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 signs with its mandate key");
+        }
+        return { kind: "mandate", credentialPath: options.mandate, ...(options["mandate-key-file"] !== undefined && { mandateKeyFile: options["mandate-key-file"] }) };
+    }
+    if (options["mandate-key-file"] !== undefined)
+        throw new Error("--mandate-key-file 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 mandate 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 mandate 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.credentialPath, authority.mandateKeyFile);
+    await createMcpServer(authority).connect(new StdioServerTransport());
 }