warpmetal 0.7.3 → 0.7.4

package/README.md

@@ -34,7 +34,7 @@ published wallet CLI with the exact version WarpMetal reports:
 npm install --global warpmetal
 warpmetal --help
 
-npm install --global @x402api/agent-wallet-cli@0.2.4
+npm install --global @x402api/agent-wallet-cli@0.2.5
 x402api help --json
 ```
 
@@ -58,7 +58,7 @@ integration.
 
 The repository also contains a skills-only WarpMetal plugin for the public
 Plugins Directory shared by Codex and ChatGPT. The plugin remains a separate
-artifact from the npm CLI and requires `warpmetal` CLI version 0.7.3 or newer.
+artifact from the npm CLI and requires `warpmetal` CLI version 0.7.4 or newer.
 
 To test the repository marketplace after the plugin lands on `main`:
 
@@ -116,8 +116,8 @@ that WarpMetal uses for merchant-side reconciliation, the pinned
 `paymentWorkflow`. It also writes an owner-only request envelope that contains
 the exact checkout URL and body but no WarpMetal credential or challenge
 handle. The handle is not a buyer payment identifier and is never a wallet
-signing input. The published
-launch wallet accepts sponsored Base USDC and sponsored Solana USDC/USDT only;
+signing input. The published launch wallet accepts sponsored Base USDC and
+sponsored Solana USDC/USDT only;
 the returned terms identify compatible alternatives and confirm that the buyer
 does not need ETH or SOL. x402api pays the actual network fee from its platform
 treasury; the merchant tenant's active allowance controls sponsorship
@@ -131,7 +131,31 @@ context:
   limits. When the live terms fit those limits, authorize and submit without
   waiting for conversational approval.
 
-Then invoke the returned authorization argv with a dedicated wallet name:
+Follow the returned commands in order. `wallet setup` creates an owner-only,
+managed unlock file inside the x402api home directory and is safe to repeat;
+it never prints the generated passphrase. `X402API_WALLET_PASSWORD_FILE` is an
+optional x402api override for an externally managed password file. It is not a
+WarpMetal variable, and WarpMetal does not create, read, or receive that file.
+
+```sh
+x402api wallet setup --json
+x402api wallet list --json
+x402api wallet create --name <wallet-name> \
+  --network <exact-challenge-network> \
+  --maximum-payment-atomic <exact-live-amount> --json
+x402api wallet address --wallet <wallet-name> --json
+x402api wallet balance --wallet <wallet-name> \
+  --asset <exact-challenge-asset> --json
+x402api wallet funding --wallet <wallet-name> \
+  --asset <exact-challenge-asset> \
+  --target-balance-atomic <exact-live-amount> --json
+```
+
+Create a wallet only when no compatible dedicated wallet exists. The funding
+command reports the public payer address, QR payload, current balance, target,
+and exact deficit in atomic and normal six-decimal units. After the selected
+wallet is sufficiently funded, invoke the returned authorization and WarpMetal
+submission argv:
 
 ```sh
 x402api payment authorize \
@@ -147,23 +171,6 @@ warpmetal checkout submit \
   --json
 ```
 
-Check the payer wallet address and balance with:
-
-```sh
-x402api wallet show --wallet <wallet-name> --json
-x402api wallet address --wallet <wallet-name> --json
-x402api wallet balance --wallet <wallet-name> --json
-```
-
-For a new dedicated wallet, configure the enforceable local per-payment
-ceiling when it is created:
-
-```sh
-x402api wallet create --name <wallet-name> \
-  --network <exact-challenge-network> \
-  --maximum-payment-atomic <per-payment-policy-cap> --json
-```
-
 Require `maximumPaymentAtomic` to cover the live charge without exceeding the
 task or operator limit. Among valid sponsored terms, honor an explicit network
 or asset preference, otherwise prefer an already funded compatible wallet,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/SKILL.md

@@ -11,20 +11,20 @@ with ad hoc HTTP commands.
 
 ## Start safely
 
-1. Run `warpmetal --version` and require version `0.7.3` or newer for this
+1. Run `warpmetal --version` and require version `0.7.4` or newer for this
    plugin. If it is missing or older, explain the compatibility requirement,
    ask before installing or upgrading software, and use only the official npm
    package from `https://www.npmjs.com/package/warpmetal`.
-3. Use `--json` for every agent-driven command.
-4. Read [references/safety.md](references/safety.md) before preparing an order,
+2. Use `--json` for every agent-driven command.
+3. Read [references/safety.md](references/safety.md) before preparing an order,
    authorizing payment, using an SSH identity, or changing a server.
-5. Read [references/cli-reference.md](references/cli-reference.md) when choosing
+4. Read [references/cli-reference.md](references/cli-reference.md) when choosing
    a command or interpreting an exit code.
-6. Read [references/payments.md](references/payments.md) before creating or
+5. Read [references/payments.md](references/payments.md) before creating or
    funding a wallet, authorizing payment, or resolving an ambiguous attempt.
-7. Read [references/runtime.md](references/runtime.md) before requesting,
+6. Read [references/runtime.md](references/runtime.md) before requesting,
    installing, accessing, expiring, or deleting Agent Runtime sandboxes.
-8. Read [references/renewals.md](references/renewals.md) before configuring or
+7. Read [references/renewals.md](references/renewals.md) before configuring or
    executing an autonomous renewal or requesting a wallet refill.
 
 Never read, print, summarize, upload, or commit the WarpMetal state file,
@@ -99,8 +99,12 @@ when the exact live terms fit those limits.
 
 Follow [references/payments.md](references/payments.md) to install the exact
 `paymentWorkflow.signerPackage.spec`, verify the V1 machine contract, install
-its matching `x402api-pay` skill, and select or fund a dedicated
-network-specific wallet. Require `agentWalletSupported: true`,
+its matching `x402api-pay` skill, and invoke the returned wallet sequence:
+`wallet setup`, `wallet list`, network-specific `wallet create` only if needed,
+then the exact address, asset-balance, and funding commands. `wallet setup`
+owns the managed unlock file; `X402API_WALLET_PASSWORD_FILE` is only an
+optional x402api override and is never a WarpMetal input. Require
+`agentWalletSupported: true`,
 `sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false` on the chosen
 live term. Never fall back to a historical buyer-funded or TRON profile.
 Honor an explicit task or operator network and asset preference. Otherwise use

package/skills/warpmetal/references/cli-reference.md

@@ -56,8 +56,11 @@ On HTTP 402, `checkout challenge` validates and displays exact payment terms,
 writes the opaque x402api `challengeHandle` to private WarpMetal state for
 merchant reconciliation, and writes a credential-free x402api V1 request envelope with owner-only
 permissions, and returns the exact pinned wallet package, V1 contract probe,
-matching wallet-skill install, authorization, and WarpMetal submission argv
-arrays. The default envelope and suggested artifact paths live under the
+matching wallet-skill install, setup, list, network-specific create,
+address/balance/funding, authorization, and WarpMetal submission argv arrays.
+The returned top-level `paymentWorkflow.sequence` fixes their order. Funding
+options remain paired by exact live network and asset. The default envelope and
+suggested artifact paths live under the
 private WarpMetal state directory. An explicit output path must not already
 contain different content. `challengeHandle` is intentionally absent from the
 wallet envelope: it is neither a buyer payment identifier nor signing input.
@@ -66,7 +69,7 @@ retire that attempt and return a new `paymentAttemptId`. The CLI replaces the
 saved challenge and stale wallet-attempt metadata; use only the newly returned
 workflow.
 
-The current integration targets `@x402api/agent-wallet-cli@0.2.4`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.5`. A compatible
 live term is marked `agentWalletSupported: true` and must use the sponsored
 Base USDC or Solana USDC/USDT launch profile with buyer native fees disabled.
 For the current declaration, x402api pays actual gas from its platform treasury

package/skills/warpmetal/references/payments.md

@@ -25,7 +25,7 @@ contract.
 WarpMetal runs on Node.js 20 or 22. The x402api Agent Wallet currently requires
 Node.js 22. Use the exact published package reported by
 `paymentWorkflow.signerPackage.spec`; the current contract is
-`@x402api/agent-wallet-cli@0.2.4`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.5`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -40,9 +40,15 @@ skill automatically.
 1. Install the exact `paymentWorkflow.signerPackage.install.argv` under Node
    22. Run `command -v x402api` and the returned
    `paymentWorkflow.signerContract.probe.argv`. Require contract version 1.
-2. Ensure an operator configured `X402API_WALLET_PASSWORD_FILE` as an owner-only
-   file, or is supervising `--password-stdin`. Never read either value.
-3. Use `x402api wallet list --json` and reuse a dedicated persistent wallet for
+2. Run the exact `paymentWorkflow.walletWorkflow.setup.argv`. The idempotent
+   `x402api wallet setup --json` command creates an owner-only managed unlock
+   file inside the x402api home directory and never prints its generated
+   passphrase. `X402API_WALLET_PASSWORD_FILE` is an optional x402api override
+   for an externally managed password file; it is not a WarpMetal setting.
+   Never create it on WarpMetal's behalf, read it, or pass it to WarpMetal. A
+   supervised operator may instead use `--password-stdin` where supported.
+3. Run the exact `paymentWorkflow.walletWorkflow.list.argv` and reuse a
+   dedicated persistent wallet for
    the exact challenge network.
 4. In an interactive conversation, create a wallet only with explicit
    approval. In an unattended run, create one only when the automation policy
@@ -63,13 +69,20 @@ skill automatically.
    higher than the task or operator limit. If an existing wallet has no ceiling
    or an unsuitable one, do not treat its full balance as bounded authority;
    use a suitably capped dedicated wallet or stop.
-5. Use both public, safe commands before requesting funding:
+5. Use the returned public address, exact asset-balance, and funding commands:
 
    ```sh
    x402api wallet address --wallet <name> --json
-   x402api wallet balance --wallet <name> --json
+   x402api wallet balance --wallet <name> \
+     --asset <exact-challenge-asset> --json
+   x402api wallet funding --wallet <name> \
+     --asset <exact-challenge-asset> \
+     --target-balance-atomic <required-or-policy-target> --json
    ```
 
+   Use only the selected term's returned argv; do not combine one network with
+   another term's asset. The funding result provides the current balance,
+   target, exact deficit, payer address, and QR payload without moving funds.
 6. If funding is short in an interactive conversation, show the exact deficit
    in normal token units and atomic units, the exact network, token symbol and
    contract/mint, and the payer wallet's public receiving address. Render only
@@ -136,7 +149,7 @@ reservation or any buyer-funded, unsupported, or unbound alternative.
 
 x402api pays actual gas from its platform treasury. The merchant tenant's
 active sponsorship allowance controls admission, but actual gas is not a
-tenant debit. During the coordinated rollout, accept only the exact 0.2.4
+tenant debit. During the coordinated rollout, accept only the exact 0.2.5
 platform-treasury declaration or the matched legacy tenant-credit declaration;
 never accept a mixed billing and final-charge policy.
 

package/skills/warpmetal/references/safety.md

@@ -46,6 +46,10 @@
 - Install only the exact `@x402api/agent-wallet-cli` version and matching
   bundled `x402api-pay` skill reported by WarpMetal. Never substitute an
   unpinned repository checkout or similarly named wallet package.
+- Let `x402api wallet setup` create and permission its managed unlock file.
+  `X402API_WALLET_PASSWORD_FILE` belongs to x402api only as an optional
+  externally managed override; WarpMetal must never create, read, or receive
+  it. Stop if x402api rejects unsafe ownership or permissions.
 - Never read or display an x402api password file, encrypted keystore, request
   envelope, payment artifact, or complete payment signature. Pass only their
   paths to the documented commands.
@@ -61,7 +65,7 @@ explicit approval immediately before:
 - installing the CLI or skill;
 - installing or repairing the Agent Runtime supervisor;
 - generating a new SSH key pair;
-- creating or funding a wallet;
+- creating a wallet or asking the human to transfer funds to it;
 - signing or submitting an x402 payment authorization;
 - booting, rebooting, or shutting down a server; and
 - creating a temporary sandbox after explaining its irreversible expiry;

package/src/cli.js

@@ -147,6 +147,22 @@ function shellCommand(argv) {
     .join(" ");
 }
 
+function walletWorkflowInstructions(workflow) {
+  const create = workflow.walletWorkflow.createOptions
+    .map(
+      (option) =>
+        `${option.network} ${option.asset}: ${shellCommand(option.argv)}`,
+    )
+    .join("\n");
+  const balanceAndFunding = workflow.fundingWorkflow.options
+    .map(
+      (option) =>
+        `${option.network} ${option.asset}:\n  Balance: ${shellCommand(option.balance.argv)}\n  Funding: ${shellCommand(option.funding.argv)}`,
+    )
+    .join("\n");
+  return `Wallet setup: ${shellCommand(workflow.walletWorkflow.setup.argv)}\nWallet list: ${shellCommand(workflow.walletWorkflow.list.argv)}\nCreate a compatible wallet only if needed:\n${create}\nCheck the selected wallet address: ${shellCommand(workflow.fundingWorkflow.address.argv)}\nCheck or fund the exact selected asset:\n${balanceAndFunding}`;
+}
+
 function emit(stream, value, json, human) {
   if (json) writeLine(stream, JSON.stringify(value, null, 2));
   else writeLine(stream, human);
@@ -413,6 +429,7 @@ async function attachPaymentWorkflow(
   );
   const workflow = paymentWorkflow({
     taskId,
+    terms: request.terms,
     requestEnvelopePath,
     paymentArtifactPath: defaults.paymentArtifactPath,
   });
@@ -653,7 +670,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     stringOption(options, "request-envelope-out"),
   );
   const paymentInstructions = safe.paymentWorkflow
-    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}, then show the payer address as both a QR code and copyable text.\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\n${walletWorkflowInstructions(safe.paymentWorkflow)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize only after selecting/funding one wallet: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
   emit(
     context.stdout,
@@ -1040,25 +1057,21 @@ async function attachRenewalPaymentWorkflow(
     requestedEnvelopePath || defaults.requestEnvelopePath,
     request.envelope,
   );
+  const refillTarget =
+    renewal.refillTargetAtomic &&
+    BigInt(renewal.refillTargetAtomic) >= BigInt(term.amountAtomic)
+      ? renewal.refillTargetAtomic
+      : term.amountAtomic;
   const workflow = paymentWorkflow({
     taskId: server.id,
     serverId,
     kind: "renewal",
     wallet: renewal.wallet,
+    terms: [term],
+    fundingTargetAtomic: refillTarget,
     requestEnvelopePath,
     paymentArtifactPath: defaults.paymentArtifactPath,
   });
-  const refillTarget =
-    renewal.refillTargetAtomic &&
-    BigInt(renewal.refillTargetAtomic) >= BigInt(term.amountAtomic)
-      ? renewal.refillTargetAtomic
-      : term.amountAtomic;
-  Object.assign(workflow.fundingWorkflow, {
-    network: term.network,
-    asset: term.asset,
-    requiredPaymentAtomic: term.amountAtomic,
-    targetBalanceAtomic: refillTarget,
-  });
   const refillNotification = refillNotificationState(
     notifications,
     renewal.policy,
@@ -1191,7 +1204,7 @@ async function handleRenewalPrepare(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const safe = await prepareRenewal(client, store, serverId, options, context);
   const fundingInstructions = safe.paymentWorkflow
-    ? `\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}. Show the returned payer address as both a QR code and copyable text, with the exact network, asset, and deficit.`
+    ? `\n${walletWorkflowInstructions(safe.paymentWorkflow)}. Show the returned payer address as both a QR code and copyable text, with the exact network, asset, and deficit.`
     : "";
   const refillInstructions = safe.refillWorkflow
     ? `\nFor verified email refill, set ${Object.entries(safe.refillWorkflow.environment).map(([key, value]) => `${key}=${value}`).join(" ")} and run: ${shellCommand(safe.refillWorkflow.argv)}`

package/src/payment.js

@@ -15,7 +15,7 @@ const MAX_ARTIFACT_BYTES = 1024 * 1024;
 const MAX_SIGNATURE_BYTES = 512 * 1024;
 
 export const AGENT_WALLET_PACKAGE = "@x402api/agent-wallet-cli";
-export const AGENT_WALLET_VERSION = "0.2.4";
+export const AGENT_WALLET_VERSION = "0.2.5";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";
@@ -707,10 +707,75 @@ export function paymentWorkflow({
   serverId,
   kind = "checkout",
   wallet = "<wallet-name>",
+  terms = [],
+  fundingTargetAtomic,
   requestEnvelopePath,
   paymentArtifactPath,
 }) {
+  const walletOptions = terms
+    .filter((term) => term?.agentWalletSupported)
+    .map((term) => {
+      const targetBalanceAtomic = fundingTargetAtomic || term.amountAtomic;
+      return {
+        network: term.network,
+        asset: term.asset,
+        requiredPaymentAtomic: term.amountAtomic,
+        targetBalanceAtomic,
+        create: {
+          argv: [
+            "x402api",
+            "wallet",
+            "create",
+            "--name",
+            "<wallet-name>",
+            "--network",
+            term.network,
+            "--maximum-payment-atomic",
+            term.amountAtomic,
+            "--json",
+          ],
+        },
+        address: {
+          argv: ["x402api", "wallet", "address", "--wallet", wallet, "--json"],
+        },
+        balance: {
+          argv: [
+            "x402api",
+            "wallet",
+            "balance",
+            "--wallet",
+            wallet,
+            "--asset",
+            term.asset,
+            "--json",
+          ],
+        },
+        funding: {
+          argv: [
+            "x402api",
+            "wallet",
+            "funding",
+            "--wallet",
+            wallet,
+            "--asset",
+            term.asset,
+            "--target-balance-atomic",
+            targetBalanceAtomic,
+            "--json",
+          ],
+        },
+      };
+    });
+  const selectedFunding = walletOptions.length === 1 ? walletOptions[0] : null;
   return {
+    sequence: [
+      "wallet_setup",
+      "wallet_list",
+      "wallet_create_if_needed",
+      "wallet_address_balance_funding",
+      "payment_authorize",
+      "warpmetal_submit",
+    ],
     signer: "x402api Agent Wallet",
     signerExecutable: "x402api",
     signerNodeRequirement: ">=22",
@@ -742,6 +807,28 @@ export function paymentWorkflow({
         ],
       },
     },
+    walletWorkflow: {
+      sequence: [
+        "setup",
+        "list",
+        "create_if_needed",
+        "address",
+        "balance",
+        "fund_if_needed",
+      ],
+      setup: { argv: ["x402api", "wallet", "setup", "--json"] },
+      list: { argv: ["x402api", "wallet", "list", "--json"] },
+      createOptions: walletOptions.map(
+        ({ network, asset, requiredPaymentAtomic, create }) => ({
+          network,
+          asset,
+          requiredPaymentAtomic,
+          ...create,
+        }),
+      ),
+      selection:
+        "Reuse a compatible capped wallet when available. Otherwise choose exactly one advertised option and replace only <wallet-name>.",
+    },
     requestEnvelopePath,
     paymentArtifactPath,
     authorize: {
@@ -766,8 +853,62 @@ export function paymentWorkflow({
         argv: ["x402api", "wallet", "address", "--wallet", wallet, "--json"],
       },
       balance: {
-        argv: ["x402api", "wallet", "balance", "--wallet", wallet, "--json"],
+        argv:
+          selectedFunding?.balance.argv ||
+          [
+            "x402api",
+            "wallet",
+            "balance",
+            "--wallet",
+            wallet,
+            "--asset",
+            "<asset-from-selected-term>",
+            "--json",
+          ],
       },
+      funding: {
+        argv:
+          selectedFunding?.funding.argv ||
+          [
+            "x402api",
+            "wallet",
+            "funding",
+            "--wallet",
+            wallet,
+            "--asset",
+            "<asset-from-selected-term>",
+            "--target-balance-atomic",
+            "<target-balance-atomic>",
+            "--json",
+          ],
+      },
+      options: walletOptions.map(
+        ({
+          network,
+          asset,
+          requiredPaymentAtomic,
+          targetBalanceAtomic,
+          address,
+          balance,
+          funding,
+        }) => ({
+          network,
+          asset,
+          requiredPaymentAtomic,
+          targetBalanceAtomic,
+          address,
+          balance,
+          funding,
+        }),
+      ),
+      ...(selectedFunding
+        ? {
+            network: selectedFunding.network,
+            asset: selectedFunding.asset,
+            requiredPaymentAtomic: selectedFunding.requiredPaymentAtomic,
+            targetBalanceAtomic: selectedFunding.targetBalanceAtomic,
+          }
+        : {}),
       presentation: {
         qrPayloadField: "address",
         textPayloadField: "address",
@@ -777,7 +918,7 @@ export function paymentWorkflow({
         showNetworkAndAsset: true,
       },
       safety:
-        "Encode and fund only the payer wallet public address. Never fund the token contract, mint, or WarpMetal merchant recipient; sponsored payments do not require ETH or SOL.",
+        "Run the exact selected funding argv. Encode and fund only its payer wallet public address. Never fund the token contract, mint, or WarpMetal merchant recipient; sponsored payments do not require ETH or SOL.",
     },
     submit: {
       argv: