@metalntwx/metal-agent 0.1.1 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @metalntwx/metal-agent
 
 The `metal-agent` CLI an agent pays x402 payees on Metal with: create or
-import a key, fund it, pay a URL, look up a settlement, or serve the same
-commands as MCP tools.
+import a key, fund it, pay a URL, look up a settlement, or serve `pay`,
+`fund` and `status` as MCP tools.
 
 ```bash
 npm install -g @metalntwx/metal-agent
@@ -25,10 +25,12 @@ endpoints) and the `*USDZ` address come from `@metalntwx/metal-pay`, and
 `networks.json` holds its demo payee URL and, on testnet, its faucet and
 explorer URLs.
 `METAL_RPC_URL` and `METAL_FAUCET_URL` override those defaults, and
-`--rpc-url` and `--faucet-url` override both.
+`--rpc-url` and `--faucet-url` override both; `METAL_FACILITATOR_URL` and
+`--facilitator-url` do the same for `mandate pull`.
 
-On testnet, `pay` and `fund` need no RPC. `status --network testnet` needs
-an endpoint of your own: sign up in the Metal console,
+On testnet, `pay` and `fund` need no RPC. `status`, `account create` and
+every `mandate` command but `credential create` need an endpoint of your
+own: sign up in the Metal console,
 https://console-testnet.metalntwx.com, create an endpoint, and pass it with
 `--rpc-url` or `METAL_RPC_URL`. On testnet, `pay` and `fund` print
 an `explorer` line with the transaction's page on
@@ -48,7 +50,8 @@ which the devnet funds at genesis.
 
 `pay` refuses, before it signs, an offer in any token but `*USDZ` and any
 offer above `--max`, 1 `*USDZ` per payment by default. A refusal at
-verification prints `payment refused: <reason>`.
+verification, by the facilitator or the seller's own check, prints
+`payment refused: <reason>`.
 A refusal at settlement prints `payment refused at settlement: <reason>`,
 with the transaction hash when there is one.
 
@@ -77,68 +80,83 @@ for the mandate's whole life, an expiry and, when `--payee` names any, the
 addresses it may pay; with none named it may pay any address.
 
 ```bash
-metal-agent mandate credential create --principal <MetalAccount address> [--payee <address>]... \
-  --cap 5 --budget 10 --out ./mandate.json --network testnet
+metal-agent mandate credential create --principal <MetalAccount address> [--payee <address>[,<name>[,<website>]]]... \
+  --cap 5 --budget 10 [--description <text>] --key <owner key file> --out ./mandate.json --network testnet
 metal-agent mandate bind --credential ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
 metal-agent pay <url> --mandate ./mandate.json --network testnet
 metal-agent mandate status --credential ./mandate.json --network testnet --rpc-url <endpoint>
+metal-agent mandate pull --credential ./mandate.json --to <address> --amount 2.50 --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --issuer <issuer public key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate verify --credential ./mandate.json --issuer <issuer public key file> --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>
 metal-agent mandate replace --credential ./wider.json --replaces ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
+metal-agent mandate renew --credential ./next.json --replaces ./mandate.json --key <owner key file> --network testnet --rpc-url <endpoint>
 metal-agent mandate revoke --credential ./wider.json --key <owner key file> --network testnet --rpc-url <endpoint>
-metal-agent mandate pull --credential ./mandate.json --to <address> --amount 2.50 --network testnet --rpc-url <endpoint>
-metal-agent mandate verify --credential ./mandate.json --network testnet --rpc-url <endpoint>
-metal-agent mandate verify --credential ./mandate.json --tx <hash> --signed-offer <text> --network testnet --rpc-url <endpoint>
 ```
 
 `credential create` writes the limits into a credential file, a Verifiable
-Intent mandate, and the agent's keys beside it: its mandate key in
-`mandate.agent-key.json`, and in `mandate.gas-key.json` the key that pays
-for its pulls. `--agent-key <file>` names a mandate key the agent already
-has instead, with its gas key beside that. The issuer keys that sign the
-credential are created on first use (`~/.metal-agent/issuer.json`, with its
-public half beside it in `issuer.public.json`). Every other command takes
-that credential file: the owner's account, the mandate's reference, its
-terms and the agent's key files derive from it. Amounts are whole cents; a
-mandate lasts 30 days unless `--expires-in` says otherwise.
-
-`account create --out <owner key file>` writes the owner's key and names the
-owner's Metal account, a smart account that key controls with threshold one,
-which the owner's first `bind` creates on chain; `--key <file>` uses a key
-that exists. Fund the account and name it as the credential's `--principal`.
+Intent mandate, and beside it the mandate key the agent signs with:
+`mandate.key.json` for `mandate.json`. `--mandate-key-file <file>` names a
+mandate key that exists instead, as a replacement does. The keys
+that sign the credential are the owner's: they live beside the owner's key file, created
+on first use (`owner-key.issuer.json`, with its public half in
+`owner-key.issuer.public.json`), unless `--issuer-key` names their file.
+`--description` says what the mandate is for, and `--payee` takes a name
+and a website after the address. Every other command takes
+that credential file: the owner's account, the mandate's id and its
+terms derive from it. Amounts are in `*USDZ`, to the cent; a
+mandate lasts 30 days unless `--expires-in` says otherwise, and its budget
+never resets.
+
+`account create --out <owner key file>` writes the owner's key and creates the
+owner's Metal account on chain, a smart account that key controls with
+threshold one; `--key <file>` uses a key that exists. The owner's key pays the
+gas, and one that holds none is funded first. Fund the account and name it as
+the credential's `--principal`; `bind` refuses an address with no account.
 The account factory is the one `@metalntwx/metal-pay` names for the network;
 on a devnet `just deploy` deploys it there, and `--factory <address>` names
-another. The testnet's factory is redeployed with each reset, and
-`@metalntwx/metal-pay` names the current one.
-
-`bind`, `replace` and `revoke` execute self-calls through the account's weighted
-quorum. `--key` names the gas sponsor and defaults as the sole signer; repeat
-`--signer-key <file>` to supply the EOA signers of an existing multisig instead.
-The SDK's `authorizeMandateCall` accepts a quorum-signing callback for mixed
-keys and passkeys. Keep owner keys outside the agent's reach: quorum-approved
-transfers remain independent of mandates. `replace` revokes the mandate
-`--replaces` names and carries its spend into the new one.
+another. `@metalntwx/metal-pay` names the testnet's.
+
+`bind`, `replace` and `revoke` are signed by the account's owners, as many as
+its threshold needs. `--key` names the gas sponsor and defaults as the sole
+signer; repeat `--signer-key <file>` to supply the owners' keys of an account
+with several instead. The SDK's `authorizeMandateCall` accepts a signing
+callback for mixed keys and passkeys. Keep owner keys outside the agent's
+reach: an owner key moves the account's funds outside any mandate's limits. `replace` revokes the mandate
+`--replaces` names and carries its spend into the new one; `renew` binds the
+new one and revokes the old in one batch, starting its spend at nothing, which
+is how a budget starts over.
+`bind`, `replace` and `renew` trust the issuer beside `--key` unless
+`--issuer` names others.
 
 Verification trusts that factory, never one a payer names: it checks the
-account's immutable clone code against the factory's implementation at the
-binding and payment blocks, and checks successful token-transfer receipts.
+account's immutable clone code against the factory's current
+implementation, and checks successful token-transfer receipts.
 
 `pay --mandate <credential>` pays from the owner's account, signed by the
-agent's mandate key, and takes neither `--key` nor `--max`. A payment
-outside the mandate is refused at the facilitator's simulation, which names
-the limit: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
+mandate key beside the credential, or the one `--mandate-key-file` names.
+It takes neither `--key` nor `--max`. A payment
+outside the mandate is refused and moves nothing, usually with a
+`mandate_*` reason: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
 payment's `nonce` as soon as it signs; the facilitator's
 `/settlements?payTo=<payee>` lists a settled payment by an id ending in it.
 
 `mandate pull` pays an address the mandate allows directly, with no seller:
-the agent's mandate key signs, and the `--key` account, the agent's gas key
-by default, submits the transaction and pays its gas, so fund it with a
-little `*USDZ`. A pull outside the mandate is recorded on chain as a
-refusal, in a transaction that succeeds and moves nothing, and exits 1.
+the agent's mandate key signs, and the facilitator submits the transaction
+and pays its gas; `--key` names a funded key to submit it instead. A pull
+the mandate refuses when checked is not sent: it reports the reason and
+exits 1. With `--key`, `--record-refusal` sends it, so the refusal is
+recorded on chain in a transaction that succeeds and moves nothing. The
+outcome is read from the chain: `paid`, `refused`, `held` when the payee's
+receive policy sends it to escrow, or `pending`. A pending pull is kept in
+the directory beside the credential, `mandate.pulls` for `mandate.json`, and
+running the same command again sends that same pull, which pays at most once.
 
 `mandate verify` checks the mandate and every payment under it from the
 chain alone, through any RPC endpoint: the binding on the owner's account,
 the credential against it and under its issuer, and each payment and
-refusal as the agent key's own signed per-payment mandate, rebuilt from its
-transaction. Anyone holding the credential can run it; `--tx <hash>`
+refusal as the mandate key's own signed per-payment mandate, rebuilt from its
+transaction. Anyone holding the credential and the issuer's public file,
+passed as `--issuer`, can run it; `--tx <hash>`
 verifies one transaction, with `--signed-offer <text>` the offer the agent
 signed for it, and a check that fails exits 1. A seller that asks for the
 agent's signed order (`requireSignedOffer` in `@metalntwx/metal-pay/mandates`,
@@ -149,17 +167,25 @@ the same, the latter for a payee that holds no credential.
 `skills/metal-agent/SKILL.md` is an installable skill: the setup steps for
 an agent, then the commands.
 
-`metal-agent mcp` serves `pay`, `fund` and `status` over stdio,
-each taking a `network`, and `pay` takes the same limit as an optional
-`max`, the request as optional `method`, `body` and `headers`, and a
-credential file as an optional `mandate`, with its `agentKey`. Keys
-enter only through the CLI, and so do the mandate commands: the server has
-no tool that sets or changes a mandate. An MCP host starts it with:
+`metal-agent mcp` serves `pay`, `fund` and `status` over stdio, each taking
+a `network`, and `pay` the request as optional `method`, `body` and
+`headers`. What `pay` spends is fixed when the server starts: its key and
+`--max` (the default key file and 1 `*USDZ` when omitted), or one mandate
+with `--mandate <credential>`. The model calling the tools chooses no key,
+no mandate and no higher limit; under a key, a `max` it passes can only
+lower the server's. The mandate commands enter only through the CLI. An MCP host
+starts it with:
 
 ```json
 { "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp"] }
 ```
 
+or, under one mandate:
+
+```json
+{ "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"] }
+```
+
 ## Develop
 
 In the `mx56db/metal` repository, `just agent <command>` runs the CLI from

package/dist/chain.js

@@ -22,7 +22,7 @@ export function resolveSettings(network, file, flags, env) {
     const faucetUrl = flags.faucetUrl ?? env["METAL_FAUCET_URL"] ?? file.faucetUrl;
     return {
         ...(rpcUrl !== undefined && { rpcUrl }),
-        facilitatorUrl: env["METAL_FACILITATOR_URL"] ?? network.facilitatorUrl,
+        facilitatorUrl: flags.facilitatorUrl ?? env["METAL_FACILITATOR_URL"] ?? network.facilitatorUrl,
         demoPayeeUrl: env["METAL_DEMO_PAYEE_URL"] ?? file.demoPayeeUrl,
         ...(faucetUrl !== undefined && { faucetUrl }),
         ...(file.explorerUrl !== undefined && { explorerUrl: file.explorerUrl }),