@itpay/cli 0.2.15 → 0.2.16

package/README.md

@@ -250,9 +250,9 @@ Payment QR rules:
 - Do not generate your own QR from payment URLs.
 - In OpenClaw Telegram, run root `agent_action.command` or `agent_action.argv` before replying; do not simulate buttons in normal prose.
 - Telegram native buttons require `presentation.blocks[].type="buttons"` with `text/url/callback_data`.
-- For Codex/Claude Code app clients, send root `agent_action.markdown` before any next ItPay command. If you can confirm it is visible to the human, you may then run `after_visible_action.command`; if unsure, stop.
+- For Codex/Claude Code app clients, send root `agent_action.markdown` first; once it is visible in the current chat, run `after_visible_action.command` once by default. Stop only if visibility is uncertain.
 - For terminal clients, run root `agent_action.command` only when the human is directly watching that terminal. Do not use `--host terminal` merely because you invoke `itp` through shell.
-- If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
+- If status is `payment_handoff_required`, follow `next.type`: Codex/Claude app clients normally send-to-human then wait once; plain chat stops for the human.
 - Treat only `payment_intent.verified` as payment success.
 
 If the human wants the agent to analyze delivered content, the human must reveal

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

@@ -49,10 +49,10 @@
     "response.agent_instruction is natural-language reinforcement for the agent; it does not replace response.agent_action.",
     "Telegram native buttons require openclaw message send --presentation; presentation.blocks[].type=\"buttons\" uses native text/url/callback_data. Do not simulate buttons in normal prose.",
     "If agent_instruction links/buttons include URLs, include the real URL. Do not only show the link label.",
-    "In Codex or Claude Code app clients, send response.agent_action.markdown first. Do not start a hidden long wait before the human-visible message is sent.",
+    "In Codex or Claude Code app clients, send response.agent_action.markdown first. Once it is visible in the current chat, immediately run response.after_visible_action.command once; do not start a hidden wait before the human-visible message is sent.",
     "For Telegram-style message clients, send photo media first, include links, and expose native buttons for refresh/status when the adapter supports them.",
     "For plain chat clients, show response.agent_instruction.message/links 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.",
+    "When response.status is payment_handoff_required, response.next describes the current client handoff. For Codex/Claude Code, send the markdown and then run after_visible_action once if visible; for plain chat, stop for the human.",
     "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.",
@@ -60,8 +60,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 after_visible_action.command exists and you can confirm the handoff is visible, you may run it once; if unsure, stop and wait for the human.",
-    "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."
+    "Do not run payment wait before the QR/link has been sent to the human. If response.after_visible_action.command exists and you can confirm the handoff is visible, run it once by default; if unsure, stop and wait for the human.",
+    "If response.after_visible_action was not run, or after the human says they paid/clicks a platform status button later, 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.",

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

@@ -37,11 +37,11 @@
   "agent_rules": [
     "Every payment wait/status command must include the same client context as the handoff command. For OpenClaw Telegram, keep --host telegram --target <same chat_id>.",
     "If payment wait returns payment_handoff_required with response.agent_action, execute it before any later status check: command/argv for Telegram or terminal, markdown for Codex/Claude Code app clients. If only response.agent_instruction is present, follow it exactly before 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.",
+    "Start payment status checks only after the QR image/link has already been sent to the human. In Codex/Claude Code app clients, after_visible_action.command is the default one-round status check once the handoff is visible.",
     "If you run payment wait without a short timeout while payment is still pending, CLI returns payment_handoff_required and the human handoff instruction 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, use after_visible_action.command only if you can confirm the QR/link is visible. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",
+    "In Codex or Claude Code app clients, after showing QR and confirming it is visible, run after_visible_action.command once. If it times out, explain that the same QR/link remains valid and pause for the human or continue only if they ask.",
     "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.",

package/docs/agent/buyer/quickstart.json

@@ -65,12 +65,12 @@
     "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 send the human handoff instruction, then only check status after the human responds or uses a platform button.",
+    "Use high-level itp buy when possible. In Codex/Claude Code app clients, the default payment flow is one round: send response.agent_action.markdown to the current chat, then immediately run response.after_visible_action.command once if the QR/link is visible.",
     "If response.agent_action is present, it is the mandatory execution path for the current client. Execute it before any normal prose reply: command/argv for Telegram or terminal, markdown for Codex/Claude Code app clients.",
     "In OpenClaw Telegram, response.agent_action is already the exact openclaw message send command. It includes target, QR media, exact message, and native button presentation.",
     "If response.agent_action cannot be executed or made visible to the human, stop and tell the human what capability is missing. Do not fall back to handwritten prose.",
     "response.agent_instruction is natural-language reinforcement for the agent; it does not replace response.agent_action.",
-    "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. If after_visible_action.command exists and you can confirm the handoff is visible, you may run it once; if unsure, stop and wait for the human.",
+    "If response.status is payment_handoff_required, do not run payment wait before the QR/link is visible. If response.next.type is send_to_human_then_wait_once_if_visible, send agent_action first, then run after_visible_action.command once. Stop only when visibility is uncertain.",
     "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

@@ -1155,14 +1155,14 @@ function isTelegramBuyerHost(flags = {}) {
 }
 
 function paymentHandoffAgentNextActions() {
-  return ["send_agent_instruction_to_human"];
+  return ["send_agent_instruction_to_human", "run_after_visible_action_once_if_visible"];
 }
 
 function paymentHandoffNext() {
   return {
-    type: "reply_to_human",
-    safe_for_agent: false,
-    instruction: "Send agent_instruction to the human now. Do not run payment wait until this message is visible to the human."
+    type: "send_to_human_then_wait_once_if_visible",
+    safe_for_agent: true,
+    instruction: "Send agent_instruction to the human first. If it is visible, run after_visible_action once; otherwise stop and wait for the human."
   };
 }
 
@@ -1659,9 +1659,16 @@ function markdownBuyerInstruction(value = {}, flags = {}, platform = "codex_app"
     markdown
   }, summary, {
     instruction,
+    preferred_flow: "send_agent_action_then_wait_once",
     agent_action: markdownAgentAction(platform, markdown),
     after_visible_action: afterVisibleAction(value, flags, summary),
-    agent_next_actions: ["send_agent_action_to_human"]
+    after_human_response_fallback: true,
+    agent_next_actions: ["send_agent_action_to_human", "run_after_visible_action_once_if_visible"],
+    next: {
+      type: "send_to_human_then_wait_once_if_visible",
+      safe_for_agent: true,
+      instruction: "先把 agent_action.markdown 原样发到当前聊天；确认二维码、摘要和链接可见后，立刻执行 after_visible_action.command 等一次。只有无法确认可见时才停下等人类。"
+    }
   });
 }
 
@@ -1690,24 +1697,37 @@ function terminalBuyerInstruction(value = {}, flags = {}) {
     print_terminal_qr: true
   }, summary, {
     instruction,
+    preferred_flow: "execute_agent_action_then_wait_once",
     agent_action: terminalAgentAction(summary, flags, plan.kind),
     after_visible_action: afterVisibleAction(value, flags, summary),
-    agent_next_actions: ["execute_agent_action"]
+    after_human_response_fallback: true,
+    agent_next_actions: ["execute_agent_action", "run_after_visible_action_once_if_visible"],
+    next: {
+      type: "execute_terminal_handoff_then_wait_once_if_visible",
+      safe_for_agent: true,
+      instruction: "先执行 agent_action.command，让人类正在看的终端显示二维码和链接；确认可见后，立刻执行 after_visible_action.command 等一次。若人类不是直接看终端，停止并用正确 --host 重跑。"
+    }
   });
 }
 
 function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {}, summary = {}, extra = {}) {
+  const afterHumanResponse = genericAfterHumanResponse(value, flags, summary);
+  if (extra.after_human_response_fallback) {
+    afterHumanResponse.fallback = true;
+    afterHumanResponse.instruction = "Fallback only: use check_status_command when after_visible_action was not run, or when the human later replies/clicks status. User text is not proof.";
+  }
   return compactObject({
     status: value.status,
     instruction: extra.instruction,
     must_send_to_human_before_next_command: true,
+    preferred_flow: extra.preferred_flow,
     order_summary: summary,
     agent_action: extra.agent_action,
     agent_instruction: agentInstruction,
-    after_human_response: genericAfterHumanResponse(value, flags, summary),
     after_visible_action: extra.after_visible_action,
+    after_human_response: afterHumanResponse,
     agent_next_actions: extra.agent_next_actions || ["send_agent_instruction_to_human"],
-    next: {
+    next: extra.next || {
       type: "reply_to_human",
       safe_for_agent: false,
       instruction: extra.next_instruction || "先把 agent_instruction 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
@@ -1717,7 +1737,7 @@ function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {},
 
 function markdownBuyerInstructionText(platform = "codex_app") {
   const label = platform === "claude_code" ? "Claude Code app" : "Codex desktop app";
-  return `你在 ${label}。必须先把顶层 agent_action.markdown 原样发到当前聊天，让人类真正看到二维码、订单摘要和链接；不要因为你用 shell 跑 itp 就改用 --host terminal。发出后，如果你能确认消息已经对人类可见，可以继续执行 after_visible_action.command 等 30 秒；如果不能确认，就停止等人类回复。`;
+  return `你在 ${label}。必须先把顶层 agent_action.markdown 原样发到当前聊天，让人类真正看到二维码、订单摘要和链接；不要因为你用 shell 跑 itp 就改用 --host terminal。发出后，如果你能确认消息已经对人类可见，默认立刻执行 after_visible_action.command 等 30 秒；只有不能确认可见时才停止等人类回复。`;
 }
 
 function markdownAgentAction(platform = "codex_app", markdown = "") {
@@ -1750,14 +1770,14 @@ function terminalAgentAction(summary = {}, flags = {}, kind = "") {
 function afterVisibleAction(value = {}, flags = {}, summary = {}) {
   if (summary.payment_intent_id) {
     return {
-      optional: true,
+      recommended: true,
       command: cliCommand("buyer", "payment", "wait", summary.payment_intent_id, "--timeout", "30", ...clientCommandArgs(flags), "--json"),
       instruction: "只有在二维码、订单摘要和链接已经对人类可见后才能执行。用户说已付款不算证明，只有 payment_intent.verified 算付款成功。"
     };
   }
   if (summary.checkout_id) {
     return {
-      optional: true,
+      recommended: true,
       command: cliCommand("buyer", "checkout", "resume", summary.checkout_id, ...clientCommandArgs(flags), "--json"),
       instruction: "只有在授权入口已经对人类可见后才能执行；继续同一个 checkout，不要新建 checkout。"
     };

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -245,11 +245,11 @@ Codex or Claude Code app clients, send `agent_action.markdown` exactly to the
 current chat. In terminal, run `agent_action.command` only when the human is
 directly watching that terminal.
 
-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 human
-has seen the QR/link. If `after_visible_action.command` exists and you can
-confirm the handoff is visible, you may run it once; if unsure, stop and wait
-for the human.
+If a response has `status=payment_handoff_required`, follow `next.type`.
+For Codex/Claude Code app clients, send `agent_action.markdown` first; once it
+is visible in the current chat, run `after_visible_action.command` once by
+default. Do not run payment wait before the human-visible QR/link is sent. If
+visibility is uncertain, stop and wait for the human.
 
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first