warpmetal 0.8.4 → 0.8.6

package/README.md

@@ -141,6 +141,18 @@ confirmation is pending. As soon as `confirmed` is true, stop all payment
 submission—even when `finalized` is false—and let WarpMetal continue signed-
 receipt finality while provisioning or renewal proceeds.
 
+For an interactive initial purchase, `checkout challenge` may also return a
+short-lived `humanCheckout` object. Its `url` and `qrPayload` are the same
+`https://pay.x402api.com/c/...` bearer capability for the exact charge; encode
+that URL as the QR, never the WarpMetal recipient address. The buyer connects
+their own wallet and needs only the advertised USDC/USDT balance because
+x402api sponsors the native gas. This is an alternative to the agent-wallet
+workflow, not a second payment. After browser payment, run the exact
+`humanCheckout.afterPayment.argv` status command. When the ready result asks
+for `ask_human_for_notification_email`, ask the owner and add the optional
+lifecycle-notification address they provide. Autonomous purchases and renewals
+continue to use the bounded agent-wallet path.
+
 - 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

package/package.json

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

package/skills/warpmetal/SKILL.md

@@ -88,6 +88,18 @@ returns `paymentTerms` plus exact `paymentWorkflow.authorize.argv` and
 `paymentWorkflow.submit.argv` arrays. Do not reconstruct those commands or
 open either file.
 
+In an interactive initial purchase, the result may also contain
+`humanCheckout`. Offer it as an alternative to the local agent wallet. Show
+`humanCheckout.url` as clickable text and render only the identical
+`humanCheckout.qrPayload` URL as the purchase QR; never render the recipient
+address as this QR. The URL is an expiring bearer capability, so do not log,
+save, or send it anywhere except to the buyer who requested this purchase. If
+the buyer uses it, do not authorize or submit through the agent wallet. Run the
+exact `humanCheckout.afterPayment.argv` command, wait for the server to become
+ready, then follow `ask_human_for_notification_email`: ask the owner for the
+optional lifecycle-notification address and add only the address they provide.
+Ignore this path in unattended purchasing and renewal automation.
+
 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`,

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

@@ -72,6 +72,15 @@ 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.
 
+For interactive initial purchases, the response may additionally include
+`humanCheckout.url`, the identical `qrPayload`, `expiresAt`, and an exact
+`afterPayment.argv` command. The URL is a short-lived bearer capability for the
+same charge, not a recipient address. If the buyer pays in the hosted checkout,
+do not submit an agent-wallet artifact; run the returned status command and,
+after ready, follow `ask_human_for_notification_email` to offer lifecycle
+notices. The CLI does not persist the hosted URL. Renewal commands never expose
+or use this interactive option.
+
 The current integration targets `@x402api/agent-wallet-cli@0.2.9`. 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.

package/skills/warpmetal/references/payments.md

@@ -123,6 +123,16 @@ warpmetal checkout challenge --task <taskId> --json
 Read only the returned safe JSON. Confirm `paymentTerms`, then use the exact
 argv arrays returned under `paymentWorkflow`:
 
+For an interactive initial purchase, an optional `humanCheckout` object offers
+a second presentation path for the same charge. Its `url` and `qrPayload` must
+be identical hosted-checkout URLs; render that URL as the QR and copyable link,
+never a recipient address. If the buyer completes this path, skip agent-wallet
+authorization and run `humanCheckout.afterPayment.argv`. Continue bounded
+status polling until ready, then ask for the optional lifecycle-notification
+email when the result returns `ask_human_for_notification_email`. The hosted
+URL expires at `humanCheckout.expiresAt`, is not persisted by the CLI, and is
+never used for unattended purchases or renewals.
+
 ```text
 paymentWorkflow.authorize.argv
   x402api payment authorize --wallet <wallet-name>

package/src/cli.js

@@ -427,7 +427,11 @@ function challengeResult(
   taskId,
   checkoutBody,
   response,
-  { requireChallenge = true } = {},
+  {
+    requireChallenge = true,
+    allowHumanCheckout = false,
+    humanCheckoutContext = undefined,
+  } = {},
 ) {
   const status = response.data?.status;
   const rejected = response.status === 402 && status === "payment_rejected";
@@ -459,6 +463,13 @@ function challengeResult(
       "WarpMetal returned PAYMENT-REQUIRED without X-X402API-Challenge-Digest.",
     );
   }
+  const humanCheckout = allowHumanCheckout
+    ? humanCheckoutResult(
+        response.data?.humanCheckout,
+        taskId,
+        humanCheckoutContext,
+      )
+    : undefined;
   return {
     status,
     taskId,
@@ -469,6 +480,7 @@ function challengeResult(
     challengeHandle,
     challengeDigest,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
+    ...(humanCheckout ? { humanCheckout } : {}),
     ...(rejected
       ? {
           errorCode: response.data?.errorCode,
@@ -479,6 +491,74 @@ function challengeResult(
   };
 }
 
+function humanCheckoutResult(value, taskId, { baseUrl, stateDirectory } = {}) {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  const keys = Object.keys(value).sort();
+  if (keys.join(",") !== "expiresAt,qrPayload,url") {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  if (
+    typeof value.url !== "string" ||
+    typeof value.qrPayload !== "string" ||
+    value.url !== value.qrPayload ||
+    typeof value.expiresAt !== "string"
+  ) {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  let url;
+  try {
+    url = new URL(value.url);
+  } catch {
+    throw new CliError("WarpMetal returned an invalid hosted checkout URL.");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.origin !== "https://pay.x402api.com" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !/^\/c\/chk_[A-Za-z0-9_-]{32}$/.test(url.pathname) ||
+    url.toString() !== value.url
+  ) {
+    throw new CliError("WarpMetal returned an invalid hosted checkout URL.");
+  }
+  const rfc3339 =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+  const expiresAt = Date.parse(value.expiresAt);
+  if (
+    !rfc3339.test(value.expiresAt) ||
+    !Number.isFinite(expiresAt) ||
+    expiresAt <= Date.now()
+  ) {
+    throw new CliError(
+      "WarpMetal returned an invalid or expired hosted checkout expiry.",
+    );
+  }
+  return {
+    url: value.url,
+    qrPayload: value.qrPayload,
+    expiresAt: value.expiresAt,
+    afterPayment: {
+      argv: [
+        "warpmetal",
+        "order",
+        "status",
+        "--task",
+        taskId,
+        "--wait",
+        ...(baseUrl ? ["--base-url", baseUrl] : []),
+        ...(stateDirectory ? ["--state-dir", stateDirectory] : []),
+        "--json",
+      ],
+      notificationNextAction: "ask_human_for_notification_email",
+    },
+  };
+}
+
 async function attachPaymentWorkflow(
   client,
   store,
@@ -517,7 +597,8 @@ async function attachPaymentWorkflow(
     paymentChallengeDigest: request.challengeDigest,
     paymentWorkflow: workflow,
   });
-  await store.savePaymentChallenge(taskId, safe);
+  const { humanCheckout: _ephemeralHostedCheckout, ...persisted } = safe;
+  await store.savePaymentChallenge(taskId, persisted);
   return safe;
 }
 
@@ -773,9 +854,20 @@ async function handleCheckoutChallenge(client, store, options, context) {
     store,
     taskId,
     order,
-    challengeResult(taskId, order.checkoutBody, response),
+    challengeResult(taskId, order.checkoutBody, response, {
+      // Initial checkout is the only interactive direct-payment surface.
+      // Autonomous renewal continues to use the bounded agent-wallet policy.
+      allowHumanCheckout: true,
+      humanCheckoutContext: {
+        baseUrl: client.baseUrl,
+        stateDirectory: store.directory,
+      },
+    }),
     stringOption(options, "request-envelope-out"),
   );
+  const directCheckoutInstructions = safe.humanCheckout
+    ? `\nDirect wallet checkout (optional, expires ${safe.humanCheckout.expiresAt}): ${safe.humanCheckout.url}\nEncode only that URL as the purchase QR. After payment, continue with: ${shellCommand(safe.humanCheckout.afterPayment.argv)}. When provisioning is ready, ask the owner for the optional lifecycle-notification email before adding it.`
+    : "";
   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)}\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)}`
     : "";
@@ -784,7 +876,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     safe,
     context.json,
     response.status === 402
-      ? `Payment authorization required for ${taskId}.${paymentInstructions}`
+      ? `Payment authorization required for ${taskId}.${directCheckoutInstructions}${paymentInstructions}`
       : `Checkout status for ${taskId}: ${safe.status}`,
   );
   return response.status === 409 ? 6 : response.status === 402 ? 7 : 0;

package/src/installer.js

@@ -123,6 +123,14 @@ function validateArtifact(artifact) {
   return { ...artifact, url: url.toString() };
 }
 
+function serverAllowsRuntimeInstall(server, currentTime = Date.now()) {
+  if (!server?.publicIp) return false;
+  if (server.state === "ready") return true;
+  if (!["cancellation_pending", "cancelled"].includes(server.state)) return false;
+  const termEndsAt = Date.parse(server.termEndsAt || "");
+  return Number.isFinite(termEndsAt) && termEndsAt > currentTime;
+}
+
 export function verifyRuntimeArtifact(content, metadata) {
   const artifact = validateArtifact(metadata);
   const digest = createHash("sha256").update(content).digest("hex");
@@ -270,8 +278,8 @@ export async function installRuntime({
     throw new CliError("The server ID is invalid.", { exitCode: 2 });
   }
   const server = (await client.getServer(serverId, token)).data?.task;
-  if (server?.state !== "ready" || !server.publicIp) {
-    throw new CliError("The VPS must be ready before runtime installation.", {
+  if (!serverAllowsRuntimeInstall(server)) {
+    throw new CliError("The VPS must be ready and within its active paid term before runtime installation.", {
       exitCode: 5,
     });
   }