@itpay/cli 0.2.4 → 0.2.5

package/README.md

@@ -239,7 +239,8 @@ Payment QR rules:
 - Otherwise render the ItPay-hosted `qr_png_url` / `preferred_qr_url`.
 - Use `mobile_wallet_url` only as a human mobile fallback.
 - Do not generate your own QR from payment URLs.
-- In agent app clients, send `human_visible_markdown` to the human first, then run `next.command`.
+- In agent app clients, send `human_visible_markdown` to the human first, then run `after_human_visible_markdown.command`.
+- If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 
 If the human wants the agent to analyze delivered content, the human must reveal

package/docs/agent/buyer/cart-checkout.json

@@ -69,7 +69,7 @@
     {
       "intent": "do both steps through the high-level command",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status is waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+      "success_signal": "response.status is waiting_human_auth, payment_handoff_required, payment_verified, or delivery_claimable"
     }
   ],
   "agent_rules": [

package/docs/agent/buyer/payment-qr.json

@@ -18,7 +18,7 @@
     {
       "intent": "create payment intent through the high-level buy flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.human_visible_markdown and response.next.command are present"
+      "success_signal": "response.status is payment_handoff_required; response.human_visible_markdown is present; response.after_human_visible_markdown.command is the wait command to run after showing the QR/link"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,8 +33,9 @@
     "Payment QR display requires both a valid/saved buyer session and payment_intent_id. If payment_intent_id appears before buyer_session is saved, run buyer checkout resume/status instead of showing payment QR.",
     "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
     "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
-    "In Codex or Claude Code app clients, the default UX is show-then-wait: send response.human_visible_markdown to the human first, then run response.next.command.",
+    "In Codex or Claude Code app clients, the default UX is show-then-wait: send response.human_visible_markdown to the human first, then run response.after_human_visible_markdown.command.",
     "For Telegram-style message clients, show response.human_visible_markdown and stop unless the human asks you to keep waiting or returns with a payment question.",
+    "When response.status is payment_handoff_required, response.next is the human reply step, not payment wait.",
     "MUST show local_qr_path first when present. Many agent clients do not reliably render remote QR images; local_qr_path is the most reliable desktop/chat display artifact.",
     "If local_qr_path is not present, show qr_png_url or preferred_qr_url as the primary scannable QR. This is an ItPay-hosted human QR image; it may render the native provider payment code for scanner reliability, but the agent must not request or decode the raw provider payload.",
     "Use qr_image_url/SVG only as a fallback when PNG/local rendering is unavailable.",
@@ -42,8 +43,8 @@
     "payment_entry_url is the stable ItPay status/payment page. qr_png_url/local_qr_path is usually the better desktop scanner artifact.",
     "The provider can briefly show order not found even after precreate succeeded. Tell the human to wait 30-60 seconds and retry the same QR/page. Do not create a new checkout, do not create a new payment intent, and do not repeatedly refresh unless the ItPay page or CLI explicitly asks for recovery.",
     "Opening the payment page must not be treated as paid.",
-    "Do not run payment wait before the QR/link has been sent to the human.",
-    "After showing QR, run next.command or buyer payment wait for the same payment_intent_id."
+    "Do not run payment wait before the QR/link has been sent to the human. If you accidentally do, CLI returns payment_handoff_required instead of blocking.",
+    "After showing QR, run after_human_visible_markdown.command or buyer payment wait <payment_intent_id> --qr-shown for the same payment_intent_id."
   ],
   "forbidden": [
     "Do not encode payment_entry_url into a new QR yourself when qr_png_url/local_qr_path is available.",

package/docs/agent/buyer/payment-wait.json

@@ -17,7 +17,7 @@
   "commands": [
     {
       "intent": "wait for payment verified event",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --qr-shown --json",
       "success_signal": "response.payment_event.event_type == payment_intent.verified"
     },
     {
@@ -27,7 +27,8 @@
     }
   ],
   "agent_rules": [
-    "Start payment wait only after the QR image/link has already been sent to the human.",
+    "Start payment wait only after the QR image/link has already been sent to the human; use --qr-shown to confirm that step is complete.",
+    "If you run payment wait without --qr-shown while payment is still pending, CLI returns payment_handoff_required and human_visible_markdown instead of long-polling.",
     "Payment wait is a recovery loop around the same payment_intent_id, not a one-shot command.",
     "wait.timeout is a heartbeat, not a payment failure.",
     "In Codex or Claude Code app clients, after showing QR, wait online for a short visible cycle first. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",

package/docs/agent/buyer/quickstart.json

@@ -37,7 +37,7 @@
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status becomes waiting_human_auth or waiting_user_payment; if waiting_user_payment, response.human_visible_markdown and response.next.command are present"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if payment_handoff_required, send response.human_visible_markdown to the human before running response.after_human_visible_markdown.command"
     }
   ],
   "agent_rules": [
@@ -54,8 +54,9 @@
     "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
     "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
     "Vault grants are only for reading approved delivered artifacts. They are not buyer session credentials and do not authorize refunds or account/order management.",
-    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown, then run next.command.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown, then run after_human_visible_markdown.command.",
     "If response.human_visible_markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the QR/link is visible may you run after_human_visible_markdown.command.",
     "Show the returned payment QR exactly as provided before starting payment wait.",
     "Payment truth comes only from payment_intent.verified.",
     "Secure delivery goes to the human first; report redacted delivery status only."

package/lib/buyer.js

@@ -45,18 +45,15 @@ async function buyerBuy(flags) {
 
   if (flags.no_wait || flags.no_wait_payment || showThenWait) {
     output(buyerRunOutput({
-      status: "waiting_user_payment",
+      status: "payment_handoff_required",
       selection,
       cart,
       checkout,
       payment_intent: intent,
       payment_handoff: paymentHandoff(intent),
-      agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-      next: {
-        command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-        safe_for_agent: true,
-        instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-      }
+      agent_next_actions: paymentHandoffAgentNextActions(),
+      next: paymentHandoffNext(),
+      after_human_visible_markdown: paymentHandoffAfter(intent)
     }));
     return;
   }
@@ -317,19 +314,16 @@ async function buyer(command, rest, flags) {
           const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
           await renderItPayPaymentAction(intent, flags);
           output(buyerRunOutput({
-            status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
+            status: intent.status === "verified" ? "payment_verified" : "payment_handoff_required",
             checkout,
             payment_intent: intent,
             payment_handoff: intent.status === "verified" ? undefined : paymentHandoff(intent),
             buyer_session: buyerSessionClaimStatus(claimedSession),
-            agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"],
+            agent_next_actions: intent.status === "verified" ? (intent.agent_next_actions || checkout.agent_next_actions || ["poll_checkout"]) : paymentHandoffAgentNextActions(),
             next: intent.status === "verified"
               ? { command: cliCommand("buyer", "checkout", "status", checkout.checkout_id, "--json"), safe_for_agent: true }
-              : {
-                command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-                safe_for_agent: true,
-                instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-              }
+              : paymentHandoffNext(),
+            after_human_visible_markdown: intent.status === "verified" ? undefined : paymentHandoffAfter(intent)
           }));
           return;
         }
@@ -343,16 +337,13 @@ async function buyer(command, rest, flags) {
         const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
         await renderItPayPaymentAction(intent, flags);
         output(buyerRunOutput({
-          status: "waiting_user_payment",
+          status: "payment_handoff_required",
           checkout,
           payment_intent: intent,
           payment_handoff: paymentHandoff(intent),
-          agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-          next: {
-            command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-            safe_for_agent: true,
-            instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-          }
+          agent_next_actions: paymentHandoffAgentNextActions(),
+          next: paymentHandoffNext(),
+          after_human_visible_markdown: paymentHandoffAfter(intent)
         }));
         return;
       }
@@ -371,6 +362,19 @@ async function buyer(command, rest, flags) {
     const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
     if (!paymentIntentID) throw new Error("payment_intent_id is required");
     const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
+    if (intent.status !== "verified" && !paymentQRShown(flags)) {
+      await renderItPayPaymentAction(intent, flags);
+      output(buyerRunOutput({
+        status: "payment_handoff_required",
+        payment_intent: intent,
+        payment_handoff: paymentHandoff(intent),
+        payment_guidance: paymentRecoveryGuidance(intent, { event_type: "payment_display_required" }),
+        agent_next_actions: paymentHandoffAgentNextActions(),
+        next: paymentHandoffNext(),
+        after_human_visible_markdown: paymentHandoffAfter(intent)
+      }));
+      return;
+    }
     const event = intent.status === "verified"
       ? { event_type: "payment_intent.verified", payment_intent_id: paymentIntentID, agent_next_actions: intent.agent_next_actions || ["poll_checkout"] }
       : await waitBuyerPayment(intent, flags);
@@ -382,7 +386,7 @@ async function buyer(command, rest, flags) {
       agent_next_actions: event.agent_next_actions || intent.agent_next_actions || paymentAgentNextActions(intent, event),
       next: event.event_type === "payment_intent.verified"
         ? { command: intent.checkout_id ? cliCommand("buyer", "checkout", "status", intent.checkout_id, "--json") : undefined, safe_for_agent: true }
-        : { command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json"), safe_for_agent: true }
+        : { command: paymentWaitCommand(paymentIntentID, { qrShown: true }), safe_for_agent: true }
     }));
     return;
   }
@@ -392,18 +396,15 @@ async function buyer(command, rest, flags) {
     const refreshed = await refreshBuyerPaymentQR(paymentIntentID, flags);
     await renderItPayPaymentAction(refreshed, flags);
     output(buyerRunOutput({
-      status: refreshed.status === "verified" ? "payment_verified" : "waiting_user_payment",
+      status: refreshed.status === "verified" ? "payment_verified" : "payment_handoff_required",
       payment_intent: refreshed,
       payment_handoff: refreshed.status === "verified" ? undefined : paymentHandoff(refreshed),
       payment_guidance: paymentRecoveryGuidance(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
-      agent_next_actions: refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
+      agent_next_actions: refreshed.status === "verified" ? (refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: "payment_intent.verified" })) : paymentHandoffAgentNextActions(),
       next: refreshed.status === "verified"
         ? { command: cliCommand("buyer", "checkout", "status", refreshed.checkout_id, "--json"), safe_for_agent: true }
-        : {
-          command: paymentWaitCommand(refreshed.payment_intent_id, { short: true }),
-          safe_for_agent: true,
-          instruction: "Send human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-        }
+        : paymentHandoffNext(),
+      after_human_visible_markdown: refreshed.status === "verified" ? undefined : paymentHandoffAfter(refreshed)
     }));
     return;
   }
@@ -1052,7 +1053,7 @@ function paymentHandoff(intent = {}) {
   const preferredQRURL = action.preferred_qr_url || qrPNGURL || action.qr_image_url || intent.qr_image_url || intent.qr?.image_url || "";
   const localQRPath = action.local_qr_path || intent.local_qr_path || "";
   const mobileWalletURL = action.mobile_wallet_url || intent.mobile_wallet_url || "";
-  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true });
+  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true, qrShown: true });
   return {
     type: "payment_qr_handoff",
     payment_intent_id: paymentIntentID || null,
@@ -1066,7 +1067,8 @@ function paymentHandoff(intent = {}) {
     markdown: paymentHandoffMarkdown({ localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL }),
     wait_command: waitCommand || null,
     safe_for_agent: true,
-    instruction: "Show markdown to the human first. Then run wait_command and wait for payment_intent.verified unless the human asked you to pause."
+    instruction: "Show markdown to the human first. Then run wait_command and wait for payment_intent.verified unless the human asked you to pause.",
+    display_targets: paymentHandoffDisplayTargets()
   };
 }
 
@@ -1080,11 +1082,46 @@ function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRUR
   return lines.join("\n\n");
 }
 
-function paymentWaitCommand(paymentIntentID, { short = false } = {}) {
+function paymentWaitCommand(paymentIntentID, { short = false, qrShown = false } = {}) {
   if (!paymentIntentID) return "";
-  return short
-    ? cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "60", "--json")
-    : cliCommand("buyer", "payment", "wait", paymentIntentID, "--json");
+  const args = ["buyer", "payment", "wait", paymentIntentID];
+  if (short) args.push("--timeout", "60");
+  if (qrShown) args.push("--qr-shown");
+  args.push("--json");
+  return cliCommand(...args);
+}
+
+function paymentQRShown(flags = {}) {
+  if (flags.qr_shown === undefined) return false;
+  return booleanFlag(flags.qr_shown);
+}
+
+function paymentHandoffAgentNextActions() {
+  return ["show_human_visible_markdown"];
+}
+
+function paymentHandoffNext() {
+  return {
+    type: "reply_to_human",
+    safe_for_agent: false,
+    instruction: "Send human_visible_markdown to the human now. Do not run payment wait until this message is visible to the human."
+  };
+}
+
+function paymentHandoffAfter(intent = {}) {
+  return {
+    command: paymentWaitCommand(intent.payment_intent_id, { short: true, qrShown: true }),
+    safe_for_agent: true,
+    instruction: "Run this only after human_visible_markdown has been sent to the human."
+  };
+}
+
+function paymentHandoffDisplayTargets() {
+  return {
+    desktop_app: ["local_qr_path", "qr_png_url", "payment_entry_url"],
+    terminal: ["qr_png_url", "payment_entry_url", "mobile_wallet_url"],
+    chat_cloud: ["qr_png_url", "payment_entry_url", "mobile_wallet_url"]
+  };
 }
 
 function paymentRecoveryGuidance(intent = {}, event = {}) {
@@ -1426,7 +1463,7 @@ async function waitBuyerPayment(intent, flags = {}) {
       action: intent?.human_action || null,
       lastHeartbeatAt,
       flags,
-      command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json")
+      command: paymentWaitCommand(paymentIntentID, { qrShown: true })
     });
   }
   return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["wait_payment"] };
@@ -1651,7 +1688,7 @@ function buyerDocsFor(value = {}) {
     topics.add("cart-checkout");
     topics.add("payment-qr");
   }
-  if (status.includes("waiting_user_payment") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
+  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("show_human_visible_markdown") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
     topics.add("payment-qr");
     topics.add("payment-wait");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -213,10 +213,15 @@ This keeps JSON output machine-readable while allowing the CLI to prepare a
 local QR image path for clients that cannot render remote SVG reliably. In
 Codex or Claude Code app clients, prefer `--no-wait-payment`: send
 `human_visible_markdown` to the human first, then run
-`next.command`. If the human is on mobile, present
+`after_human_visible_markdown.command`. If the human is on mobile, present
 `mobile_wallet_url` as a clickable human-only fallback; do not convert it into a
 QR.
 
+If a response has `status=payment_handoff_required`, `next` is the user-visible
+reply step, not payment wait. Do not run `buyer payment wait` until the QR/link
+has been sent to the human; then use the returned
+`after_human_visible_markdown.command` with `--qr-shown`.
+
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first
 and then payment after ItPay receives the OAuth callback. Do not call