warpmetal 0.3.0 → 0.4.0

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,44 @@ 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. After inspecting the terms and approving payment,
+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
+```
+
+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 +115,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
@@ -82,9 +130,10 @@ Wallet key management and signing remain outside this package.
   delete their workspace after 15 minutes to 24 hours.
 - Guarded reload powers the server off first. Runtime-enabled reload requires a
   second acknowledgment, after which the CLI guides supervisor reinstall and
-  pinned connection-profile refresh. Replacement owner SSH host keys must be
-  verified before updating `known_hosts`; erased workspaces are never described
-  as recoverable.
+  pinned connection-profile refresh. Post-reload owner SSH host keys must be
+  independently verified because the provider may rotate or preserve them;
+  update `known_hosts` only when the verified key changed. Erased workspaces
+  are never described as recoverable.
 
 ## Agent Runtime example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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,44 @@ 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.
+
+Show the user the exact amount, asset, network, recipient, profile, and maximum
+authorization lifetime from `paymentTerms`; obtain explicit approval before
+signing or submission. 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 approval, 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 request approval again when terms changed. On
+`manual_review` or an ambiguous attempt, stop and never create another payment.
 
 ## Provision and manage
 
@@ -137,11 +158,12 @@ warpmetal server reload \
 
 The CLI requires the recovery owner credential so it can keep polling after
 reload revokes SSH-derived access tokens. On success, reinstall Agent Runtime
-only after verifying the replacement owner-facing SSH host-key fingerprint
-through a trusted provider or console channel and safely updating
-`known_hosts`. Never bypass a mismatch. Then wait for grants to become applied and refresh every
-connection profile with `sandbox access refresh --confirm REFRESH` before
-connecting. Do not fall back to raw API calls for deletion, networking,
+only after verifying the post-reload owner-facing SSH host-key fingerprint
+through a trusted provider or console channel. The provider may rotate or
+preserve the key; update `known_hosts` only when the verified key changed and
+never bypass a mismatch. Then wait for grants to become applied and refresh
+every connection profile with `sandbox access refresh --confirm REFRESH`
+before connecting. Do not fall back to raw API calls for deletion, networking,
 renewal, or another unsupported mutation.
 
 ## Use Agent Runtime

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,110 @@
+# 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. Create a wallet only with explicit approval. 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 `x402api wallet balance --wallet <name> --json`. If funding is short,
+   show the public address, exact network, token, and atomic deficit. The owner
+   funds the token address from a wallet they control. Sponsored launch
+   payments never ask the buyer to fund ETH or SOL.
+
+Treat the dedicated wallet's funded balance as spend authority available to
+the agent, bounded by any wallet-local maximum payment policy. WarpMetal still
+requires explicit approval immediately before its payment authorization and
+submission workflow.
+
+## 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 approval 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/safety.md

@@ -34,8 +34,15 @@
 - 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
 
@@ -58,9 +65,11 @@ one lifecycle operation. When Agent Runtime is enabled, also require
 `acknowledgeAgentRuntimeReset`: all sandbox workspaces are permanently erased,
 the supervisor identity is revoked, desired sandboxes are recreated empty
 after reinstall, and all pinned profiles require refresh. Use only the guarded
-CLI command and stop on `manual_review`. Reload also replaces the owner-facing
-SSH host key; verify its fingerprint through a trusted provider or console
-channel before changing `known_hosts`, and never disable host-key checking.
+CLI command and stop on `manual_review`. Reload invalidates the prior
+owner-facing SSH host-key trust decision; the provider may rotate or preserve
+the key. Verify the post-reload fingerprint through a trusted provider or
+console channel, change `known_hosts` only when the verified key changed, and
+never disable host-key checking.
 
 An order preparation is unpaid but consumes a limited prepared-order slot.
 Confirm the plan, hostname, OS, and public key before preparing it.
@@ -69,9 +78,13 @@ 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 and approval.
+- 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