@metalntwx/metal-agent 0.2.0 → 0.3.1

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
@@ -20,8 +20,8 @@ set, and pass it with `--rpc-url`. A user without one creates it as
 The key file defaults to `~/.metal-agent/key.json`. It holds the private key
 in the clear, owner-readable only; treat the file as the secret.
 
-If `metal-agent --help` runs and the user already has a key, go to the
-command you need. Otherwise start with Setup.
+If `metal-agent --version` prints `0.3.1` and the user already has a key,
+go to the command you need. Otherwise start with Setup.
 
 ## Setup
 
@@ -30,13 +30,15 @@ Run the steps in order. After each step, show the user its output.
 1. Check Node.js with `node --version`. If it is missing, tell the user to
    install Node.js, and stop.
 
-2. Check for the CLI with `metal-agent --help`. If it is not found, install
-   it:
+2. Install the CLI, or move an installed one to this version:
 
    ```bash
-   npm install -g @metalntwx/metal-agent
+   npm install -g @metalntwx/metal-agent@0.3.1
    ```
 
+   Then `metal-agent --version` prints `0.3.1`. If it prints anything else,
+   another copy comes first on the `PATH`: tell the user, and stop.
+
 3. Install this skill, so that later sessions have it without fetching this
    page. Copy the directory
    `$(npm root -g)/@metalntwx/metal-agent/skills/metal-agent` into your
@@ -48,7 +50,7 @@ Run the steps in order. After each step, show the user its output.
    In Claude Code:
 
    ```bash
-   claude mcp add metal-agent -- npx -y @metalntwx/metal-agent mcp
+   claude mcp add metal-agent -- npx -y @metalntwx/metal-agent@0.3.1 mcp
    ```
 
    In any other MCP host, add this server to its MCP configuration:
@@ -58,7 +60,7 @@ Run the steps in order. After each step, show the user its output.
      "mcpServers": {
        "metal-agent": {
          "command": "npx",
-         "args": ["-y", "@metalntwx/metal-agent", "mcp"]
+         "args": ["-y", "@metalntwx/metal-agent@0.3.1", "mcp"]
        }
      }
    }
@@ -66,16 +68,22 @@ 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`.
+   `--mandate <credential>` after `mcp`. Under a mandate on testnet, also set
+   the user's endpoint in the server's environment, or in an `env` block in
+   another host's configuration:
+
+   ```bash
+   claude mcp add metal-agent -e METAL_RPC_URL=<endpoint> -- npx -y @metalntwx/metal-agent@0.3.1 mcp --mandate <credential>
+   ```
 
    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
-   user for its address.
+   `metal-agent key create`. Tell the user the address. If either answers
+   that the key file already holds a key, tell the user the address in its
+   `address` field, and ask whether to pay with that key.
 
 6. Fund the key from the testnet faucet, unless the user said it is funded,
    and show the user the `transaction` and `explorer` lines:
@@ -112,12 +120,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
@@ -135,11 +143,13 @@ Ask the public faucet for `*USDZ`; the faucet sets the amount.
 An address that already holds a full grant is reported as funded. A grant
 prints `transaction <hash>` and `explorer <url>`, the transaction's page on
 the block explorer. The faucet limits how often one client can ask: on a
-`client_rate_limited` error, wait the seconds it names; on a daily-limit
-error, load a pre-funded key with `key import`.
+`client_rate_limited` error, wait the seconds it names; on
+`client_daily_limit_reached`, fund the address from the Faucet page in the
+Metal console the error names; on either daily-limit error, load a
+pre-funded key with `key import`.
 
 ```bash
-metal-agent fund 0x40daBEc53aA45faC6d0eaCCA5713fac49d8d213c --network testnet
+metal-agent fund <address> --network testnet
 ```
 
 ## pay
@@ -149,7 +159,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,
@@ -168,10 +178,11 @@ metal-agent pay https://example.com/report --network testnet --max 5
 For a request other than GET, pass `--method` (POST when there is a body),
 `--body` (sent as `application/json` unless a `--header` names a content
 type) and repeated `--header 'name: value'`; `pay` sends them again with the
-payment. To buy RPC over x402, POST the JSON-RPC call to the RPC URL:
+payment. To buy RPC over x402, POST the JSON-RPC call to
+`https://rpc-testnet.metalntwx.com/v1`:
 
 ```bash
-metal-agent pay <rpc url> --network testnet --method POST --body '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
+metal-agent pay https://rpc-testnet.metalntwx.com/v1 --network testnet --method POST --body '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
 ```
 
 The output's `header rpc-aas-endpoint: <url>` is the endpoint that payment
@@ -187,15 +198,16 @@ 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, or the seller's own check refused.
+  verification, or the seller's own check refused; nothing was paid.
 - `error: payment refused at settlement: <reason>` means the facilitator
-  refused at settlement, with the transaction hash when there is one. On
+  refused at settlement for a reason that moves nothing, with the
+  transaction hash when there is one; nothing was paid. On
   `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.
+- On `error: payment in doubt at settlement: …`, 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`
 
@@ -208,19 +220,21 @@ 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, and
-pay with that. If the error says there is no agent key, pass the
-`--agent-key` it names.
+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 --issuer <file> --tx <hash> --signed-offer <text>` to check the two
-together.
+`mandate verify --credential <file> --issuer <file> --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>`
+to check the two together.
 
 `mandate status` shows what is left: read `spent <amount> of <budget>`,
 `revoked yes|no` and the `payee` lines.
@@ -229,22 +243,42 @@ 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, so ask the user to fund its `gas-key-address` first. `outcome paid`, or `outcome refused, not sent` with `reason` and `recorded no` lines,
-says what happened; a pull refused when checked sends nothing and costs no gas. Pass
-`--record-refusal` only when the user asks for the refusal to be recorded
-on chain. If a pull fails after printing `transaction <hash>`, run
-`metal-agent status <hash>` before pulling again; it may have paid.
+`mandate pull` pays an address the mandate allows, with no seller. The
+facilitator submits it and pays the gas. Pass `--payment-id` with the id of
+the payment it is for, such as the refund's or the invoice's: two payouts of
+one amount to one payee, while the first is pending, are two payments
+only under two ids. The `outcome`
+line says what happened: `paid`, exit 0; `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`,
+exit 4, for one the payee's receive policy holds in escrow, so the payee was
+not paid and the amount counts against the budget: do not send it again;
+the payee, or the authority its policy names, releases it; or `pending`,
+exit 3. Refusals exit 1. 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, on the
+same machine, with the same credential, `--payment-id`, `--to` and
+`--amount`: it sends the same pull, which pays at most once, or reports its
+outcome. Never add, drop or change the payment id, or change the amount, to
+pay a pending pull again. After `outcome refused`, nothing was paid, and the
+same payment id may be sent with other values. `error: the pull was not
+sent: …` names why, such as the facilitator's refusal; tell the user.
+An error saying `the pull kept before may have been sent and can land until
+…` means that pull can still land until then: tell the user, and never pay
+it under another payment id. The same holds for an error naming an event the SDK
+does not decode: the pull may have paid.
 
 ```bash
-metal-agent mandate pull --credential ./mandate.json --to <payee address> --amount 2.50 --network testnet --rpc-url <endpoint>
+metal-agent mandate pull --credential ./mandate.json --to <payee address> --amount 2.50 --payment-id <payment id> --network testnet --rpc-url <endpoint>
 ```
 
 `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. It needs
+`verified yes|no`, and a failed `step` line names what differs. A failure
+that names a topic the SDK does not decode means metal-agent and the
+account may be different versions; tell the user. It needs
 the issuer's public key file, the `issuer-public-file` that `credential
 create` printed; ask the user for it.
 
@@ -252,9 +286,6 @@ create` printed; ask the user for it.
 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
@@ -269,12 +300,23 @@ 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. What `pay` spends is fixed when the server starts,
-by its key and `--max`, or by one mandate; `pay` takes the request as
+stdio for an MCP host; under a mandate, `mandate_pull`, `mandate_status` and
+`mandate_verify` as well. What `pay` and `mandate_pull` spend is set when
+the server starts, by whoever starts it: a key file and `--max`, or one
+mandate's credential file, which each call reads. `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.
+only lower the server's limit, and ends a refusal after signing, or a
+payment that may have settled, with a `next:` line. `fund` and `status`
+take the endpoint as `rpcUrl`, which
+`status` on testnet needs unless the server's environment sets
+`METAL_RPC_URL`. With the server's `METAL_RPC_URL`, `fund` asks the testnet
+faucet nothing for an address that already holds about a full grant. The
+mandate tools take no `rpcUrl`: they read the chain through the server's
+`METAL_RPC_URL`, or devnet's default endpoint, and fail naming a chain other
+than the network's. `mandate_pull` takes `to`, `amount` and a `paymentId`,
+one per payment, and ends any outcome but `paid` with a `next:` line;
+`mandate_verify` takes the `issuers` to trust. No tool chooses a key, a
+mandate or a higher limit, and none sets or changes a mandate.
 
 ```bash
 metal-agent mcp