@itpay/cli 0.2.2 → 0.2.3

package/README.md

@@ -221,7 +221,7 @@ itp buyer checkout status <checkout_id> --json
 For the one-command buyer helper:
 
 ```bash
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --email buyer@example.com --input company_name=阿里 --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email buyer@example.com --input company_name=阿里 --display agent --no-wait-payment --json
 ```
 
 For multi-item cart tests:
@@ -239,6 +239,7 @@ 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 `payment_handoff.markdown` to the human first, then run `payment_handoff.wait_command`.
 - Treat only `payment_intent.verified` as payment success.
 
 If the human wants the agent to analyze delivered content, the human must reveal

package/bin/itp

@@ -93,7 +93,7 @@ async function main() {
       output({
         version: VERSION,
         commands: [
-          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --json",
+          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --display agent --no-wait-payment --json",
           "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --no-wait --json",
           "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --json",
           "buyer catalog get --variant var_pubg_couple_skin_cny20 --json",

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

@@ -68,7 +68,7 @@
     },
     {
       "intent": "do both steps through the high-level command",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --json",
+      "command": "itp buy <variant_id> --sandbox --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"
     }
   ],

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

@@ -17,8 +17,8 @@
   "commands": [
     {
       "intent": "create payment intent through the high-level buy flow",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --json",
-      "success_signal": "response.payment_intent.human_action.local_qr_path or response.payment_intent.human_action.qr_png_url is present"
+      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "success_signal": "response.payment_handoff.markdown and response.payment_handoff.wait_command are present"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,6 +33,8 @@
     "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: show response.payment_handoff.markdown first, then run response.payment_handoff.wait_command.",
+    "For Telegram-style message clients, show response.payment_handoff.markdown and stop unless the human asks you to keep waiting or returns with a payment question.",
     "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.",
@@ -40,7 +42,8 @@
     "payment_entry_url is the stable ItPay status/payment page. qr_png_url/local_qr_path is usually the better desktop scanner artifact.",
     "In Alipay sandbox, 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.",
-    "After showing QR, immediately wait for payment verification."
+    "Do not run payment wait before the QR/link has been sent to the human.",
+    "After showing QR, run payment_handoff.wait_command or buyer payment wait 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

@@ -27,9 +27,11 @@
     }
   ],
   "agent_rules": [
+    "Start payment wait only after the QR image/link has already been sent to the human.",
     "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.",
-    "Continue waiting with the same payment_intent_id unless the user explicitly cancels.",
+    "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.",
     "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.",

package/docs/agent/buyer/quickstart.json

@@ -36,8 +36,8 @@
     },
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --json",
-      "success_signal": "response.status becomes waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+      "command": "itp buy <variant_id> --sandbox --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.payment_handoff contains markdown and wait_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; it is designed to show the first-purchase entry, wait/resume, continue to payment, wait for verification, and poll delivery.",
-    "Show the returned payment QR exactly as provided.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show payment_handoff, then run payment_handoff.wait_command.",
+    "If response.payment_handoff.markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "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

@@ -4,9 +4,10 @@ import {
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { renderHumanAction, renderItPayPaymentAction, writeWaitHeartbeat } from "./render-human.js";
+import { renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
+  const showThenWait = shouldReturnAfterAgentTextQR(flags);
   const selectionID = flags.selection || flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id;
   if (!selectionID) throw new Error("catalog variant id is required, for example: itp buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --json");
   const selection = await resolveBuyerCatalogSelection(selectionID, flags);
@@ -14,7 +15,7 @@ async function buyerBuy(flags) {
   let checkout = await createBuyerCheckoutFromCart(cart, selection, flags);
   if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
     await renderHumanAction(checkout.human_action, flags);
-    if (flags.no_wait || flags.no_wait_auth) {
+    if (flags.no_wait || flags.no_wait_auth || showThenWait) {
       output(buyerRunOutput({
         status: "waiting_human_auth",
         selection,
@@ -41,15 +42,20 @@ async function buyerBuy(flags) {
     : await createBuyerPaymentIntent(checkout.checkout_id, flags);
   await renderItPayPaymentAction(intent, flags);
 
-  if (flags.no_wait || flags.no_wait_payment) {
+  if (flags.no_wait || flags.no_wait_payment || showThenWait) {
     output(buyerRunOutput({
       status: "waiting_user_payment",
       selection,
       cart,
       checkout,
       payment_intent: intent,
+      payment_handoff: paymentHandoff(intent),
       agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-      next: { command: cliCommand("buyer", "payment", "wait", intent.payment_intent_id, "--json") }
+      next: {
+        command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
+        safe_for_agent: true,
+        instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+      }
     }));
     return;
   }
@@ -312,8 +318,16 @@ async function buyer(command, rest, flags) {
             status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
             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.agent_next_actions || checkout.agent_next_actions || ["wait_payment"],
+            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 payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+              }
           }));
           return;
         }
@@ -326,7 +340,18 @@ async function buyer(command, rest, flags) {
         }
         const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
         await renderItPayPaymentAction(intent, flags);
-        output(buyerRunOutput({ status: "waiting_user_payment", checkout, payment_intent: intent, agent_next_actions: intent.agent_next_actions || ["wait_payment"] }));
+        output(buyerRunOutput({
+          status: "waiting_user_payment",
+          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 payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+          }
+        }));
         return;
       }
       output(buyerRunOutput({
@@ -367,11 +392,16 @@ async function buyer(command, rest, flags) {
     output(buyerRunOutput({
       status: refreshed.status === "verified" ? "payment_verified" : "waiting_user_payment",
       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" }),
       next: refreshed.status === "verified"
         ? { command: cliCommand("buyer", "checkout", "status", refreshed.checkout_id, "--json"), safe_for_agent: true }
-        : { command: cliCommand("buyer", "payment", "wait", refreshed.payment_intent_id, "--json"), safe_for_agent: true }
+        : {
+          command: paymentWaitCommand(refreshed.payment_intent_id, { short: true }),
+          safe_for_agent: true,
+          instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+        }
     }));
     return;
   }
@@ -997,6 +1027,49 @@ function paymentAgentNextActions(intent = {}, event = {}) {
   return ["show_payment_qr_if_needed", "wait_same_payment_intent"];
 }
 
+function paymentHandoff(intent = {}) {
+  const action = intent.human_action || {};
+  const paymentIntentID = intent.payment_intent_id || action.id || "";
+  const entryURL = intent.payment_entry_url || intent.payment_url || action.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 || "";
+  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true });
+  return {
+    type: "payment_qr_handoff",
+    payment_intent_id: paymentIntentID || null,
+    checkout_id: intent.checkout_id || null,
+    primary: localQRPath ? "local_qr_path" : (qrPNGURL ? "qr_png_url" : (preferredQRURL ? "preferred_qr_url" : "payment_entry_url")),
+    local_qr_path: localQRPath || null,
+    qr_png_url: qrPNGURL || null,
+    preferred_qr_url: preferredQRURL || null,
+    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."
+  };
+}
+
+function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
+  const imageURL = localQRPath || qrPNGURL || preferredQRURL;
+  const lines = ["请扫码付款："];
+  if (imageURL) lines.push(`![ItPay payment QR](${imageURL})`);
+  if (entryURL) lines.push(`[打开付款页面](${entryURL})`);
+  if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
+  lines.push("我会继续等待 ItPay 返回 payment_intent.verified。");
+  return lines.join("\n\n");
+}
+
+function paymentWaitCommand(paymentIntentID, { short = false } = {}) {
+  if (!paymentIntentID) return "";
+  return short
+    ? cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "60", "--json")
+    : cliCommand("buyer", "payment", "wait", paymentIntentID, "--json");
+}
+
 function paymentRecoveryGuidance(intent = {}, event = {}) {
   const paymentIntentID = intent.payment_intent_id || event.payment_intent_id || null;
   return {

package/lib/render-human.js

@@ -121,7 +121,7 @@ async function renderHumanAction(action, flags = {}) {
     }
     return { rendered: false, mode: flags.json ? "json" : mode };
   }
-  const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
+  const host = agentHost(flags);
   if (["discord", "telegram", "whatsapp"].includes(host)) {
     return { rendered: false, mode: "chat-json", host };
   }
@@ -356,8 +356,8 @@ function formatActionTime(value) {
 
 function shouldUseAgentTextQR(flags = {}) {
   const mode = String(flags.display || process.env.ITP_DISPLAY || "").toLowerCase() || "auto";
-  const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
-  return mode === "chat" || mode === "agent" || (["gemini", "gemini-cli"].includes(host) && mode === "auto");
+  const host = agentHost(flags);
+  return mode === "chat" || mode === "agent" || (agentTextQRHosts().has(host) && mode === "auto");
 }
 
 function shouldReturnAfterAgentTextQR(flags = {}) {
@@ -365,6 +365,18 @@ function shouldReturnAfterAgentTextQR(flags = {}) {
   return shouldUseAgentTextQR(flags);
 }
 
+function agentHost(flags = {}) {
+  const explicit = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
+  if (explicit) return explicit;
+  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SHELL || process.env.CODEX_CI) return "codex";
+  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDECODE_SESSION_ID) return "claude-code";
+  return "";
+}
+
+function agentTextQRHosts() {
+  return new Set(["codex", "codex-cli", "claude", "claude-code", "gemini", "gemini-cli"]);
+}
+
 function attachAgentQRImage(action, qrImageURL, localPath = "") {
   if (!action || !qrImageURL) return action;
   action.preferred_qr_url = qrImageURL;

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -59,7 +59,7 @@ read this skill
 The high-level command can wrap this flow:
 
 ```bash
-itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --json
+itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
 ```
 
 For step-by-step testing:
@@ -93,7 +93,7 @@ itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input
 itp buyer cart show <cart_id> --json
 itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --json
 itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --sandbox --email <buyer_email> --input company_name=京东 --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --sandbox --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --json
 ```
 
 For cart edits, always read the server cart first with `buyer cart show`.
@@ -206,13 +206,16 @@ Each docs page includes `next_docs`. Follow those links as the state changes.
 For payment creation in an agent/chat client, prefer:
 
 ```bash
-itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --json
+itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
 ```
 
 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. If the
-human is on mobile, present `mobile_wallet_url` as a clickable human-only
-fallback; do not convert it into a QR.
+local QR image path for clients that cannot render remote SVG reliably. In
+Codex or Claude Code app clients, prefer `--no-wait-payment`: send
+`payment_handoff.markdown` to the human first, then run
+`payment_handoff.wait_command`. If the human is on mobile, present
+`mobile_wallet_url` as a clickable human-only fallback; do not convert it into a
+QR.
 
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first