@itpay/cli 0.2.5 → 0.2.7

package/README.md

@@ -214,7 +214,7 @@ redacted secure delivery status:
 itp buyer catalog search --query 企业工商 --json
 itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=阿里 --json
 itp buyer checkout create --cart <cart_id> --email <buyer_email> --json
-itp buyer payment wait <payment_intent_id> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --json
 itp buyer checkout status <checkout_id> --json
 ```
 
@@ -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 `after_human_visible_markdown.command`.
+- In agent app clients, execute `render_plan.selected` first. Send its media, text/markdown, real links, and native buttons when the adapter supports them.
+- Do not rewrite `render_plan.selected` into a custom table or omit the real URL.
 - If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 

package/bin/itp

@@ -109,7 +109,7 @@ async function main() {
           "buyer checkout status <checkout_id> --json",
           "buyer checkout resume <checkout_id> --json",
           "buyer auth status --json",
-          "buyer payment wait <payment_intent_id> --json",
+          "buyer payment wait <payment_intent_id> --timeout 1 --json",
           "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
           "buyer deliveries list --checkout <checkout_id> --json",
           "buyer deliveries show <delivery_id> --checkout <checkout_id> --json",

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

@@ -11,14 +11,22 @@
     "The human needs to scan with the payment provider."
   ],
   "required_state": {
-    "needs": ["payment_intent_id", "human_action", "qr_png_url/preferred_qr_url or local_qr_path"],
-    "must_not_need": ["raw provider QR", "provider sign", "ops token"]
+    "needs": [
+      "payment_intent_id",
+      "human_action",
+      "qr_png_url/preferred_qr_url or local_qr_path"
+    ],
+    "must_not_need": [
+      "raw provider QR",
+      "provider sign",
+      "ops token"
+    ]
   },
   "commands": [
     {
       "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.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"
+      "success_signal": "response.status is payment_handoff_required; response.human_visible_markdown and response.render_plan are present; render the QR/link to the human before any status check"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,8 +41,13 @@
     "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.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.",
+    "If response.render_plan.selected exists, treat it as the final UI render plan for the current host. Execute selected before reading other platform branches.",
+    "Do not rewrite response.render_plan.selected into a custom table. Use selected.text/markdown, selected.media, selected.links, and selected.buttons as provided.",
+    "If selected.links exists, include the real URL. Do not only show the link label.",
+    "If selected.buttons exists but the current adapter cannot render native buttons, degrade to selected.links plus short text; do not fake payment success or skip the status check.",
+    "In Codex or Claude Code app clients, send response.human_visible_markdown or response.render_plan.platforms.codex_app.markdown to the human first. Do not start a hidden long wait before the human-visible message is sent.",
+    "For Telegram-style message clients, use response.render_plan.platforms.telegram: send photo media first, include links, and expose native buttons for refresh/status when the adapter supports them.",
+    "For plain chat clients, show response.human_visible_markdown and stop unless the human asks you to check status 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.",
@@ -43,8 +56,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. 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."
+    "Do not run payment wait before the QR/link has been sent to the human. Without an explicit short timeout, CLI returns payment_handoff_required instead of blocking.",
+    "After the human says they paid or clicks a platform status button, run response.after_human_response.check_payment_command 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.",
@@ -67,5 +80,14 @@
       "command": "itp docs show qr-refresh --role buyer --json"
     }
   ],
-  "search_terms": ["qr", "payment qr", "alipay", "scan", "order not found", "二维码", "扫码", "付款码"]
+  "search_terms": [
+    "qr",
+    "payment qr",
+    "alipay",
+    "scan",
+    "order not found",
+    "二维码",
+    "扫码",
+    "付款码"
+  ]
 }

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

@@ -10,15 +10,23 @@
     "The CLI returned agent_wait metadata."
   ],
   "required_state": {
-    "needs": ["payment_intent_id"],
-    "optional": ["cursor"],
-    "must_not_need": ["ops token", "provider query permission", "human text proof"]
+    "needs": [
+      "payment_intent_id"
+    ],
+    "optional": [
+      "cursor"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider query permission",
+      "human text proof"
+    ]
   },
   "commands": [
     {
       "intent": "wait for payment verified event",
-      "command": "itp buyer payment wait <payment_intent_id> --qr-shown --json",
-      "success_signal": "response.payment_event.event_type == payment_intent.verified"
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "success_signal": "response.payment_event.event_type is payment_intent.verified or wait.timeout"
     },
     {
       "intent": "resume checkout after verified event",
@@ -27,12 +35,13 @@
     }
   ],
   "agent_rules": [
-    "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.",
+    "If payment wait returns payment_handoff_required, render response.render_plan.selected to the human before running any later status check.",
+    "Start payment status checks only after the QR image/link has already been sent to the human or the human asks to check status.",
+    "If you run payment wait without a short timeout while payment is still pending, CLI returns payment_handoff_required and human_visible_markdown instead of long-polling.",
+    "Payment wait/status check 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.",
-    "Continue waiting with the same payment_intent_id unless the user explicitly cancels or asks you to pause.",
+    "In Codex or Claude Code app clients, after showing QR, use a short status check first. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",
+    "Continue checking the same payment_intent_id unless the user explicitly cancels or asks you to pause.",
     "If the network drops, the process is interrupted, or there is no response, rerun payment wait with the same payment_intent_id or run checkout status/resume with the same checkout_id.",
     "If status is unclear, tell the human it is unclear and continue querying the same payment_intent_id/checkout_id. Do not create a new checkout.",
     "Payment success is payment_intent.verified only.",
@@ -57,5 +66,18 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["wait", "long poll", "timeout", "still waiting", "paid", "payment", "等待", "付款", "付款成功", "没返回", "一直等", "超时"]
+  "search_terms": [
+    "wait",
+    "long poll",
+    "timeout",
+    "still waiting",
+    "paid",
+    "payment",
+    "等待",
+    "付款",
+    "付款成功",
+    "没返回",
+    "一直等",
+    "超时"
+  ]
 }

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

@@ -21,7 +21,7 @@
     },
     {
       "intent": "continue waiting after refresh",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
       "success_signal": "payment_event.event_type == payment_intent.verified"
     }
   ],

package/docs/agent/buyer/quickstart.json

@@ -10,8 +10,16 @@
     "The agent is unsure which ItPay buyer command should come first."
   ],
   "required_state": {
-    "needs": ["itp CLI available", "buyer delivery email before checkout"],
-    "must_not_need": ["ops token", "claim token", "raw key", "provider raw payload"]
+    "needs": [
+      "itp CLI available",
+      "buyer delivery email before checkout"
+    ],
+    "must_not_need": [
+      "ops token",
+      "claim token",
+      "raw key",
+      "provider raw payload"
+    ]
   },
   "commands": [
     {
@@ -37,7 +45,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 payment_handoff_required; if payment_handoff_required, send response.human_visible_markdown to the human before running response.after_human_visible_markdown.command"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if payment_handoff_required, render response.human_visible_markdown or response.render_plan to the human before any payment status check"
     }
   ],
   "agent_rules": [
@@ -54,12 +62,13 @@
     "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 after_human_visible_markdown.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/render_plan, then only check status after the human responds or uses a platform button.",
     "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.",
+    "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the human asks to check payment should you run after_human_response.check_payment_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."
+    "Secure delivery goes to the human first; report redacted delivery status only.",
+    "When a response includes render_plan.selected, execute that selected plan first; do not make the model choose a different platform branch or rewrite the payment/auth UI."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",
@@ -95,5 +104,14 @@
       "command": "itp docs show account-portal --role buyer --json"
     }
   ],
-  "search_terms": ["start", "quickstart", "first time", "buyer flow", "how to use itpay", "开始", "第一次", "怎么用"]
+  "search_terms": [
+    "start",
+    "quickstart",
+    "first time",
+    "buyer flow",
+    "how to use itpay",
+    "开始",
+    "第一次",
+    "怎么用"
+  ]
 }

package/docs/agent/buyer/recovery.json

@@ -22,7 +22,7 @@
     },
     {
       "intent": "wait again on the same payment intent",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
     },
     {

package/lib/buyer.js

@@ -4,7 +4,7 @@ import {
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -23,6 +23,7 @@ async function buyerBuy(flags) {
         cart,
         checkout,
         human_action: checkout.human_action,
+        render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
         agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
         next: {
           command: cliCommand("buyer", "checkout", "resume", checkout.checkout_id, "--json"),
@@ -50,10 +51,9 @@ async function buyerBuy(flags) {
       cart,
       checkout,
       payment_intent: intent,
-      payment_handoff: paymentHandoff(intent),
+      ...paymentHandoffFields(intent, flags),
       agent_next_actions: paymentHandoffAgentNextActions(),
-      next: paymentHandoffNext(),
-      after_human_visible_markdown: paymentHandoffAfter(intent)
+      next: paymentHandoffNext()
     }));
     return;
   }
@@ -215,6 +215,9 @@ async function buyer(command, rest, flags) {
           checkout,
           buyer_session: buyerSessionClaimStatus(),
           checkout_guidance: checkoutAuthorizationGuidance(checkout),
+          render_plan: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
+            ? buildHumanActionRenderPlan(checkout.human_action, {}, flags)
+            : undefined,
           agent_next_actions: checkout.agent_next_actions || checkoutAgentNextActions(checkout),
           next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
             ? {
@@ -240,6 +243,9 @@ async function buyer(command, rest, flags) {
         checkout,
         buyer_session: buyerSessionClaimStatus(),
         checkout_guidance: checkoutAuthorizationGuidance(checkout),
+        render_plan: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
+          ? buildHumanActionRenderPlan(checkout.human_action, {}, flags)
+          : undefined,
         agent_next_actions: checkout.agent_next_actions || checkoutAgentNextActions(checkout),
         next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
           ? {
@@ -278,6 +284,7 @@ async function buyer(command, rest, flags) {
             status: "waiting_human_auth",
             checkout,
             human_action: checkout.human_action,
+            render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
             agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
             next: {
               command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
@@ -293,6 +300,7 @@ async function buyer(command, rest, flags) {
             status: "waiting_human_auth",
             checkout,
             human_action: checkout.human_action,
+            render_plan: buildHumanActionRenderPlan(checkout.human_action, {}, flags),
             agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
             next: {
               command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
@@ -317,13 +325,12 @@ async function buyer(command, rest, flags) {
             status: intent.status === "verified" ? "payment_verified" : "payment_handoff_required",
             checkout,
             payment_intent: intent,
-            payment_handoff: intent.status === "verified" ? undefined : paymentHandoff(intent),
+            ...(intent.status === "verified" ? {} : paymentHandoffFields(intent, flags)),
             buyer_session: buyerSessionClaimStatus(claimedSession),
             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 }
-              : paymentHandoffNext(),
-            after_human_visible_markdown: intent.status === "verified" ? undefined : paymentHandoffAfter(intent)
+              : paymentHandoffNext()
           }));
           return;
         }
@@ -340,10 +347,9 @@ async function buyer(command, rest, flags) {
           status: "payment_handoff_required",
           checkout,
           payment_intent: intent,
-          payment_handoff: paymentHandoff(intent),
+          ...paymentHandoffFields(intent, flags),
           agent_next_actions: paymentHandoffAgentNextActions(),
-          next: paymentHandoffNext(),
-          after_human_visible_markdown: paymentHandoffAfter(intent)
+          next: paymentHandoffNext()
         }));
         return;
       }
@@ -362,16 +368,15 @@ 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)) {
+    if (intent.status !== "verified" && shouldReturnPaymentHandoffBeforeWait(flags)) {
       await renderItPayPaymentAction(intent, flags);
       output(buyerRunOutput({
         status: "payment_handoff_required",
         payment_intent: intent,
-        payment_handoff: paymentHandoff(intent),
+        ...paymentHandoffFields(intent, flags),
         payment_guidance: paymentRecoveryGuidance(intent, { event_type: "payment_display_required" }),
         agent_next_actions: paymentHandoffAgentNextActions(),
-        next: paymentHandoffNext(),
-        after_human_visible_markdown: paymentHandoffAfter(intent)
+        next: paymentHandoffNext()
       }));
       return;
     }
@@ -386,7 +391,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: paymentWaitCommand(paymentIntentID, { qrShown: true }), safe_for_agent: true }
+        : { command: paymentStatusCheckCommand(paymentIntentID), safe_for_agent: true }
     }));
     return;
   }
@@ -398,13 +403,12 @@ async function buyer(command, rest, flags) {
     output(buyerRunOutput({
       status: refreshed.status === "verified" ? "payment_verified" : "payment_handoff_required",
       payment_intent: refreshed,
-      payment_handoff: refreshed.status === "verified" ? undefined : paymentHandoff(refreshed),
+      ...(refreshed.status === "verified" ? {} : paymentHandoffFields(refreshed, flags)),
       payment_guidance: paymentRecoveryGuidance(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 }
-        : paymentHandoffNext(),
-      after_human_visible_markdown: refreshed.status === "verified" ? undefined : paymentHandoffAfter(refreshed)
+        : paymentHandoffNext()
     }));
     return;
   }
@@ -900,7 +904,7 @@ async function waitBuyerCheckoutAuth(checkout, flags = {}) {
   if (!checkoutID) throw new Error("checkout_id is required");
   const timeoutMs = Number(flags.auth_timeout || flags.timeout || 900) * 1000;
   const started = Date.now();
-  let lastHeartbeatAt = 0;
+  let lastHeartbeatAt = Date.now();
   let current = typeof checkout === "string" ? await getBuyerCheckout(checkoutID, flags) : checkout;
   const authAction = current?.human_action || readCoreAuthAction(checkoutID) || null;
   rememberCoreAuthAction(checkoutID, authAction);
@@ -1037,12 +1041,20 @@ function paymentAgentNextActions(intent = {}, event = {}) {
     return ["poll_checkout_delivery"];
   }
   if (event.event_type === "wait.timeout") {
-    return ["wait_same_payment_intent", "resume_checkout_status_if_needed"];
+    return ["check_same_payment_intent", "resume_checkout_status_if_needed"];
   }
   if (event.event_type === "qr_refreshed") {
-    return ["show_returned_qr", "wait_same_payment_intent"];
+    return ["show_returned_qr", "check_same_payment_intent"];
   }
-  return ["show_payment_qr_if_needed", "wait_same_payment_intent"];
+  return ["show_payment_qr_if_needed", "check_same_payment_intent"];
+}
+
+function paymentHandoffFields(intent = {}, flags = {}) {
+  return {
+    payment_handoff: paymentHandoff(intent),
+    render_plan: buildHumanActionRenderPlan(intent.human_action || {}, intent, flags),
+    after_human_response: paymentHandoffAfterHumanResponse(intent)
+  };
 }
 
 function paymentHandoff(intent = {}) {
@@ -1053,7 +1065,6 @@ 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, qrShown: true });
   return {
     type: "payment_qr_handoff",
     payment_intent_id: paymentIntentID || null,
@@ -1065,10 +1076,8 @@ function paymentHandoff(intent = {}) {
     payment_entry_url: entryURL || null,
     mobile_wallet_url: mobileWalletURL || null,
     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.",
-    display_targets: paymentHandoffDisplayTargets()
+    instruction: "Render the QR/link to the human first. After the human responds or uses a platform button, query the same payment_intent_id. Only payment_intent.verified proves payment."
   };
 }
 
@@ -1078,22 +1087,20 @@ function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRUR
   if (imageURL) lines.push(`![ItPay payment QR](${imageURL})`);
   if (entryURL) lines.push(`[打开付款页面](${entryURL})`);
   if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
-  lines.push("我会继续等待 ItPay 返回 payment_intent.verified。");
+  lines.push("付款后回复“我已付款”，我会查询真实支付状态。");
   return lines.join("\n\n");
 }
 
-function paymentWaitCommand(paymentIntentID, { short = false, qrShown = false } = {}) {
+function paymentStatusCheckCommand(paymentIntentID) {
   if (!paymentIntentID) return "";
-  const args = ["buyer", "payment", "wait", paymentIntentID];
-  if (short) args.push("--timeout", "60");
-  if (qrShown) args.push("--qr-shown");
-  args.push("--json");
-  return cliCommand(...args);
+  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", "--json");
 }
 
-function paymentQRShown(flags = {}) {
-  if (flags.qr_shown === undefined) return false;
-  return booleanFlag(flags.qr_shown);
+function shouldReturnPaymentHandoffBeforeWait(flags = {}) {
+  if (booleanFlag(flags.wait || flags.long_wait || false)) return false;
+  if (flags.timeout === undefined) return true;
+  const timeout = Number(flags.timeout);
+  return !Number.isFinite(timeout) || timeout > 5;
 }
 
 function paymentHandoffAgentNextActions() {
@@ -1108,19 +1115,13 @@ function paymentHandoffNext() {
   };
 }
 
-function paymentHandoffAfter(intent = {}) {
+function paymentHandoffAfterHumanResponse(intent = {}) {
+  const paymentIntentID = intent.payment_intent_id || intent.human_action?.id || "";
   return {
-    command: paymentWaitCommand(intent.payment_intent_id, { short: true, qrShown: true }),
+    check_payment_command: paymentStatusCheckCommand(paymentIntentID),
+    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", "--json") : "",
     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"]
+    instruction: "Use check_payment_command after the human says they paid or a platform button requests a status check. User text is not proof; only payment_intent.verified is."
   };
 }
 
@@ -1136,10 +1137,10 @@ function paymentRecoveryGuidance(intent = {}, event = {}) {
     next_step: event.event_type === "payment_intent.verified" || intent.status === "verified"
       ? "付款已验证；进入 checkout status / 交付模块。"
       : event.event_type === "wait.timeout"
-        ? "wait.timeout 不是付款失败；继续等待同一个 payment_intent_id，或用 checkout status/resume 确认状态。"
+        ? "wait.timeout 不是付款失败；继续查询同一个 payment_intent_id，或用 checkout status/resume 确认状态。"
         : event.event_type === "qr_refreshed"
-          ? "展示 ItPay 返回的 QR，然后继续等待同一个 payment_intent_id。"
-          : "展示 ItPay 返回的付款入口并等待 payment_intent.verified；用户口头说已付款不算证明。",
+          ? "展示 ItPay 返回的 QR，然后继续查询同一个 payment_intent_id。"
+          : "展示 ItPay 返回的付款入口；用户反馈后查询 payment_intent.verified，用户口头说已付款不算证明。",
     network_or_interrupt: "断网、无响应、进程中断时，重新运行 payment wait 或 checkout status/resume，使用同一个 payment_intent_id / checkout_id。",
     qr_problem: "QR 未显示时不要自造二维码；先用返回的 local_qr_path/qr_png_url/preferred_qr_url。扫码提示订单不存在或过期时，先等 30-60 秒重扫同一 QR，仍失败才 refresh-qr。",
     do_not: [
@@ -1444,12 +1445,13 @@ async function waitBuyerPayment(intent, flags = {}) {
   const waitURL = flags.wait_url || intent?.agent_wait?.wait_url || `/v1/payment-intents/${encodeURIComponent(paymentIntentID)}/events/wait`;
   const timeoutMs = Number(flags.timeout || 900) * 1000;
   const started = Date.now();
-  let lastHeartbeatAt = 0;
+  let lastHeartbeatAt = Date.now();
   let lastEvent = null;
   while (Date.now() - started < timeoutMs) {
+    const remainingMs = Math.max(1000, timeoutMs - (Date.now() - started));
     const params = new URLSearchParams();
     if (cursor) params.set("cursor", cursor);
-    params.set("timeout", String(flags.poll_timeout || "30s"));
+    params.set("timeout", String(flags.poll_timeout || `${Math.ceil(Math.min(30000, remainingMs) / 1000)}s`));
     const event = await coreApi(appendURLQuery(waitURL, params), { method: "GET" }, flags);
     lastEvent = event;
     cursor = event.cursor || cursor;
@@ -1463,10 +1465,10 @@ async function waitBuyerPayment(intent, flags = {}) {
       action: intent?.human_action || null,
       lastHeartbeatAt,
       flags,
-      command: paymentWaitCommand(paymentIntentID, { qrShown: true })
+      command: paymentStatusCheckCommand(paymentIntentID)
     });
   }
-  return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["wait_payment"] };
+  return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["check_payment_status"] };
 }
 
 async function waitBuyerDelivery(checkoutID, flags = {}) {
@@ -1639,6 +1641,7 @@ function compactHumanAction(action = null) {
   if (!action || typeof action !== "object") return action;
   return compactObject({
     kind: action.kind,
+    payment_intent_id: action.payment_intent_id,
     url: action.url,
     local_qr_path: action.local_qr_path,
     local_qr_mime: action.local_qr_mime,

package/lib/env.js

@@ -98,10 +98,14 @@ function apiTimeoutMs(flags = {}) {
 }
 
 function parseFlags(args) {
+  const removedQRDisplayFlag = ["--qr", "shown"].join("-");
   const flags = {};
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (!arg.startsWith("--")) continue;
+    if (arg === removedQRDisplayFlag) {
+      throw new Error("legacy QR display flag has been removed; show the payment QR to the human, then run buyer payment wait <payment_intent_id> --timeout 1 --json.");
+    }
     const key = arg.slice(2).replaceAll("-", "_");
     const next = args[i + 1];
     if (!next || next.startsWith("--")) {

package/lib/render-human.js

@@ -7,12 +7,18 @@ import { apiTimeoutMs, cliCommand, commandExists, mergeRun, readRun, readState,
 
 async function renderItPayPaymentAction(intent, flags = {}) {
   const action = intent?.human_action ? { ...intent.human_action } : (intent?.payment_url ? {
+    kind: "payment_qr",
     id: intent.payment_intent_id,
+    payment_intent_id: intent.payment_intent_id,
     title: "Scan payment QR",
     url: intent.payment_url,
     expires_at: intent.qr?.expires_at
   } : null);
   if (action) {
+    if (!action.kind && isPaymentIntentHandoff(intent)) action.kind = "payment_qr";
+    if (!action.id && intent?.payment_intent_id) action.id = intent.payment_intent_id;
+    if (!action.payment_intent_id && intent?.payment_intent_id) action.payment_intent_id = intent.payment_intent_id;
+    if (!action.url && (intent?.payment_url || intent?.payment_entry_url)) action.url = intent.payment_url || intent.payment_entry_url;
     if (intent?.qr_png_url || intent?.qr?.png_url) {
       action.qr_png_url = intent.qr_png_url || intent.qr.png_url;
     }
@@ -35,6 +41,18 @@ async function renderItPayPaymentAction(intent, flags = {}) {
   return result;
 }
 
+function isPaymentIntentHandoff(intent = {}) {
+  return Boolean(
+    intent?.payment_intent_id ||
+    intent?.payment_url ||
+    intent?.payment_entry_url ||
+    intent?.qr_png_url ||
+    intent?.qr_image_url ||
+    intent?.qr?.png_url ||
+    intent?.qr?.image_url
+  );
+}
+
 function humanActionSummaryLines(action) {
   if (!action?.url) return [];
   const lines = [
@@ -265,6 +283,117 @@ function annotateHumanActionPresentation(action, qrImageURL) {
   return action;
 }
 
+function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
+  if (!action || typeof action !== "object") return null;
+  const kind = action.kind || (isPaymentIntentHandoff(intent) ? "payment_qr" : "human_action");
+  const planAction = action.kind === kind ? action : { ...action, kind };
+  const entryURL = intent.payment_entry_url || intent.payment_url || action.url || action.web_url || "";
+  const qrPNGURL = action.qr_png_url || intent.qr_png_url || intent.qr?.png_url || "";
+  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 || humanActionPresentationURL(action, "mobile_wallet_url") || "";
+  const imageSource = localQRPath || qrPNGURL || preferredQRURL;
+  const requiredOutputs = [];
+  if (imageSource) {
+    requiredOutputs.push(compactObject({
+      type: "image",
+      local_path: localQRPath || undefined,
+      fallback_url: preferredQRURL || qrPNGURL || undefined,
+      must_be_user_visible: true
+    }));
+  }
+  if (entryURL) requiredOutputs.push({ type: "link", label: kind === "auth_qr" ? "打开授权页面" : "打开付款页面", url: entryURL });
+  if (mobileWalletURL) requiredOutputs.push({ type: "link", label: "手机钱包打开", url: mobileWalletURL });
+  const markdown = humanActionMarkdown(planAction, { localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL });
+  const telegram = telegramRenderPlan(planAction, { localQRPath, preferredQRURL, entryURL, mobileWalletURL });
+  const host = agentHost(flags);
+  const platforms = compactObject({
+    codex_app: { format: "markdown_image_and_links", markdown },
+    claude_code: { format: "markdown_image_and_links", markdown },
+    telegram,
+    plain_chat: {
+      format: "image_or_link_then_human_reply",
+      text: kind === "payment_qr"
+        ? "请扫码或点击链接完成支付。付完后回复“我已付款”，我再查询真实状态。"
+        : "请打开上面的授权入口。完成后告诉我，我再继续查询状态。",
+      links: requiredOutputs.filter((item) => item.type === "link")
+    },
+    terminal: {
+      format: "cli_prints_qr_then_wait",
+      print_terminal_qr: true,
+      print_links: true
+    }
+  });
+  const selectedPlatform = selectedRenderPlatform(host);
+  const selected = {
+    platform: selectedPlatform,
+    ...platforms[selectedPlatform]
+  };
+  return compactObject({
+    kind,
+    proof_rule: kind === "payment_qr"
+      ? "Only payment_intent.verified proves payment."
+      : "This human action is not payment proof.",
+    host: host || undefined,
+    required_outputs: requiredOutputs,
+    selected,
+    platforms,
+    forbidden: [
+      "Do not say 'scan the QR above' unless an image or scannable URL is actually attached.",
+      "Do not read a local image file as model input and treat that as sent to the human.",
+      "Do not treat page open, QR display, button click, or human text as payment proof.",
+      "Do not create a new checkout because payment is still pending."
+    ]
+  });
+}
+
+function humanActionMarkdown(action = {}, { localQRPath = "", qrPNGURL = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
+  const imageURL = localQRPath || qrPNGURL || preferredQRURL;
+  const lines = [action.kind === "auth_qr" ? "请打开 ItPay 授权入口：" : "请扫码付款："];
+  if (imageURL) lines.push(`![ItPay ${action.kind === "auth_qr" ? "auth" : "payment"} QR](${imageURL})`);
+  if (entryURL) lines.push(`[${action.kind === "auth_qr" ? "打开授权页面" : "打开付款页面"}](${entryURL})`);
+  if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
+  lines.push(action.kind === "payment_qr" ? "付款后回复“我已付款”，我会查询真实支付状态。" : "完成授权后回复，我会继续同一个 checkout。");
+  return lines.join("\n\n");
+}
+
+function telegramRenderPlan(action = {}, { localQRPath = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
+  const media = localQRPath || preferredQRURL
+    ? [compactObject({ type: "photo", local_path: localQRPath || undefined, fallback_url: preferredQRURL || undefined })]
+    : [];
+  const links = [];
+  if (entryURL) links.push({ label: action.kind === "auth_qr" ? "打开授权页面" : "打开付款页面", url: entryURL });
+  if (mobileWalletURL) links.push({ label: "手机钱包打开", url: mobileWalletURL });
+  const buttons = action.kind === "payment_qr"
+    ? [
+      { text: "支付遇到问题 / 刷新", intent: "refresh_payment_qr" },
+      { text: "我已付款，查询状态", intent: "check_payment_status" }
+    ]
+    : entryURL ? [{ text: "打开授权页面", url: entryURL }] : [];
+  return {
+    format: action.kind === "payment_qr" ? "photo_text_inline_buttons" : "text_inline_buttons",
+    media,
+    text: action.kind === "payment_qr"
+      ? "请扫码或点击链接完成支付。付款后点“我已付款，查询状态”。"
+      : "请打开 ItPay 授权入口，完成后回到当前对话。",
+    links,
+    buttons
+  };
+}
+
+function selectedRenderPlatform(host = "") {
+  const normalized = String(host || "").toLowerCase().replaceAll("-", "_");
+  if (["codex", "codex_app", "codex_cli"].includes(normalized)) return "codex_app";
+  if (["claude", "claude_code", "claudecode"].includes(normalized)) return "claude_code";
+  if (["telegram", "tg"].includes(normalized)) return "telegram";
+  if (terminalQRHostAliases().has(normalized)) return "terminal";
+  return "plain_chat";
+}
+
+function compactObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null && item !== ""));
+}
+
 function shouldPrepareLocalQRForJSON(mode, flags = {}, action = {}) {
   if (mode === "file" || flags.qr_file || process.env.ITP_QR_FILE) return true;
   if (action?.qr_png_url || action?.preferred_qr_url || action?.qr_image_url) return true;
@@ -496,4 +625,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };
+export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -75,7 +75,7 @@ itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity
 itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
 itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json
 itp buyer checkout resume <checkout_id> --json
-itp buyer payment wait <payment_intent_id> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --json
 itp buyer checkout status <checkout_id> --json
 itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --json
 itp buyer refund list --order <order_id> --json
@@ -211,16 +211,18 @@ itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent
 
 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
-`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.
+Codex or Claude Code app clients, prefer `--no-wait-payment`: execute
+`render_plan.selected` first. If `selected.markdown` exists, send it exactly to
+the human. If `selected.media` exists, attach the listed image before saying the
+human can scan it. If `selected.links` exists, include the real URL, not just
+the label. If `selected.buttons` exists and the current adapter supports native
+buttons, render them; otherwise fall back to the real URL plus short text. Do
+not invent a table or rewrite the UI plan.
 
 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`.
+reply step, not payment wait. Do not run `buyer payment wait` until the human
+has seen the QR/link and asks to check status; then use
+`after_human_response.check_payment_command`.
 
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first