@metalntwx/metal-agent 0.1.1 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metalntwx/metal-agent",
-  "version": "0.1.1",
-  "description": "The `metal-agent` CLI and MCP server: create or import an agent key, fund it on Metal devnet or testnet, pay x402 offers in *USDZ, look up a settlement, and set spending limits for an agent that Metal enforces.",
+  "version": "0.3.0",
+  "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": {
     "type": "git",
@@ -18,15 +18,15 @@
     "skills"
   ],
   "dependencies": {
-    "@metalntwx/metal-ts": "^0.3.1",
-    "@metalntwx/metal-pay": "^0.1.1",
-    "@modelcontextprotocol/sdk": "1.31.0",
-    "@x402/core": "2.21.0",
+    "@metalntwx/metal-ts": "^0.3.2",
+    "@metalntwx/metal-pay": "^0.3.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@x402/core": "2.28.0",
     "viem": "^2.54.6",
     "zod": "^3.25.76"
   },
   "dependencyRationale": {
-    "@metalntwx/metal-ts": "Funds the agent key with a MIP20 transfer, decodes settled transfers, and sends the EIP-7702 delegation a mandate needs.",
+    "@metalntwx/metal-ts": "Funds a key on devnet with a MIP20 transfer.",
     "@metalntwx/metal-pay": "The one-call x402 payment clients, mandates, and the Metal network constants.",
     "@modelcontextprotocol/sdk": "The stdio MCP server behind `metal-agent mcp`.",
     "@x402/core": "Decodes the `payment-response` header a paid request returns.",

package/skills/metal-agent/SKILL.md

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