warpmetal 0.3.1 → 0.4.1

package/README.md

@@ -4,8 +4,10 @@ The official command-line client and portable Agent Skill for WarpMetal.
 
 The CLI uses the public API at `https://api.warpmetal.com`, stores generated
 WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents. Version 0.3 adds guarded OS
-reload and Agent Runtime recovery to the fixed-size, isolated sandbox workflow.
+wallet private keys or SSH private-key contents. Version 0.4 adds a guarded
+x402api Agent Wallet handoff: WarpMetal writes the exact credential-free payment
+request, explains the next commands to an agent, validates the returned payment
+artifact, and submits it without absorbing wallet custody.
 
 ## Distribution
 
@@ -21,9 +23,16 @@ remains the stable executable API.
 
 ## Install
 
+WarpMetal supports Node.js 20 and 22. The separate x402api Agent Wallet
+requires Node.js 22; it is not a WarpMetal package dependency. Install the
+published wallet CLI with the exact version WarpMetal reports:
+
 ```sh
 npm install --global warpmetal
 warpmetal --help
+
+npm install --global @x402api/agent-wallet-cli@0.2.1
+x402api help --json
 ```
 
 Install the bundled skill for supported coding agents:
@@ -58,6 +67,67 @@ Pass `--json` for structured, secret-redacted output. Use
 `WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
 alternate state directory.
 
+## Pay through the x402api Agent Wallet
+
+After preparing an order, request its live payment challenge:
+
+```sh
+warpmetal checkout challenge --task <taskId> --json
+```
+
+On HTTP 402 the CLI returns exact `paymentTerms`, the pinned
+`@x402api/agent-wallet-cli` package contract, and argv arrays under
+`paymentWorkflow`. It also writes an owner-only request envelope that contains
+the exact checkout URL and body but no WarpMetal credential. 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. Payment authority depends on execution context:
+
+- When a human is actively chatting with the agent, show the exact live terms
+  and ask for confirmation immediately before authorizing and submitting.
+- In an unattended run, a pre-funded dedicated wallet is standing spend
+  authority, bounded by its maximum-payment policy and any task or operator
+  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:
+
+```sh
+x402api payment authorize \
+  --wallet <wallet-name> \
+  --request-envelope <path-returned-by-warpmetal> \
+  --artifact-out <path-returned-by-warpmetal> \
+  --json
+
+warpmetal checkout submit \
+  --task <taskId> \
+  --payment-artifact <owner-only-artifact-path> \
+  --wait \
+  --json
+```
+
+Check the payer wallet address and balance with:
+
+```sh
+x402api wallet address --wallet <wallet-name> --json
+x402api wallet balance --wallet <wallet-name> --json
+```
+
+If funding is short in an interactive conversation, tell the human the exact
+top-up in normal and atomic units, the network, stablecoin and contract/mint,
+and the payer wallet's public receiving address. The human sends the token to
+that wallet address, never to the token contract/mint or WarpMetal's payment
+recipient, and never sends ETH or SOL for a sponsored payment. In an unattended
+run, use a preconfigured refill or escalation mechanism or stop with
+`funding_required`.
+
+The x402api Agent Wallet is a separate, merchant-neutral executable. Install
+its matching `x402api-pay` skill with `x402api skill install --output <agent-skill-directory>/x402api-pay --json`.
+Do not use `x402api pay`, `payment submit`, or `payment reconcile` for WarpMetal:
+checkout requires the private WarpMetal owner token, so x402api authorizes and
+WarpMetal submits. WarpMetal keeps `--payment-signature-file` for another
+compatible external signer.
+
 ## Security boundary
 
 - Order and access tokens are never printed; they are written to
@@ -68,8 +138,9 @@ alternate state directory.
 - WarpMetal applies key-only OpenSSH configuration on initial provisioning and
   every OS reload. Password and keyboard-interactive login are disabled; never
   request, store, or expect a VPS login password.
-- The CLI accepts an externally produced x402 `PAYMENT-SIGNATURE` from a file.
-Wallet key management and signing remain outside this package.
+- The CLI writes x402api-compatible request envelopes and accepts validated
+  x402api payment artifacts or a compatible external `PAYMENT-SIGNATURE` file.
+  Wallet key management and signing remain outside this package.
 - Destructive or state-changing commands require explicit confirmations and
   generate idempotency keys by default.
 - Runtime bootstrap credentials remain memory-only. Signed supervisor bundles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Agent-safe CLI and skill for purchasing and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
+    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"
   },

package/skills/warpmetal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warpmetal
-description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI. Use when a shell-capable agent needs live VPS discovery, x402 ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
+description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI, including x402api Agent Wallet payment handoff. Use when a shell-capable agent needs live VPS discovery, x402 payment authorization, ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
 ---
 
 # WarpMetal
@@ -19,12 +19,15 @@ with ad hoc HTTP commands.
    authorizing payment, using an SSH identity, or changing a server.
 5. Read [references/cli-reference.md](references/cli-reference.md) when choosing
    a command or interpreting an exit code.
-6. Read [references/runtime.md](references/runtime.md) before requesting,
+6. 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,
    installing, accessing, expiring, or deleting Agent Runtime sandboxes.
 
-Never read, print, summarize, upload, or commit the WarpMetal state file. Never
-read an SSH private-key file. Pass its path only to a command designed to use
-it. Never request or handle a wallet seed phrase or private key.
+Never read, print, summarize, upload, or commit the WarpMetal state file,
+x402api keystore, password file, payment request envelope, or payment artifact.
+Never read an SSH private-key file. Pass private paths only to commands designed
+to use them. Never request or handle a wallet seed phrase or private key.
 
 WarpMetal provisions and reloads servers with key-only OpenSSH access. Password
 and keyboard-interactive login are disabled, including for root. Never request,
@@ -64,26 +67,54 @@ open the state file to retrieve the credential.
 
 ## Authorize payment
 
-Run `warpmetal checkout challenge --task <taskId> --json` to obtain the live
-x402 terms. Before any wallet creation, funding, or signature, show the user
-the exact amount, asset, network, recipient, and expiration derived from the
-live challenge and obtain explicit approval.
-
-Use a compatible external wallet signer to produce one `PAYMENT-SIGNATURE`
-header value in a file. Do not pass wallet secrets to WarpMetal or the CLI.
-After approval, submit it with:
+Run `warpmetal checkout challenge --task <taskId> --json`. The CLI validates
+the live x402 terms, writes an owner-only credential-free request envelope, and
+returns `paymentTerms` plus exact `paymentWorkflow.authorize.argv` and
+`paymentWorkflow.submit.argv` arrays. Do not reconstruct those commands or
+open either file.
+
+Determine payment authority from the current execution context. In an
+interactive conversation, show the human the exact amount, asset, network,
+recipient, profile, and maximum authorization lifetime from `paymentTerms`,
+then obtain confirmation immediately before signing and submission. In an
+unattended autonomous run, do not wait for conversational approval: treat the
+dedicated wallet's available token balance as standing spend authority, bounded
+by its maximum-payment policy and any task or operator limits. Proceed only
+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`,
+`sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false` on the chosen
+live term. Never fall back to a historical buyer-funded or TRON profile.
+
+After interactive confirmation or autonomous policy validation, invoke the
+returned authorize argv once. The separate
+`x402api` executable owns the wallet, validates the envelope, and writes the
+payment artifact. Then invoke the returned submit argv, equivalent to:
 
 ```sh
 warpmetal checkout submit \
   --task <taskId> \
-  --payment-signature-file <path> \
+  --payment-artifact <owner-only-artifact-path> \
   --wait \
   --json
 ```
 
-If the command reports a rejected signature, inspect the replacement live
-challenge and request new approval where its terms changed. If it reports
-`manual_review`, stop immediately and never create another payment.
+Do not use `x402api pay`, `x402api payment submit`, or `x402api payment
+reconcile` for this checkout. Those commands submit credential-free requests,
+but WarpMetal must add its private owner token locally.
+
+WarpMetal verifies that the artifact matches the exact saved request and an
+advertised sponsored requirement, gas reservation, resource, extensions, and
+buyer payment identifier before sending its signature. The legacy
+`--payment-signature-file` input remains available for another compatible
+external signer. If a signed request returns a replacement challenge, use the
+new CLI-produced workflow and re-evaluate payment authority. Ask again when a
+human is chatting and the terms changed; in an unattended run, proceed only if
+the replacement remains within standing authority. On `manual_review` or an
+ambiguous attempt, stop and never create another payment.
 
 ## Provision and manage
 

package/skills/warpmetal/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "WarpMetal VPS"
-  short_description: "Manage WarpMetal VPS and agent sandboxes safely"
-  default_prompt: "Use $warpmetal to provision a VPS and manage isolated agent sandboxes safely."
+  short_description: "Purchase and manage WarpMetal compute safely"
+  default_prompt: "Use $warpmetal to purchase a VPS through the guarded x402 wallet handoff and manage isolated agent sandboxes safely."

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

@@ -33,11 +33,14 @@ warpmetal order prepare \
   [--idempotency-key <key>] \
   --json
 
-warpmetal checkout challenge --task <taskId> --json
+warpmetal checkout challenge \
+  --task <taskId> \
+  [--request-envelope-out <path>] \
+  --json
 
 warpmetal checkout submit \
   --task <taskId> \
-  --payment-signature-file <path> \
+  (--payment-artifact <path> | --payment-signature-file <path>) \
   [--wait] [--timeout-seconds <n>] \
   --json
 
@@ -47,8 +50,29 @@ warpmetal order status \
   --json
 ```
 
-The payment signature file must contain one HTTP header value. The CLI does
-not create or store wallet keys and does not sign x402 challenges.
+On HTTP 402, `checkout challenge` validates and displays exact payment terms,
+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
+private WarpMetal state directory. An explicit output path must not already
+contain different content.
+
+The current integration targets `@x402api/agent-wallet-cli@0.2.1`. 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.
+WarpMetal rejects a challenge with no compatible sponsored term. Because the
+checkout is authenticated, do not substitute `x402api pay`, `payment submit`,
+or `payment reconcile` for the returned WarpMetal submission command.
+
+`--payment-artifact` accepts the owner-only JSON artifact produced by a
+compatible pinned x402api Agent Wallet release. WarpMetal validates its request
+and payment-requirement digests, resource, extensions, buyer payment identifier,
+signature, sponsorship expiry, file type, and permissions before submission.
+It reports only safe attempt metadata. The compatibility
+`--payment-signature-file` input must contain one HTTP header value. WarpMetal
+never creates, imports, reads, or stores wallet keys and does not sign x402
+challenges itself. See [payments.md](payments.md).
 
 ## Server management
 

package/skills/warpmetal/references/payments.md

@@ -0,0 +1,136 @@
+# WarpMetal payment workflow
+
+## Contents
+
+- Trust boundary
+- Wallet setup and funding
+- Exact purchase workflow
+- Retries and recovery
+
+## Trust boundary
+
+WarpMetal is the merchant tool. It owns product selection, the private owner
+credential, exact checkout bytes, submission, provisioning, and fulfillment.
+The separate x402api Agent Wallet owns encrypted network keys, balance checks,
+payment authorization, and durable payment attempts. Never merge their state
+files or pass a WarpMetal credential to `x402api`.
+
+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.1`. Do not add it as a WarpMetal dependency,
+install executable wallet code from an unpinned repository URL, or substitute
+a similarly named package.
+
+The wallet package ships its own version-matched `x402api-pay` skill. Install
+that skill into the directory used by Codex, Claude Code, or another portable
+Agent Skills runtime with the returned `paymentWorkflow.walletSkill.install.argv`.
+The command refuses to overwrite an existing directory; do not delete an old
+skill automatically.
+
+## Wallet setup and funding
+
+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
+   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
+   already permits it and a secure password source is configured; otherwise
+   reuse a preconfigured wallet or stop. Keep Base and Solana wallets separate;
+   never import the owner's primary seed or key. TRON wallet management exists,
+   but the published launch payer cannot authorize TRON.
+5. Use both public, safe commands before requesting funding:
+
+   ```sh
+   x402api wallet address --wallet <name> --json
+   x402api wallet balance --wallet <name> --json
+   ```
+
+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. Tell the
+   human to transfer the token to the payer wallet address, never to the token
+   contract/mint or `paymentTerms.recipient`. Sponsored launch payments never
+   ask the buyer to fund ETH or SOL. Recheck the balance after the transfer.
+7. If funding is short in an unattended run, use only a preconfigured refill
+   or escalation mechanism. Otherwise report `funding_required` and stop; do
+   not invent a human approval step or funding source.
+
+Treat the dedicated wallet's funded balance as spend authority available to
+the agent, bounded by any wallet-local maximum payment policy and task or
+operator limits. When a human is actively chatting, disclose the exact live
+terms and obtain confirmation immediately before payment. In an unattended
+run, do not wait for conversational approval; authorize and submit
+autonomously when the terms fit the standing authority.
+
+Use this structure when asking a human to fund the wallet:
+
+> Transfer exactly `<amount> <USDC-or-USDT>` on `<Base-or-Solana>` to the agent
+> wallet `<payer-wallet-address>`. Token contract/mint: `<asset-identifier>`.
+> Send the token to the payer wallet address, not to the token contract/mint and
+> not to WarpMetal's payment recipient. Do not send ETH or SOL; the network fee
+> is sponsored.
+
+## Exact purchase workflow
+
+```sh
+warpmetal checkout challenge --task <taskId> --json
+```
+
+Read only the returned safe JSON. Confirm `paymentTerms`, then use the exact
+argv arrays returned under `paymentWorkflow`:
+
+```text
+paymentWorkflow.authorize.argv
+  x402api payment authorize --wallet <wallet-name>
+    --request-envelope <owner-only-request-path>
+    --artifact-out <owner-only-artifact-path> --json
+
+paymentWorkflow.submit.argv
+  warpmetal checkout submit --task <taskId>
+    --payment-artifact <owner-only-artifact-path> --wait --json
+```
+
+Replace only `<wallet-name>` after selecting the wallet for the advertised
+network. Do not parse, rewrite, copy, or display the request envelope or payment
+artifact. The envelope excludes the WarpMetal owner token; the artifact holds
+the complete payment signature and remains owner-only.
+
+Choose only a term marked `agentWalletSupported: true`,
+`sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false`. The supported
+launch profiles are sponsored Base USDC and sponsored Solana USDC/USDT, bound
+by the strict `com.x402api.gas-sponsorship` extension. Stop on an expired gas
+reservation or any buyer-funded, unsupported, or unbound alternative.
+
+Do not replace the two-stage workflow with `x402api pay`, `payment submit`, or
+`payment reconcile`. Those wallet commands can submit an exact credential-free
+endpoint; WarpMetal checkout requires a private owner token that must never
+enter the wallet envelope. Use x402api only for authorization and WarpMetal for
+submission and merchant reconciliation.
+
+WarpMetal rejects an artifact whose request digest, selected payment
+requirement, resource, extension set, buyer payment identifier, signature,
+expiry, sponsorship lifetime, file type, or permissions do not match the saved
+challenge. Keep `--payment-signature-file` only as a compatibility path for
+another external signer.
+
+## Retries and recovery
+
+- `payment_pending` or `payment_finalizing`: keep the same checkout bytes and
+  artifact. `--wait` performs bounded retries with that exact authorization.
+- Timeout or process restart after authorization: use the saved x402api attempt
+  ID and artifact. Reconcile with WarpMetal and reuse its submit argv. Never
+  authorize again merely because submission is unknown.
+- Signed HTTP 402: the artifact was definitively rejected. Run the WarpMetal
+  challenge flow again, inspect the replacement terms, and authorize one new
+  artifact only when the protocol and current interactive or autonomous
+  payment authority allow it.
+- `manual_review`: payment or fulfillment may be final. Stop all payment and
+  mutation retries.
+- Expired or corrupt artifact, changed request digest, unexpected recipient,
+  unsupported network, asset, profile, sponsorship error, or request-binding
+  mismatch: stop instead of falling back or asking the buyer to fund ETH/SOL.

package/skills/warpmetal/references/runtime.md

@@ -44,7 +44,7 @@ fields `name`, `size`, optional `lifetime`, and optional `expiresInSeconds`:
 
 Pass it to `warpmetal order prepare --runtime-file <path>`. If it contains a
 temporary sandbox, pass `--confirm TEMPORARY`. Preparing remains unpaid; keep
-the existing separate payment approval.
+the existing separate interactive-or-autonomous payment authority check.
 
 For an existing ready server:
 

package/skills/warpmetal/references/safety.md

@@ -34,12 +34,20 @@
 - Give each agent a distinct sandbox-specific SSH key and grant. Never reuse
   the owner host key or one agent key across multiple sandboxes.
 - Never request, read, transmit, or store a wallet seed phrase or private key.
-- Never put a token, payment signature, private key, or state-file content in
-  a prompt, URL, log, screenshot, source file, or shell argument.
+- 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.
+- 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.
+- Never put a token, payment signature, payment artifact, wallet password,
+  private key, or state-file content in a prompt, URL, log, screenshot, source
+  file, or shell argument.
 
-## Required confirmations
+## Interactive confirmations and autonomous payment authority
 
-Obtain explicit user approval immediately before:
+When a human is actively directing the current task in a conversation, obtain
+explicit approval immediately before:
 
 - installing the CLI or skill;
 - installing or repairing the Agent Runtime supervisor;
@@ -51,6 +59,16 @@ Obtain explicit user approval immediately before:
 - revoking a sandbox access grant; and
 - any destructive reload, sandbox deletion, or replacement-key operation.
 
+In an unattended autonomous run, do not pause payment for conversational
+approval. A pre-funded dedicated wallet provides standing spend authority,
+bounded by its maximum-payment policy and any task or operator limits. Sign and
+submit only when the exact live amount, asset, network, recipient, profile,
+resource binding, and sponsorship fit those limits. Unattended mode does not
+grant unlimited spend, permission to import a primary wallet, or permission to
+use unsupported or buyer-funded payment rails. If the wallet is short and no
+preconfigured refill or escalation mechanism exists, report
+`funding_required` and stop.
+
 A reload requires both `confirm: "ERASE"` and `powerOffFirst: true`. Treat
 `powerOffFirst` as explicit authorization for WarpMetal to shut down the
 server, wait until it is powered off, and then erase and reinstall it inside
@@ -71,9 +89,14 @@ Confirm the plan, hostname, OS, and public key before preparing it.
 
 - Reuse the same idempotency key only for the exact same logical request.
 - For `payment_pending`, retry the exact checkout body and the exact same
-  payment signature. Do not create a replacement payment.
+  payment artifact. Do not create a replacement payment.
 - A signed HTTP 402 rejects that signature. Use the new live challenge for one
-  replacement authorization.
+  replacement authorization after checking the new terms against the current
+  interactive or autonomous payment authority.
+- On timeout or restart after wallet authorization, reuse the saved x402api
+  attempt and artifact through WarpMetal. Never authorize again merely because
+  submission or fulfillment is uncertain, and never send the private owner
+  token through `x402api pay`, `payment submit`, or `payment reconcile`.
 - Treat `manual_review` as terminal. Do not pay again and do not repeat the
   mutation.
 - Treat HTTP 202 as accepted or pending, never as proof of success. Poll the