warpmetal 0.7.5 → 0.7.6

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.6
+npm install --global @x402api/agent-wallet-cli@0.2.7
 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.5 or newer.
+artifact from the npm CLI and requires `warpmetal` CLI version 0.7.6 or newer.
 
 To test the repository marketplace after the plugin lands on `main`:
 

package/package.json

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

package/skills/warpmetal/SKILL.md

@@ -11,7 +11,7 @@ with ad hoc HTTP commands.
 
 ## Start safely
 
-1. Run `warpmetal --version` and require version `0.7.5` or newer for this
+1. Run `warpmetal --version` and require version `0.7.6` 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`.

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

@@ -69,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.6`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.7`. 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.6`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.7`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -149,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.6
+tenant debit. During the coordinated rollout, accept only the exact 0.2.7
 platform-treasury declaration or the matched legacy tenant-credit declaration;
 never accept a mixed billing and final-charge policy.
 
@@ -191,12 +191,13 @@ current `termEndsAt` generation are different.
   terms and authorize only the new workflow; never reuse an expired envelope or
   artifact.
 - `payment_pending` or `payment_finalizing`: keep the same checkout bytes and
-  artifact. `--wait` performs bounded retries with that exact authorization.
+  artifact. Preserve the returned durable `paymentId`; `--wait` records it in
+  private WarpMetal state and 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
+- Signed HTTP 402: the artifact was definitively rejected. Preserve its
+  `paymentId`, then 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.
 - `sponsorship_allowance_unavailable`, `sponsorship_payment_cap_exceeded`,

package/skills/warpmetal/references/safety.md

@@ -115,9 +115,10 @@ Confirm the plan, hostname, OS, and public key before preparing it.
   replaces its saved challenge metadata. Re-evaluate the new terms before
   authorization; never sign or submit the expired challenge.
 - For `payment_pending`, retry the exact checkout body and the exact same
-  payment artifact. Do not create a replacement payment.
-- A signed HTTP 402 rejects that signature. Use the new live challenge for one
-  replacement authorization after checking the new terms against the current
+  payment artifact. Preserve the returned `paymentId` as the durable x402api
+  reconciliation key. Do not create a replacement payment.
+- A signed HTTP 402 rejects that signature. Preserve its `paymentId`, request a
+  new live challenge, and create one replacement authorization after checking the new terms against the current
   interactive or autonomous payment authority.
 - Treat `sponsorship_allowance_unavailable`,
   `sponsorship_payment_cap_exceeded`,

package/src/cli.js

@@ -379,13 +379,18 @@ async function pollGrant(
   }
 }
 
-function challengeResult(taskId, checkoutBody, response) {
+function challengeResult(
+  taskId,
+  checkoutBody,
+  response,
+  { requireChallenge = true } = {},
+) {
   const paymentRequired = response.headers["payment-required"];
   const challengeHandle = response.headers["x-x402api-challenge-handle"];
-  if (response.status === 402 && !paymentRequired) {
+  if (requireChallenge && response.status === 402 && !paymentRequired) {
     throw new CliError("WarpMetal returned HTTP 402 without PAYMENT-REQUIRED.");
   }
-  if (response.status === 402 && !challengeHandle) {
+  if (requireChallenge && response.status === 402 && !challengeHandle) {
     throw new CliError(
       "WarpMetal returned HTTP 402 without X-X402API-Challenge-Handle.",
     );
@@ -736,12 +741,17 @@ async function handleCheckoutSubmit(client, store, options, context) {
       token,
       paymentSignature,
     });
+    if (response.data?.paymentId) {
+      await store.saveOrderPaymentId(taskId, response.data.paymentId);
+    }
     const safe = await attachPaymentWorkflow(
       client,
       store,
       taskId,
       order,
-      challengeResult(taskId, order.checkoutBody, response),
+      challengeResult(taskId, order.checkoutBody, response, {
+        requireChallenge: false,
+      }),
     );
     const retryable =
       response.status === 202 &&
@@ -755,6 +765,7 @@ async function handleCheckoutSubmit(client, store, options, context) {
     const output = {
       ...safe,
       task: response.data?.task,
+      paymentId: response.data?.paymentId,
       message: response.data?.message,
       ...(walletPayment
         ? {
@@ -1327,6 +1338,9 @@ async function handleRenewalSubmit(client, store, options, context) {
         paymentSignature: walletPayment.paymentSignature,
       },
     );
+    if (response.data?.paymentId) {
+      await store.saveRenewalPaymentId(serverId, response.data.paymentId);
+    }
     const retryable =
       response.status === 202 &&
       ["payment_pending", "payment_finalizing"].includes(response.data?.status);
@@ -1339,6 +1353,7 @@ async function handleRenewalSubmit(client, store, options, context) {
       status: response.data?.status,
       serverId,
       task: response.data?.task,
+      paymentId: response.data?.paymentId,
       paymentAttemptId:
         response.data?.paymentAttemptId ||
         response.headers["x-warpmetal-payment-attempt"],

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.6";
+export const AGENT_WALLET_VERSION = "0.2.7";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";

package/src/state.js

@@ -13,7 +13,10 @@ const WALLET_PAYMENT_STATE_FIELDS = [
   "walletPayerAddress",
   "paymentArtifactExpiresAt",
   "paymentArtifactSavedAt",
+  "gatewayPaymentId",
 ];
+const X402API_PAYMENT_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 function replaceChallenge(record, challenge) {
   const changed =
@@ -361,6 +364,50 @@ export class StateStore {
     });
   }
 
+  async saveOrderPaymentId(taskId, paymentId) {
+    if (!X402API_PAYMENT_ID.test(paymentId || "")) {
+      throw new CliError("WarpMetal returned an invalid x402api payment ID.", {
+        exitCode: 3,
+      });
+    }
+    await this.update((state) => {
+      const order = state.orders[taskId];
+      if (!order) {
+        throw new CliError(`No local order state exists for ${taskId}.`, {
+          exitCode: 2,
+        });
+      }
+      if (order.gatewayPaymentId && order.gatewayPaymentId !== paymentId) {
+        throw new CliError("WarpMetal changed the x402api payment ID for this attempt.", {
+          exitCode: 3,
+        });
+      }
+      order.gatewayPaymentId = paymentId;
+    });
+  }
+
+  async saveRenewalPaymentId(serverId, paymentId) {
+    if (!X402API_PAYMENT_ID.test(paymentId || "")) {
+      throw new CliError("WarpMetal returned an invalid x402api payment ID.", {
+        exitCode: 3,
+      });
+    }
+    await this.update((state) => {
+      const renewal = state.renewals[serverId];
+      if (!renewal) {
+        throw new CliError(`No local renewal state exists for ${serverId}.`, {
+          exitCode: 2,
+        });
+      }
+      if (renewal.gatewayPaymentId && renewal.gatewayPaymentId !== paymentId) {
+        throw new CliError("WarpMetal changed the x402api payment ID for this renewal.", {
+          exitCode: 3,
+        });
+      }
+      renewal.gatewayPaymentId = paymentId;
+    });
+  }
+
   async saveAccessToken(serverId, accessToken, expiresAt) {
     await this.update((state) => {
       const server = state.servers[serverId] || { serverId };
@@ -488,6 +535,7 @@ export class StateStore {
         serverId: order.serverId,
         planId: order.planId,
         paymentAttemptId: order.paymentAttemptId,
+        paymentId: order.gatewayPaymentId,
         challengeHandle: order.challengeHandle,
         walletPaymentAttemptId: order.walletPaymentAttemptId,
         walletName: order.walletName,
@@ -523,6 +571,7 @@ export class StateStore {
         refillTargetAtomic: renewal.refillTargetAtomic,
         policy: renewal.policy,
         paymentAttemptId: renewal.paymentAttemptId,
+        paymentId: renewal.gatewayPaymentId,
         challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
       })),