@metalntwx/metal-agent 0.2.0 → 0.3.1

package/dist/commands/pay.js

@@ -1,5 +1,5 @@
 import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from "@x402/core/http";
-import { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, formatUsdz, USDZ, usdzBaseUnits, } from "@metalntwx/metal-pay";
+import { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, formatUsdz, metalNetwork, USDZ, usdzBaseUnits, } from "@metalntwx/metal-pay";
 import { createMandatePaymentClient, describeRefusal, refusalOf, signedOfferOf } from "@metalntwx/metal-pay/mandates";
 import { loadMandate, mandateAgentSigner } from "./mandate.js";
 /** A decimal `*USDZ` limit per payment, `DEFAULT_MAX_PAYMENT` when absent. */
@@ -59,11 +59,76 @@ 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);
 }
+/** A payment refused with nothing paid, before settlement or at it; `reason` is the facilitator's or the seller's, when it gave one. */
+export class PaymentRefused extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** A payment that was signed and may have settled: paying again can pay twice. */
+export class PaymentInDoubt extends Error {
+}
+/**
+ * The facilitator's settlement reasons that mean nothing moved
+ * (apps/x402-facilitator/src/facilitator.ts `check`, `settle`, `failed` and
+ * routes.ts): the payment was never sent, was refused or reverted. Any other
+ * answer, such as a seller's own `fetch failed` when the facilitator's answer
+ * to it was lost, or `already_settled`, `nonce_already_used` or
+ * `payment_quarantined`, which name a transaction that moved it, leaves open
+ * whether it settled.
+ */
+const NOTHING_SETTLED = new Set([
+    "unsupported_x402_version",
+    "unsupported_network",
+    "unsupported_scheme",
+    "unsupported_asset",
+    "settlement_unavailable",
+    "invalid_payload",
+    "bad_signature",
+    "rpc_unreachable",
+    "authorization_window",
+    "rate_limited",
+    "daily_limit_reached",
+    "recipient_refuses",
+    "payment_failed",
+    "payment_reverted",
+]);
+function nothingSettled(reason) {
+    if (reason === undefined)
+        return false;
+    const mandate = refusalOf(reason);
+    // A used digest is a payment that was made, or refused, already.
+    if (mandate !== undefined)
+        return mandate !== "NonceUsed";
+    return NOTHING_SETTLED.has(reason) || reason.startsWith("payment_mismatch:");
+}
+/** The networks an offer named when none is the one paid on, read from @x402/core's error for an offer with no option it can sign. */
+function offeredElsewhere(message, target) {
+    const marker = "Failed to create payment payload: No network/scheme registered";
+    if (!message.startsWith(marker) || !message.includes("{"))
+        return undefined;
+    try {
+        const { paymentRequirements } = JSON.parse(message.slice(message.indexOf("{")));
+        const networks = [...new Set((paymentRequirements ?? []).map(({ network }) => network).filter((network) => typeof network === "string"))];
+        if (networks.length === 0 || networks.includes(target.network.network))
+            return undefined;
+        const named = networks.map((network) => {
+            const metal = metalNetwork(network);
+            return metal === undefined ? network : `${metal.name} (${network})`;
+        });
+        return `the offer is on ${named.join(", ")}, not ${target.network.name} (${target.network.network})`;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A refusal's reason as `pay` prints it: a mandate's with what it means, any other as the facilitator named it. */
 function describeRefusalReason(reason) {
     if (reason === undefined)
@@ -102,10 +167,10 @@ 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 message = error instanceof Error ? error.message : String(error);
+        if (signed !== undefined)
+            throw new PaymentInDoubt(`${message}; a payment was signed and may have settled; look it up by its nonce before paying again`);
+        throw new Error(`${offeredElsewhere(message, target) ?? message}; nothing was signed`);
     });
     const body = await response.text();
     const paymentRequired = response.headers.get("payment-required");
@@ -114,16 +179,24 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
         const required = decodePaymentRequiredHeader(paymentRequired);
         const offer = required.accepts[0];
         const priced = offer ? `${formatUsdz(offer.amount)} ${USDZ.symbol} on ${offer.network}` : "no offer";
-        throw new Error(`payment refused: ${describeRefusalReason(required.error)} (offer: ${priced})`);
+        // Refused before settlement: the seller settles only a payment its check passed.
+        throw new PaymentRefused(`payment refused: ${describeRefusalReason(required.error)} (offer: ${priced}); nothing was paid`, required.error);
     }
     const settlement = paymentResponse ? decodePaymentResponseHeader(paymentResponse) : undefined;
-    if (settlement !== undefined && !settlement.success)
-        throw new Error(`payment refused at settlement: ${settleRefusal(settlement)}`);
+    if (settlement !== undefined && !settlement.success) {
+        // A settlement that is not known to have moved nothing can land all the same, so paying again can pay twice.
+        if (!nothingSettled(settlement.errorReason))
+            throw new PaymentInDoubt(`payment in doubt at settlement: ${settleRefusal(settlement)}; it may have settled: do not pay again; look it up by its nonce`);
+        throw new PaymentRefused(`payment refused at settlement: ${settleRefusal(settlement)}; nothing was paid`, settlement.errorReason);
+    }
     // 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}`);
+    // A settled payment is reported paid, whatever status the seller answers with.
+    if (response.status >= 400 && settlement?.success !== true) {
+        // A seller that fails after the payment was signed, or answers that another request holds it, may have settled it first.
+        const answered = `${url} answered ${response.status}: ${body}`;
+        if (signed !== undefined && (response.status >= 500 || response.status === 409))
+            throw new PaymentInDoubt(`${answered}; a payment was signed and may have settled; look it up by its nonce before paying again`);
+        throw new Error(answered);
     }
     print(`status ${response.status}`);
     if (settlement !== undefined) {

package/dist/help.js

@@ -1,10 +1,9 @@
-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.`,
+        about: `Generates the agent's key and writes it to a key file only its owner can read, ~/.metal-agent/key.json unless --out names another. It never overwrites a key file.`,
     },
     {
         name: "key import",
@@ -18,8 +17,8 @@ const COMMANDS = [
     },
     {
         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.",
+        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",
@@ -28,23 +27,23 @@ const COMMANDS = [
     },
     {
         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.",
+        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; under a mandate, mandate_pull, mandate_status and mandate_verify too, which read the chain through the server's METAL_RPC_URL, or devnet's default endpoint. What pay and mandate_pull spend is set here, by whoever starts the server: a key file and --max, or one mandate's credential file, which each call reads. 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.",
+        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 too little is funded first, from the faucet on testnet. When a later step fails, such as a faucet refusal, the error names the key file, and the same command continues from it. 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>] [--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.",
+        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, by default 00:00 UTC on the day of issue) 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 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.",
+        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",
@@ -68,24 +67,26 @@ const COMMANDS = [
     },
     {
         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.",
+        usage: `metal-agent mandate pull --credential <file> --to <address> --amount <usdz> ${NETWORK}\n                  [--payment-id <id>] [--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 (exit 0), refused (exit 1), held in the payee's escrow (exit 4), or pending (exit 3); an error also exits 1. Each pull is kept under ~/.metal-agent/pulls, and running the same command again sends a pending pull again, which pays at most once. --payment-id names the payment, such as a refund's id: two payouts of one amount to one payee are two payments under two ids, an id whose payout was paid or held reports it again, and one the account refused may be sent with other values. Without it, a payout is known by its payee and amount. Either is known only under this home directory and this credential: a retry from another machine, or under a credential that renewed or replaced it, signs a new payout.",
     },
     {
         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.",
+        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, as does an event under the mandate the SDK does not decode.",
     },
 ];
-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.
+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 the mandate
-commands take --factory <address> when the network's MetalAccountFactory is
+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.`;
+metal-agent <command> --help explains one command.
+metal-agent --version prints the version.`;
 /** 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.

package/dist/index.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { accountFactoryFor } from "@metalntwx/metal-pay";
 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, mandateRenew, mandateReplace, mandateRevoke, mandateStatus, mandateVerify, parseAddress, parseCents, parseCount, parsePayee, parseTxHash, parsePullAmount, } from "./commands/mandate.js";
+import { credentialCreate, accountCreate, mandateBind, mandatePull, mandateRenew, mandateReplace, mandateRevoke, mandateStatus, mandateVerify, parseAddress, parseCents, parseCount, parsePayee, parseTxHash, parsePaymentId, parsePullAmount, } from "./commands/mandate.js";
 import { parseHeaders, parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.js";
 import { helpFor } from "./help.js";
-import { DEFAULT_KEY_PATH, agentKeyPath, gasKeyPath, issuerKeyPath, publicKeyPath, readKey } from "./keystore.js";
+import { defaultKeyPath, issuerKeyPath, publicKeyPath, readKey } from "./keystore.js";
 import { mcpAuthority, serveMcp } from "./mcp.js";
 const print = (line) => console.log(line);
+/** `mandate pull`'s exit code per outcome: a wrapper that retries on `pending` alone sends the same pull, and never pays a `held` one into escrow again. */
+const PULL_EXIT = { paid: 0, refused: 1, pending: 3, held: 4 };
 async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -20,6 +23,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 },
@@ -33,23 +37,34 @@ 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" },
+            "payment-id": { type: "string" },
             "record-refusal": { type: "boolean" },
             help: { type: "boolean", short: "h" },
+            version: { type: "boolean" },
         },
     });
+    if (values.version) {
+        print(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+        return 0;
+    }
     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(helpFor(command === "help" ? positionals.slice(1) : positionals.slice(0, 3)));
         return command === undefined && !values.help ? 2 : 0;
@@ -57,6 +72,7 @@ async function main(argv) {
     const on = () => target(values.network, {
         rpcUrl: values["rpc-url"],
         faucetUrl: values["faucet-url"],
+        facilitatorUrl: values["facilitator-url"],
     });
     switch (command) {
         case "key":
@@ -74,21 +90,23 @@ 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);
+            await pay(on(), await readKey(values.key ?? defaultKeyPath()), sub, limit, print, request);
             return 0;
         }
         case "account": {
             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;
@@ -116,10 +134,11 @@ async function main(argv) {
                     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"],
+                    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);
@@ -145,17 +164,16 @@ 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),
+                    paymentId: parsePaymentId(values["payment-id"], "--payment-id"),
+                    keyPath: values.key,
                     recordRefusal: values["record-refusal"] === true,
                 };
-                return (await mandatePull(on(), args, print)) === "paid" ? 0 : 1;
+                return PULL_EXIT[await mandatePull(on(), args, print)];
             }
             else if (sub === "verify") {
                 const tx = values.tx === undefined ? undefined : parseTxHash(values.tx, "--tx");
@@ -181,6 +199,14 @@ async function main(argv) {
             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

@@ -1,29 +1,33 @@
-import { createECDH } from "node:crypto";
-import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createECDH, randomUUID } from "node:crypto";
+import { access, chmod, link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, extname, join } from "node:path";
+import { dirname, extname, isAbsolute, join } from "node:path";
 import { createEs256Key, jwkThumbprint, parseP256Jwk } from "@metalntwx/metal-pay/mandates";
 import { isHex } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 export function isPrivateKey(value) {
     return typeof value === "string" && isHex(value) && value.length === 66;
 }
-export const DEFAULT_KEY_PATH = join(homedir(), ".metal-agent", "key.json");
+/** `~/.metal-agent`, where metal-agent keeps its own files. An empty HOME names no directory, and they would land under whichever one the command runs in. */
+function agentHome() {
+    const home = homedir();
+    if (!isAbsolute(home))
+        throw new Error(`HOME is ${home === "" ? "empty" : `${JSON.stringify(home)}, not an absolute path`}; set it to your home directory, where metal-agent keeps its key and its pulls`);
+    return join(home, ".metal-agent");
+}
+/** The agent's key file when no option names one: `~/.metal-agent/key.json`. */
+export const defaultKeyPath = () => join(agentHome(), "key.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 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 the pulls `mandate pull` sends under the mandate `reference`, one directory per payment: `~/.metal-agent/pulls/<reference>`. */
+export const pendingPullsPath = (reference) => join(agentHome(), "pulls", reference);
 /** 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);
-    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 secp256k1 key at `path`, generated and written there first when the file does not exist. */
 export async function readOrCreateKey(path) {
     if (await exists(path))
@@ -33,14 +37,22 @@ export async function readOrCreateKey(path) {
     await writeKey(path, { address, privateKey });
     return { address, created: true };
 }
+/** Writes a key file that does not exist: whole, beside it, then linked into place, so a failed write leaves no part-written key for a later run to read. */
 export async function writeKey(path, key) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    await writeFile(path, `${JSON.stringify(key, null, 2)}\n`, { mode: 0o600, flag: "wx" }).catch((error) => {
-        if (error.code === "EEXIST")
-            throw new Error(`${path} already holds a key; pass --out <file> to write another`);
-        throw error;
-    });
-    await chmod(path, 0o600);
+    const draft = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(draft, `${JSON.stringify(key, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        await chmod(draft, 0o600);
+        await link(draft, path).catch((error) => {
+            if (error.code === "EEXIST")
+                throw new Error(`${path} already holds a key; pass --out <file> to write another`);
+            throw error;
+        });
+    }
+    finally {
+        await rm(draft, { force: true });
+    }
 }
 export async function readKey(path) {
     const parsed = JSON.parse(await readFile(path, "utf8"));