@metalntwx/metal-agent 0.3.0 → 0.3.2

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",
@@ -29,17 +28,17 @@ const COMMANDS = [
     {
         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.",
+        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> | --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.",
+        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>] [--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.",
+        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",
@@ -68,13 +67,13 @@ const COMMANDS = [
     },
     {
         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.",
+        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 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.",
+        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, and mandate pull
@@ -86,7 +85,8 @@ 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, 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,
@@ -47,10 +50,16 @@ async function main(argv) {
             "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) {
@@ -90,7 +99,7 @@ async function main(argv) {
             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": {
@@ -160,10 +169,11 @@ async function main(argv) {
                     mandateKeyFile: values["mandate-key-file"],
                     to: parseAddress(values.to, "--to"),
                     amount: parsePullAmount(values.amount, "--amount"),
+                    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");

package/dist/keystore.js

@@ -1,14 +1,22 @@
-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);
@@ -16,8 +24,8 @@ function beside(path, suffix) {
 }
 /** 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 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 secp256k1 key at `path`, generated and written there first when the file does not exist. */
@@ -29,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"));

package/dist/mcp.js

@@ -1,15 +1,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { BaseError, RpcRequestError, erc20Abi, getAddress, isAddress } from "viem";
 import { z } from "zod";
-import { target } from "./chain.js";
+import { rpcClient, target } from "./chain.js";
 import { fund } from "./commands/fund.js";
-import { parseMax, pay, payUnderMandate } from "./commands/pay.js";
+import { PaymentInDoubt, PaymentRefused, parseMax, pay, payUnderMandate } from "./commands/pay.js";
 import { status } from "./commands/status.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";
+import { loadMandate, mandateAgentSigner, mandatePull, mandateStatus, mandateVerify, parseAddress, parsePaymentId, parsePullAmount, parseTxHash, } from "./commands/mandate.js";
+import { defaultKeyPath, pendingPullsPath, readKey, readTrustedIssuer } from "./keystore.js";
+import { USDZ, accountFactoryFor, formatUsdz, metalNetwork, rpcUrlFor, usdzBaseUnits } from "@metalntwx/metal-pay";
+import { describeRefusal, redactUrls, refusalOf } from "@metalntwx/metal-pay/mandates";
 /** The authority `metal-agent mcp` serves under, from its options. */
 export function mcpAuthority(options) {
     if (options.mandate !== undefined) {
@@ -20,16 +22,110 @@ export function mcpAuthority(options) {
     }
     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") };
+    return { kind: "key", keyPath: options.key ?? defaultKeyPath(), 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()
-    .url()
-    .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 rpcUrl = (onTestnet) => z.string().url().optional().describe(`JSON-RPC endpoint; on devnet the network's default when omitted. ${onTestnet}`);
 const RPC_HOW = "pass rpcUrl or set METAL_RPC_URL in the server's environment";
+/** A running server's environment is the user's to change, and takes effect when it restarts. */
+const SERVER_RPC_HOW = "tell the user to set METAL_RPC_URL in this server's environment and restart the server";
+/**
+ * Checks that the server's endpoint for `on` serves `on`'s network: a balance,
+ * a pull's outcome or a verification read on another chain is not this one's.
+ */
+async function assertServerChain(on) {
+    const id = await rpcClient(on, SERVER_RPC_HOW).getChainId();
+    if (id === on.network.chainId)
+        return;
+    const other = ["devnet", "testnet"].find((name) => metalNetwork(name)?.chainId === id);
+    throw new Error(`the server's endpoint is on chain ${id}, not ${on.network.name}'s ${on.network.chainId}: ${other === undefined ? "" : `pass network ${other}, or `}tell the user to set METAL_RPC_URL to a ${on.network.name} endpoint and restart the server`);
+}
+/**
+ * The network a mandate tool reads, through the server's own endpoint and
+ * facilitator, checked to serve that network: a pull's outcome and a
+ * verification are only as true as the chain they are read from, so the
+ * model names no endpoint, as it names no mandate.
+ */
+async function mandateTarget(net) {
+    const on = target(net);
+    const resolved = { ...on, rpcUrl: rpcUrlFor(on.network, on.rpcUrl, SERVER_RPC_HOW) };
+    await assertServerChain(resolved);
+    return resolved;
+}
+/** A mandate's limit or state refused a payment: limits and dates are mandate_status's to show, and the user's to change. */
+const MANDATE_REFUSED_NEXT = "next: nothing was paid; mandate_status shows the mandate's limits and state: a start date or a window clears with time, and a limit, or a revoked or unbound mandate, needs the user";
+/** The server keeps the credential it started with, so only the user moves it to the one that replaced or renewed it. */
+const REVOKED_NEXT = "next: nothing more is paid under it; tell the user, who restarts this server with --mandate naming the credential that replaced or renewed it";
+/** What a model does after pay is refused, which paid nothing: a mandate's refusal as its limits and state say, any other the user's to judge. */
+function payRefusedNext(reason, underMandate) {
+    const refusal = underMandate && reason !== undefined ? refusalOf(reason) : undefined;
+    if (refusal === "Revoked")
+        return REVOKED_NEXT;
+    if (refusal !== undefined)
+        return MANDATE_REFUSED_NEXT;
+    return "next: nothing was paid; tell the user the reason before paying this URL again";
+}
+/** What a model does after a payment that may have settled, found by the nonce the call printed: under a mandate mandate_verify lists it, under a key only the user can look it up. */
+function payInDoubtNext(nonce, underMandate) {
+    return underMandate
+        ? `next: call mandate_verify and look for nonce ${nonce}: if it is listed the payment settled, so do not pay again`
+        : `next: do not pay this URL again before the user has checked whether nonce ${nonce} settled`;
+}
+/** Runs pay, ending a refusal, or a payment that may have settled, with what the model does next. */
+async function payOrNext(print, underMandate, run) {
+    let nonce;
+    try {
+        await run((line) => {
+            if (line.startsWith("nonce "))
+                nonce = line.slice("nonce ".length);
+            print(line);
+        });
+    }
+    catch (error) {
+        if (error instanceof PaymentRefused) {
+            print(`error: ${redactUrls(error.message)}`);
+            print(payRefusedNext(error.reason, underMandate));
+            return "failed";
+        }
+        if (!(error instanceof PaymentInDoubt) || nonce === undefined)
+            throw error;
+        print(`error: ${redactUrls(error.message)}`);
+        print(payInDoubtNext(nonce, underMandate));
+        return "failed";
+    }
+}
+/** What a model does after a pull's outcome, in the tool's own terms, from the call's own arguments; a paid pull needs nothing more. */
+function pullNext(outcome, call) {
+    switch (outcome) {
+        case "pending":
+            return `next: call mandate_pull again with to ${call.to}, amount ${call.amount} and paymentId ${JSON.stringify(call.paymentId)}: it sends the same payout, which pays at most once, or reports how it ended; do not change the paymentId or the amount to retry it`;
+        case "held":
+            return "next: the payee's receive policy holds this payment in escrow, so the payee was not paid; it counts against the budget, so do not send it again; the payee, or the authority its policy names, releases it";
+        case "refused":
+            return MANDATE_REFUSED_NEXT;
+        case "paid":
+            return undefined;
+    }
+}
+/** The balance the testnet faucet tops an address up to: 100 *USDZ, as grant_target in apps/testnet-faucet/src/lib.rs sets it. */
+const FAUCET_GRANT = BigInt(usdzBaseUnits("100"));
+/** The most an issuer's public key file is read at: a few hundred bytes of JSON. */
+const ISSUER_FILE_MAX = 64 * 1024;
+const ASK_ISSUERS = "ask the user for the issuer public key files they trust";
+/** The model names these files, so one that is not an issuer's is named without what it holds, and a device or a large file is not read. */
+async function readIssuerFile(path) {
+    const file = await stat(path).catch((error) => {
+        throw error.code === "ENOENT" ? new Error(`no file at ${path}; ${ASK_ISSUERS}`) : error;
+    });
+    if (!file.isFile())
+        throw new Error(`${path} is not a regular file, so not an issuer's public key file; ${ASK_ISSUERS}`);
+    if (file.size > ISSUER_FILE_MAX)
+        throw new Error(`${path} is over 64 KiB, so not an issuer's public key file; ${ASK_ISSUERS}`);
+    await readTrustedIssuer(path).catch((error) => {
+        throw error instanceof SyntaxError ? new Error(`${path} is not JSON, so not an issuer's public key file; ${ASK_ISSUERS}`) : error;
+    });
+}
 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 });
@@ -41,17 +137,21 @@ export function createMcpServer(authority) {
         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.";
+    const AGAIN = "Each call signs a new payment, so calling pay again pays again; a call that times out or returns no answer may still have paid:";
     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}`,
+            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. ${AGAIN} check before calling again, as mandate_verify lists this mandate's payments with their nonces.`,
             // 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 })));
+        }, ({ url, network: net, method, body, headers }) => collect(async (print) => {
+            await assertMandateKey(authority);
+            return payOrNext(print, true, (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}`,
+            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. ${AGAIN} tell the user before calling again. ${BUY_RPC}`,
             inputSchema: z
                 .object({
                 ...request,
@@ -67,40 +167,182 @@ export function createMcpServer(authority) {
                 throw new Error(`max can only lower this server's limit of ${limit} per payment; its --max sets the limit`);
             }
             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 });
+            const key = await readKey(authority.keyPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+                // The default key file the model can create; one the user named with --key is theirs to restore, as a new key there would hold nothing.
+                if (!isDefaultKey(authority.keyPath)) {
+                    throw new Error(`no key at ${authority.keyPath}, the key file this server's --key names: tell the user to restore it, or to restart the server with --key naming another`);
+                }
+                throw new Error(`no key at ${authority.keyPath}, the key this server pays with: create it with \`metal-agent key create --out ${authority.keyPath}\`, or restart the server with --key naming a key file`);
+            });
+            return payOrNext(print, false, (print) => pay(target(net), key, 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.",
+        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. " +
+            "On testnet with the server's METAL_RPC_URL, an address that already holds about a full grant is reported funded and the faucet is not asked.",
         inputSchema: {
             address: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
             network,
             amount: z.string().optional().describe("Decimal *USDZ, devnet only; 10 by default"),
-            rpcUrl,
+            rpcUrl: rpcUrl("On testnet unused: the faucet funds the address"),
         },
-    }, ({ address, network: net, amount, rpcUrl: rpc }) => collect((print) => fund(target(net, { rpcUrl: rpc }), address, amount, print)));
+    }, ({ address, network: net, amount, rpcUrl: rpc }) => collect(async (print) => {
+        const on = target(net, { rpcUrl: rpc });
+        if (on.network.name === "testnet") {
+            if (amount !== undefined)
+                throw new Error("on testnet the faucet sets the amount; leave out amount");
+            // The faucet tops an address up to a full grant, so one that holds about that much would spend a grant on the difference.
+            // Only the server's endpoint is read; a balance it cannot read, or on another chain, leaves the faucet to decide.
+            const server = target(net);
+            if (server.rpcUrl !== undefined && isAddress(address)) {
+                const balance = await assertServerChain(server)
+                    .then(() => rpcClient(server).readContract({ address: server.nusd, abi: erc20Abi, functionName: "balanceOf", args: [address] }))
+                    .catch(() => undefined);
+                if (balance !== undefined && balance * 100n >= FAUCET_GRANT * 99n) {
+                    print(`${getAddress(address)} is funded: it holds ${usdz(balance)}, about a full faucet grant, so the faucet was not asked`);
+                    return;
+                }
+            }
+        }
+        // `key import` writes the CLI's key file, which this server may not pay with.
+        await fund(on, address, amount, print, fetch, false);
+    }));
     server.registerTool("status", {
         description: "Show a settled transfer from chain data: receipt status, block, submitter, gas, and the MIP20 transfer it carried.",
-        inputSchema: { txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/), network, rpcUrl },
+        inputSchema: {
+            txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
+            network,
+            rpcUrl: rpcUrl("On testnet, status needs an endpoint of the user's own, created after signing up in the Metal console; left out, the server's METAL_RPC_URL is used when it is set"),
+        },
     }, ({ txHash, network: net, rpcUrl: rpc }) => collect((print) => status(target(net, { rpcUrl: rpc }), txHash, print, RPC_HOW)));
+    if (authority.kind === "mandate") {
+        const { credentialPath, mandateKeyFile } = authority;
+        server.registerTool("mandate_pull", {
+            description: "Pay an address from this server's mandate's account with no seller, such as a refund or a payout: signed by the mandate key, within the limits its owner set, and submitted by the facilitator, which pays the gas. " +
+                "One payment, one paymentId, such as the refund's or the invoice's id: never call with another paymentId for a payment an earlier call sent, and an error after a pending answer does not mean nothing was sent. " +
+                "A paymentId recorded as paid or held in a transaction the chain does not hold, as after a chain reset, fails and sends nothing: ask the user before paying it again under another paymentId. " +
+                "Returns `outcome paid`, `refused`, `pending` or `held`, with the transaction when there is one, and on any outcome but paid a `next:` line saying what to do.",
+            inputSchema: z
+                .object({
+                to: z.string().regex(/^0x[0-9a-fA-F]{40}$/).describe("The address to pay"),
+                amount: z.string().describe("Decimal *USDZ to the cent, such as 2.50"),
+                paymentId: z.string().min(1).describe("Your id for this payment, such as the refund's or the invoice's; a retry passes the same one"),
+                network,
+            })
+                .strict(),
+        }, ({ to, amount, paymentId, network: net }) => collect(async (print) => {
+            const on = await mandateTarget(net);
+            const args = {
+                credentialPath,
+                mandateKeyFile,
+                to: parseAddress(to, "to"),
+                amount: parsePullAmount(amount, "amount"),
+                paymentId: parsePaymentId(paymentId, "paymentId"),
+                keyPath: undefined,
+                recordRefusal: false,
+            };
+            await assertMandateKey(authority);
+            let revoked = false;
+            const outcome = await mandatePull(on, args, (line) => {
+                if (line === `reason ${describeRefusal("Revoked")}`)
+                    revoked = true;
+                print(line);
+            });
+            const next = outcome === "refused" && revoked ? REVOKED_NEXT : pullNext(outcome, { to: args.to, amount, paymentId });
+            if (next !== undefined)
+                print(next);
+            if (outcome === "refused")
+                return "failed";
+        }));
+        server.registerTool("mandate_status", {
+            description: "Show this server's mandate: the limits its owner set (payees, the most per payment, the budget, the most payments when capped, its start and expiry), whether it is bound on the owner's account and, once bound, whether it is revoked, `spent <amount> of <budget>` and `payments`. Call it to see what the mandate has left, before a payment or after a refusal.",
+            inputSchema: z.object({ network }).strict(),
+        }, ({ network: net }) => collect(async (print) => {
+            const on = await mandateTarget(net);
+            const state = await mandateStatus(on, credentialPath, accountFactoryFor(on.network, undefined, "run mandate status from the CLI with --factory"), print);
+            if (state === "unbound")
+                print("next: every payment is refused until its owner binds it, creating the account first when account-type is none; tell the user");
+            if (state === "revoked")
+                print(REVOKED_NEXT);
+        }));
+        server.registerTool("mandate_verify", {
+            description: "Check this server's mandate and every payment and refusal under it from the chain alone, or one of this mandate's payments by txHash, with the signed order pay printed for it as signedOffer. " +
+                "Returns four `step` lines, one line per payment or refusal found, and `verified yes` or `verified no`. Fails naming an event under the mandate this SDK does not decode, as an account of another version emits.",
+            inputSchema: z
+                .object({
+                issuers: z.array(z.string()).min(1).describe("The issuer public key files the user trusts, such as the owner's <key>.issuer.public.json: ask the user for them"),
+                txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/).optional().describe("One transaction to check instead of every payment"),
+                signedOffer: z.string().optional().describe("The signed order pay printed for that transaction's payment, checked against it; needs txHash"),
+                network,
+            })
+                .strict(),
+        }, ({ issuers, txHash, signedOffer, network: net }) => collect(async (print) => {
+            if (signedOffer !== undefined && txHash === undefined)
+                throw new Error("signedOffer goes with txHash, the payment it was made for");
+            const on = await mandateTarget(net);
+            for (const path of issuers)
+                await readIssuerFile(path);
+            const args = {
+                accountFactory: accountFactoryFor(on.network, undefined, "run mandate verify from the CLI with --factory"),
+                credentialPath,
+                issuerPaths: issuers,
+                tx: txHash === undefined ? undefined : parseTxHash(txHash, "txHash"),
+                signedOffer,
+            };
+            if ((await mandateVerify(on, args, print)) === "failed")
+                return "failed";
+        }));
+    }
     return server;
 }
+/** The server's mandate key, checked when it started and read again by each call: one gone since is the user's to restore. */
+async function assertMandateKey({ credentialPath, mandateKeyFile }) {
+    const mandate = await loadMandate(credentialPath);
+    await mandateAgentSigner(mandate, credentialPath, mandateKeyFile).catch(() => {
+        throw new Error(`the server's mandate key, ${mandateKeyFile ?? `beside ${credentialPath}`}, cannot be read as this mandate's: tell the user to put it back, or to restart the server with --mandate-key-file naming it`);
+    });
+}
+/** Whether `path` is the agent's default key file; an empty HOME names none. */
+function isDefaultKey(path) {
+    try {
+        return path === defaultKeyPath();
+    }
+    catch {
+        return false;
+    }
+}
+/** Runs a command for a tool, returning the lines it printed; a command that ends `failed`, or throws, is the tool's error. */
 async function collect(run) {
     const lines = [];
     try {
-        await run((line) => lines.push(line));
-        return { content: [{ type: "text", text: lines.join("\n") }] };
+        const failed = (await run((line) => lines.push(line))) === "failed";
+        return { content: [{ type: "text", text: lines.join("\n") }], ...(failed && { isError: true }) };
     }
     catch (error) {
+        // A chain library's message ends in its version and the request; its short message says what failed, and the node's own words lead,
+        // as the library's short message for a node's error reads as the caller's mistake.
+        const node = error instanceof BaseError ? error.walk((e) => e instanceof RpcRequestError) : null;
+        const message = node instanceof RpcRequestError
+            ? `the node answered: ${node.details}`
+            : error instanceof BaseError
+                ? `${error.shortMessage}${error.details ? ` Details: ${error.details}` : ""}`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
         // The result goes to the model: an endpoint's URL in it would hand over the endpoint's credential.
-        lines.push(`error: ${redactUrls(error instanceof Error ? error.message : String(error))}`);
+        lines.push(`error: ${redactUrls(message)}`);
         return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
     }
 }
-/** 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. */
+/** Serves over stdio. A mandate, its mandate key and the home its pulls are kept under 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);
+    if (authority.kind === "mandate") {
+        const mandate = await loadMandate(authority.credentialPath);
+        await mandateAgentSigner(mandate, authority.credentialPath, authority.mandateKeyFile);
+        pendingPullsPath(mandate.reference);
+    }
     await createMcpServer(authority).connect(new StdioServerTransport());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalntwx/metal-agent",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "The `metal-agent` CLI and MCP server: create or import the agent's 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": {
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "@metalntwx/metal-ts": "^0.3.2",
-    "@metalntwx/metal-pay": "^0.3.0",
+    "@metalntwx/metal-pay": "^0.3.2",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@x402/core": "2.28.0",
     "viem": "^2.54.6",