@itpay/cli 0.2.2 → 0.2.4

package/README.md

@@ -213,7 +213,7 @@ redacted secure delivery status:
 ```bash
 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@example.com --json
+itp buyer checkout create --cart <cart_id> --email <buyer_email> --json
 itp buyer payment wait <payment_intent_id> --json
 itp buyer checkout status <checkout_id> --json
 ```
@@ -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_email> --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 `human_visible_markdown` to the human first, then run `next.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,8 +93,8 @@ 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 --no-wait --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --display agent --no-wait-payment --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --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",
           "buyer cart create --variant var_pubg_couple_skin_cny20 --json",
@@ -105,7 +105,7 @@ async function main() {
           "buyer shelf manifest --json",
           "buyer shelf snapshot --version <catalog_version> --json",
           "buyer shelf delta --since <catalog_version> --json",
-          "buyer checkout create --cart <cart_id> --method alipay --email buyer@example.com --phone +8613800000000 --json",
+          "buyer checkout create --cart <cart_id> --method alipay --email <buyer_email> --phone +8613800000000 --json",
           "buyer checkout status <checkout_id> --json",
           "buyer checkout resume <checkout_id> --json",
           "buyer auth status --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> --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

@@ -8,7 +8,7 @@
     "Checkout returns human_action.kind=auth_qr for the first-purchase auth-to-payment entry.",
     "PaymentIntent has been created.",
     "The CLI returned human_action.kind=payment_qr, qr_png_url, preferred_qr_url, or qr_image_url.",
-    "The human needs to scan with Alipay sandbox."
+    "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"],
@@ -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> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "success_signal": "response.human_visible_markdown and response.next.command are present"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,14 +33,17 @@
     "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.",
+    "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.",
     "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.",
     "For mobile users, present mobile_wallet_url as a clickable payment button when present.",
     "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.",
+    "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 next.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.",
@@ -58,7 +61,7 @@
       "command": "itp docs show payment-wait --role buyer --json"
     },
     {
-      "condition": "Alipay sandbox says order not found after waiting on the same QR/page",
+      "condition": "the payment provider says order not found after waiting on the same QR/page",
       "topic": "qr-refresh",
       "command": "itp docs show qr-refresh --role buyer --json"
     }

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/qr-refresh.json

@@ -5,7 +5,7 @@
   "title": "QR Refresh Recovery",
   "purpose": "Teach the agent how to recover scanner problems without changing payment truth or creating a second order.",
   "when_to_use": [
-    "The human reports Alipay sandbox says order not found after waiting 30-60 seconds on the same QR/page.",
+    "The human reports the payment provider says order not found after waiting 30-60 seconds on the same QR/page.",
     "The QR expired or the wallet cannot load it.",
     "The payment intent is still not verified."
   ],
@@ -29,7 +29,7 @@
     "QR refresh is display recovery only. ItPay may return the same QR again when the current provider QR is still valid.",
     "Use the same payment_intent_id.",
     "If QR does not render, first use the returned local_qr_path, qr_png_url, or preferred_qr_url. Do not generate a new QR from guessed provider payload.",
-    "For Alipay sandbox order-not-found, first ask the human to wait and scan/open the same QR/page again; use refresh only after that wait has failed.",
+    "For provider order-not-found, first ask the human to wait and scan/open the same QR/page again; use refresh only after that wait has failed.",
     "If refresh succeeds, show only the returned ItPay QR/display URL and continue waiting on the same payment_intent_id.",
     "After refresh, continue waiting through the normal wait contract."
   ],

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> --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"
     }
   ],
   "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 human_visible_markdown, then run next.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.",
+    "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,17 +4,19 @@ 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) {
+  rejectBuyerSandboxFlag(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");
+  if (!selectionID) throw new Error("catalog variant id is required, for example: itp buy <variant_id> --email <buyer_email> --json");
   const selection = await resolveBuyerCatalogSelection(selectionID, flags);
   const cart = await createBuyerCart(selection, 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 +43,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 human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+      }
     }));
     return;
   }
@@ -75,6 +82,7 @@ async function buyerBuy(flags) {
 }
 
 async function buyer(command, rest, flags) {
+  rejectBuyerSandboxFlag(flags);
   const subcommand = rest[0] && !String(rest[0]).startsWith("--") ? rest[0] : "";
   if (command === "catalog") {
     if (subcommand === "search") {
@@ -312,8 +320,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 human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+              }
           }));
           return;
         }
@@ -326,7 +342,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 human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+          }
+        }));
         return;
       }
       output(buyerRunOutput({
@@ -367,11 +394,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 human_visible_markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
+        }
     }));
     return;
   }
@@ -792,7 +824,7 @@ async function createBuyerCheckoutFromCart(cart, selection = null, flags = {}) {
   const cartID = typeof cart === "string" ? cart : (cart?.cart_id || cart?.id);
   if (!cartID) throw new Error("cart_id is required");
   const deliveryContact = {};
-  if (flags.email) deliveryContact.email = flags.email;
+  if (flags.email) deliveryContact.email = realBuyerEmail(flags.email);
   if (flags.phone) deliveryContact.phone = flags.phone;
   const missing = requiredDeliveryContactFields(selection).filter((field) => !deliveryContact[field]);
   if (missing.length) {
@@ -831,6 +863,21 @@ function requiredDeliveryContactFields(selection) {
   return Array.isArray(fields) ? fields.map((field) => String(field).trim()).filter(Boolean) : [];
 }
 
+function rejectBuyerSandboxFlag(flags = {}) {
+  if (!flags?.sandbox) return;
+  throw new Error("--sandbox is not used by buyer commands; environment is selected by the ItPay API base. Run the command without --sandbox.");
+}
+
+function realBuyerEmail(value) {
+  const email = String(value || "").trim();
+  if (!email) return "";
+  const domain = email.split("@").pop().toLowerCase();
+  if (["example.com", "example.net", "example.org"].includes(domain)) {
+    throw new Error("placeholder email rejected; ask the human for their real delivery email before checkout.");
+  }
+  return email;
+}
+
 async function createBuyerPaymentIntent(checkoutID, flags = {}) {
   if (!checkoutID) throw new Error("checkout_id is required");
   const method = String(flags.method || flags.payment_method || "alipay").toLowerCase();
@@ -997,6 +1044,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 {
@@ -1294,7 +1384,7 @@ async function refreshBuyerPaymentQR(paymentIntentID, flags = {}) {
   if (intent.status === "verified") return intent;
   const refreshURL = intent.qr_refresh_url;
   if (!refreshURL) {
-    throw new Error("payment intent does not expose qr_refresh_url; refresh is supported only for refreshable Alipay sandbox QR intents");
+    throw new Error("payment intent does not expose qr_refresh_url; refresh is supported only for refreshable provider QR intents");
   }
   return await coreApi(refreshURL, {
     method: "POST",
@@ -1363,10 +1453,11 @@ function isBuyerDeliveryComplete(result) {
 }
 
 function buyerRunOutput(value = {}) {
+  const body = compactBuyerOutput(value);
   return normalizeBuyerMoneyFields(stripInternalBuyerFields({
     schema_version: "itp.buyer.v1",
+    ...body,
     docs: value.docs || buyerDocsFor(value),
-    ...value,
     secrets: {
       raw_content_included: false,
       claim_token_included: false,
@@ -1375,6 +1466,158 @@ function buyerRunOutput(value = {}) {
   }));
 }
 
+function compactBuyerOutput(value = {}) {
+  const result = {};
+  if (value.status !== undefined) result.status = value.status;
+  if (value.payment_handoff?.markdown) {
+    result.must_reply_to_human_before_next_command = true;
+    result.human_visible_markdown = value.payment_handoff.markdown;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (["docs", "status"].includes(key)) continue;
+    result[key] = compactBuyerField(key, item);
+  }
+  return result;
+}
+
+function compactBuyerField(key, value) {
+  if (key === "selection") return compactSelection(value);
+  if (key === "selections") return Array.isArray(value) ? value.map(compactSelection) : value;
+  if (key === "product") return compactProduct(value);
+  if (key === "products") return Array.isArray(value) ? value.map(compactProduct) : value;
+  if (key === "cart") return compactCart(value);
+  if (key === "checkout") return compactCheckout(value);
+  if (key === "payment_intent") return compactPaymentIntent(value);
+  return value;
+}
+
+function compactSelection(selection = {}) {
+  if (!selection || typeof selection !== "object") return selection;
+  return compactObject({
+    catalog_item_id: selection.catalog_item_id,
+    catalog_variant_id: selection.catalog_variant_id,
+    ucp_variant_id: selection.ucp_variant_id,
+    offer_id: selection.offer_id,
+    title: selection.title,
+    variant_title: selection.variant_title,
+    amount: selection.expected_amount,
+    currency: selection.currency,
+    required_contact_fields: selection.required_contact_fields,
+    purchasable: selection.purchasable
+  });
+}
+
+function compactProduct(product = {}) {
+  if (!product || typeof product !== "object") return product;
+  return compactObject({
+    id: product.id,
+    title: product.title,
+    description: product.description,
+    selected: product.selected,
+    variants: Array.isArray(product.variants) ? product.variants.map(compactVariant) : undefined
+  });
+}
+
+function compactVariant(variant = {}) {
+  const metadata = variant.metadata || {};
+  return compactObject({
+    id: variant.id,
+    title: variant.title,
+    description: variant.description,
+    price: variant.price,
+    availability: variant.availability,
+    required_profile_fields: metadata["ai.itpay.required_profile_fields"],
+    input_schema_json: metadata["ai.itpay.api.input_schema_json"],
+    agent_explanation_zh: metadata["ai.itpay.agent_explanation_zh"]
+  });
+}
+
+function compactCart(cart = {}) {
+  if (!cart || typeof cart !== "object") return cart;
+  return compactObject({
+    cart_id: cart.cart_id || cart.id,
+    status: cart.status,
+    amount: cart.amount,
+    currency: cart.currency,
+    line_items: Array.isArray(cart.line_items) ? cart.line_items.map(compactCartLine) : undefined
+  });
+}
+
+function compactCartLine(line = {}) {
+  return compactObject({
+    id: line.id,
+    quantity: line.quantity,
+    amount: line.amount,
+    currency: line.currency,
+    input: line.input,
+    item: line.item ? compactObject({
+      id: line.item.id,
+      title: line.item.title,
+      catalog_item_id: line.item.catalog_item_id,
+      catalog_variant_id: line.item.catalog_variant_id,
+      offer_id: line.item.offer_id
+    }) : undefined
+  });
+}
+
+function compactCheckout(checkout = {}) {
+  if (!checkout || typeof checkout !== "object") return checkout;
+  return compactObject({
+    checkout_id: checkout.checkout_id,
+    cart_id: checkout.cart_id,
+    order_id: checkout.order_id,
+    status: checkout.status,
+    delivery_status: checkout.delivery_status,
+    identity_status: checkout.identity_status,
+    next_required_action: checkout.next_required_action,
+    payment_intent_id: checkout.payment_intent_id,
+    amount: checkout.amount,
+    currency: checkout.currency,
+    delivery: checkout.delivery,
+    human_action: checkout.human_action,
+    agent_next_actions: checkout.agent_next_actions
+  });
+}
+
+function compactPaymentIntent(intent = {}) {
+  if (!intent || typeof intent !== "object") return intent;
+  return compactObject({
+    payment_intent_id: intent.payment_intent_id,
+    payment_attempt_id: intent.payment_attempt_id,
+    checkout_id: intent.checkout_id,
+    order_id: intent.order_id,
+    status: intent.status,
+    amount: intent.amount,
+    currency: intent.currency,
+    human_action: compactHumanAction(intent.human_action),
+    qr_png_url: intent.qr_png_url,
+    qr_image_url: intent.qr_image_url,
+    mobile_wallet_url: intent.mobile_wallet_url,
+    agent_wait: intent.agent_wait,
+    agent_next_actions: intent.agent_next_actions
+  });
+}
+
+function compactHumanAction(action = null) {
+  if (!action || typeof action !== "object") return action;
+  return compactObject({
+    kind: action.kind,
+    url: action.url,
+    local_qr_path: action.local_qr_path,
+    local_qr_mime: action.local_qr_mime,
+    qr_png_url: action.qr_png_url,
+    qr_image_url: action.qr_image_url,
+    preferred_qr_url: action.preferred_qr_url,
+    mobile_wallet_url: action.mobile_wallet_url,
+    agent_display_hint: action.agent_display_hint,
+    expires_at: action.expires_at
+  });
+}
+
+function compactObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null));
+}
+
 function normalizeBuyerMoneyFields(value) {
   if (Array.isArray(value)) return value.map((item) => normalizeBuyerMoneyFields(item));
   if (!value || typeof value !== "object") return value;

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/lib/runtime.js

@@ -448,7 +448,7 @@ async function maybeMockApproveDeviceAuth(authId, flags) {
     return;
   }
   if (!fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
+    throw new Error("mock approval is developer-only and disabled for agent runs; use real payment-provider authentication");
   }
   const alipayUserId = flags.alipay_user_id || process.env.ITPAY_MOCK_ALIPAY_USER_ID || `2088${crypto.randomInt(100000000000, 999999999999)}`;
   await api(`/api/itp/auth/device/${encodeURIComponent(authId)}/mock-approve`, {
@@ -692,10 +692,10 @@ async function createCheckoutResult(flags) {
 
 function validateLivePaymentFlags(method, flags = {}) {
   if (String(method).toLowerCase() === "fake" && !fakeTestingAllowed(flags)) {
-    throw new Error("fake payment is developer-only and disabled for agent runs; use --method alipay for local, sandbox, and live testing");
+    throw new Error("fake payment is developer-only and disabled for agent runs; use --method alipay for local and live testing");
   }
   if ((flags.mock_approve || process.env.ITPAY_MOCK_APPROVE === "true" || process.env.ITPAY_MOCK_APPROVE === "1") && !fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
+    throw new Error("mock approval is developer-only and disabled for agent runs; use real payment-provider authentication");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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> --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 --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,20 +206,23 @@ 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> --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
+`human_visible_markdown` to the human first, then run
+`next.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
 and then payment after ItPay receives the OAuth callback. Do not call
 `oauth_start_url` directly unless the ItPay auth page asks for fallback.
-If the payment page says the Alipay sandbox entry is stabilizing/preparing,
-or if Alipay sandbox says "order not found", tell the human to wait 30-60
+If the payment page says provider entry is stabilizing/preparing,
+or if the payment provider says "order not found", tell the human to wait 30-60
 seconds and use the same page/QR again. Do not ask them to refresh repeatedly,
 and do not create another checkout or payment intent. Use
 `itp buyer payment refresh-qr ... --reason order-not-found` only after the
@@ -235,7 +238,7 @@ I found the service and selected the matching variant.
 I created the cart and checkout.
 Please open the returned ItPay authorization link and approve Alipay login.
 I am waiting for ItPay account authorization.
-Please scan the returned ItPay-hosted QR image with Alipay sandbox.
+Please scan the returned ItPay-hosted QR image with the payment provider.
 I am waiting for ItPay payment verification.
 Payment is verified.
 Delivery is claimable by the human buyer. Please check your email.