@itpay/cli 0.2.14 → 0.2.15

package/README.md

@@ -158,9 +158,12 @@ Before starting a new purchase, agents should inspect recoverable local state:
 itp status --refresh --host <client> --json
 ```
 
-Every non-doc command needs a client context. Use `--host codex`,
-`--host claude-code`, `--host terminal`, or `--host plain-chat`. For OpenClaw
-Telegram private/group chat, use `--host telegram --target <inbound_meta.chat_id>`.
+Every non-doc command needs a client context. `--host` means the
+human-visible client/surface, not where the shell command runs. Use
+`--host codex` in Codex desktop chat even when you call `itp` through shell;
+use `--host terminal` only when the human is directly reading a terminal. For
+OpenClaw Telegram private/group chat, use
+`--host telegram --target <inbound_meta.chat_id>`.
 If the CLI returns `client_context_required` or `client_target_required`, rerun
 the same command with the requested fields.
 
@@ -247,7 +250,8 @@ 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, send root `agent_instruction.markdown` before any next ItPay command.
+- 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 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.
 - Treat only `payment_intent.verified` as payment success.
 

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

@@ -35,7 +35,7 @@
     }
   ],
   "agent_rules": [
-    "Every non-doc ItPay command must include current client context. Use --host codex/claude-code/terminal/plain-chat, or for OpenClaw Telegram use --host telegram --target <inbound_meta.chat_id>.",
+    "Every non-doc ItPay command must include current client context. Use --host codex/claude-code/terminal/plain-chat, or for OpenClaw Telegram use --host telegram --target <inbound_meta.chat_id>. --host is the human-visible client/surface, not where the shell command runs; in Codex desktop chat use --host codex even when calling itp through shell.",
     "If ItPay returns client_context_required or client_target_required, rerun the same command with the requested --host/--target before doing anything else.",
     "If human_action.kind is auth_qr, present the ItPay first-purchase entry URL/QR and explain it starts account login/registration/profile authorization and should continue to payment for the same checkout after approval.",
     "For auth_qr, the ItPay auth entry is the primary handoff. oauth_start_url is fallback/debug and should not replace the ItPay orchestration page.",
@@ -43,13 +43,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.",
-    "If response.agent_action is present, it is the mandatory execution path. Execute response.agent_action.command or response.agent_action.argv before any normal prose reply or next ItPay command.",
+    "If response.agent_action is present, it is the mandatory execution path. Execute it before any normal prose reply or next ItPay command: 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. Do not rebuild it, do not summarize it, and do not rewrite it into a custom table.",
-    "If response.agent_action cannot be executed, stop and tell the human this agent lacks OpenClaw native message-send capability. Do not fall back to Markdown.",
+    "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 handmade prose.",
     "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_instruction.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. Do not start a hidden long 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.",
@@ -60,7 +60,7 @@
     "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. Without an explicit short timeout, CLI returns payment_handoff_required instead of blocking.",
+    "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."
   ],
   "forbidden": [

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

@@ -36,12 +36,12 @@
   ],
   "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 response.agent_action.command or response.agent_action.argv before any later status check. If only response.agent_instruction is present, follow it exactly before any later status check.",
+    "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.",
     "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 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.",
+    "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.",
     "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

@@ -45,12 +45,12 @@
     {
       "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 --host <client> --json",
-      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; in OpenClaw Telegram, if agent_action is present, execute response.agent_action.command or response.agent_action.argv before any normal reply or payment status check"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if agent_action is present, execute it before any normal reply or payment status check"
     }
   ],
   "agent_rules": [
     "Use --json for every ItPay command.",
-    "Every non-doc ItPay command must include the current client context: --host codex, --host claude-code, --host terminal, --host plain-chat, or for OpenClaw/Telegram use --host telegram --target <inbound_meta.chat_id>.",
+    "Every non-doc ItPay command must include the current client context: --host codex, --host claude-code, --host terminal, --host plain-chat, or for OpenClaw/Telegram use --host telegram --target <inbound_meta.chat_id>. --host is the human-visible client/surface, not where the shell command runs; in Codex desktop chat use --host codex even when calling itp through shell.",
     "Do not rely on the CLI to guess Telegram, Discord, WhatsApp, Codex, or Claude Code. If ItPay returns client_context_required or client_target_required, rerun the same command with the required --host/--target fields before continuing.",
     "For Telegram group chat or @mention flows, pass the group/private chat target from OpenClaw inbound metadata, for example --target telegram:-1001234567890. ItPay only echoes the target into agent_action; OpenClaw owns group allowlist/mention policy.",
     "Use `itp status --refresh --host <client> --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
@@ -66,11 +66,11 @@
     "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.",
-    "If response.agent_action is present, it is the mandatory execution path for the current client. Execute response.agent_action.command or response.agent_action.argv before any normal prose reply.",
+    "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, stop and tell the human this agent lacks OpenClaw native message-send capability. Do not fall back to Markdown or handwritten prose.",
+    "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. Only after the human asks to check payment should you run after_human_response.check_payment_command.",
+    "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.",
     "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

@@ -1650,13 +1650,19 @@ function telegramAgentAction(commandArgs = {}) {
 function markdownBuyerInstruction(value = {}, flags = {}, platform = "codex_app", markdown = "") {
   const plan = value.render_plan || {};
   const summary = buyerOrderSummary(value, plan.kind);
+  const instruction = markdownBuyerInstructionText(platform);
   return handoffInstructionOutput(value, flags, {
     type: plan.kind === "auth_qr" ? "send_markdown_auth_handoff" : "send_markdown_payment_handoff",
     platform,
     proof_rule: plan.proof_rule,
-    instruction: "必须先把 markdown 原样发给用户；不要先运行 wait/status。只有 payment_intent.verified 才算付款成功。",
+    instruction,
     markdown
-  }, summary);
+  }, summary, {
+    instruction,
+    agent_action: markdownAgentAction(platform, markdown),
+    after_visible_action: afterVisibleAction(value, flags, summary),
+    agent_next_actions: ["send_agent_action_to_human"]
+  });
 }
 
 function plainChatBuyerInstruction(value = {}, flags = {}, selected = {}) {
@@ -1675,31 +1681,90 @@ function plainChatBuyerInstruction(value = {}, flags = {}, selected = {}) {
 function terminalBuyerInstruction(value = {}, flags = {}) {
   const plan = value.render_plan || {};
   const summary = buyerOrderSummary(value, plan.kind);
+  const instruction = "必须先执行 agent_action.command，让 CLI 在人类正在看的终端里打印二维码、链接和摘要；不要把 terminal 当成 Codex 桌面端。如果人类不是直接看这个终端，改用 --host codex 重跑。";
   return handoffInstructionOutput(value, flags, {
     type: plan.kind === "auth_qr" ? "terminal_auth_handoff" : "terminal_payment_handoff",
     platform: "terminal",
     proof_rule: plan.proof_rule,
-    instruction: "CLI 已负责终端展示；用户回复后再运行 after_human_response 里的命令。",
+    instruction,
     print_terminal_qr: true
-  }, summary);
+  }, summary, {
+    instruction,
+    agent_action: terminalAgentAction(summary, flags, plan.kind),
+    after_visible_action: afterVisibleAction(value, flags, summary),
+    agent_next_actions: ["execute_agent_action"]
+  });
 }
 
-function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {}, summary = {}) {
+function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {}, summary = {}, extra = {}) {
   return compactObject({
     status: value.status,
+    instruction: extra.instruction,
     must_send_to_human_before_next_command: true,
     order_summary: summary,
+    agent_action: extra.agent_action,
     agent_instruction: agentInstruction,
     after_human_response: genericAfterHumanResponse(value, flags, summary),
-    agent_next_actions: ["send_agent_instruction_to_human"],
+    after_visible_action: extra.after_visible_action,
+    agent_next_actions: extra.agent_next_actions || ["send_agent_instruction_to_human"],
     next: {
       type: "reply_to_human",
       safe_for_agent: false,
-      instruction: "先把 agent_instruction 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+      instruction: extra.next_instruction || "先把 agent_instruction 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
     }
   });
 }
 
+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 秒；如果不能确认，就停止等人类回复。`;
+}
+
+function markdownAgentAction(platform = "codex_app", markdown = "") {
+  const label = platform === "claude_code" ? "Claude Code app" : "Codex desktop app";
+  return {
+    type: "markdown_reply",
+    platform,
+    instruction: `现在立刻把 markdown 原样发送到当前聊天。${label} 可以用绝对路径 Markdown 图片显示本地二维码。不要只贴文件路径，不要先运行 wait/status。`,
+    markdown,
+    if_unavailable: "如果当前客户端不能让这段 Markdown 对人类可见，停止并说明无法展示二维码；不要先运行 wait/status。"
+  };
+}
+
+function terminalAgentAction(summary = {}, flags = {}, kind = "") {
+  const args = kind === "auth_qr" && summary.checkout_id
+    ? ["buyer", "checkout", "resume", summary.checkout_id, ...clientCommandArgs(flags), "--no-wait-auth"]
+    : summary.payment_intent_id
+      ? ["buyer", "payment", "wait", summary.payment_intent_id, ...clientCommandArgs(flags)]
+      : [];
+  if (!args.length) return undefined;
+  return {
+    type: "terminal_handoff_command",
+    tool: "shell",
+    instruction: "只有当人类直接看这个终端窗口时才执行。它会让 CLI 打印二维码和链接。若你在 Codex 桌面聊天里，请改用 --host codex 重跑原命令。",
+    command: cliCommand(...args),
+    if_unavailable: "如果不能确认人类正在看该终端，停止并用正确的 --host 重跑；不要把终端输出当成 Codex 桌面端回复。"
+  };
+}
+
+function afterVisibleAction(value = {}, flags = {}, summary = {}) {
+  if (summary.payment_intent_id) {
+    return {
+      optional: 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,
+      command: cliCommand("buyer", "checkout", "resume", summary.checkout_id, ...clientCommandArgs(flags), "--json"),
+      instruction: "只有在授权入口已经对人类可见后才能执行；继续同一个 checkout，不要新建 checkout。"
+    };
+  }
+  return undefined;
+}
+
 function buyerOrderSummary(value = {}, kind = "") {
   const cart = value.cart || {};
   const checkout = value.checkout || {};

package/lib/client-context.js

@@ -52,7 +52,7 @@ function clientContextRequired() {
     schema_version: "itp.client_context.v1",
     status: "client_context_required",
     must_rerun: true,
-    instruction: "Rerun the same itp command with --host <client>. ItPay will not guess the current chat/app client.",
+    instruction: "Rerun the same itp command with --host <client>. --host means the human-visible client/surface, not where the shell command runs. In Codex desktop chat use --host codex even when calling itp through shell; use --host terminal only when the human is directly reading a terminal.",
     allowed_hosts: Array.from(SUPPORTED_HOSTS),
     examples: {
       codex: "itp ... --host codex --json",
@@ -84,7 +84,7 @@ function unsupportedClientContext(host) {
     status: "unsupported_client_context",
     must_rerun: true,
     host,
-    instruction: "Use one supported --host value so ItPay can return a single executable human-output instruction.",
+    instruction: "Use one supported --host value so ItPay can return a single executable human-output instruction. --host means the human-visible client/surface, not the shell execution environment.",
     allowed_hosts: Array.from(SUPPORTED_HOSTS)
   };
 }

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -20,9 +20,12 @@ protocol from this file. Use the CLI docs graph whenever you need details.
 
 ## Start Here
 
-Every non-doc ItPay command must include the current client context. The CLI
-will stop with `client_context_required` or `client_target_required` rather
-than guess.
+Every non-doc ItPay command must include the current client context. `--host`
+means the human-visible client/surface, not where the shell command runs. In
+Codex desktop chat use `--host codex` even when calling `itp` through shell;
+use `--host terminal` only when the human is directly reading a terminal. The
+CLI will stop with `client_context_required` or `client_target_required`
+rather than guess.
 
 ```text
 Codex app:        --host codex
@@ -37,11 +40,11 @@ For Telegram groups or @mention flows, use the same OpenClaw inbound
 OpenClaw owns group allowlists and mention policy; ItPay only echoes the target
 into the returned `agent_action`.
 
-If a response contains `agent_action`, run `agent_action.command` or
-`agent_action.argv` before writing any normal reply. Do not summarize it, do
-not rewrite it as Markdown, and do not run wait/status first. If the command
-cannot run, stop and tell the human the agent lacks the required OpenClaw
-message tool.
+If a response contains `agent_action`, execute that action before writing any
+normal reply or running wait/status. For Telegram/terminal this may be
+`agent_action.command` or `agent_action.argv`; for Codex/Claude Code this may
+be `agent_action.markdown`, which must be sent exactly to the current chat.
+If the action cannot be made visible to the human, stop and say why.
 
 Run these commands before buying:
 
@@ -147,7 +150,7 @@ be unlocked again by the ItPay backend.
 
 ## Non-Negotiable Rules
 
-1. Use `--json` and current client context for every non-doc ItPay command. Use `--host codex`, `--host claude-code`, `--host terminal`, `--host plain-chat`, or for OpenClaw Telegram use `--host telegram --target <inbound_meta.chat_id>`.
+1. Use `--json` and current client context for every non-doc ItPay command. Use `--host codex`, `--host claude-code`, `--host terminal`, `--host plain-chat`, or for OpenClaw Telegram use `--host telegram --target <inbound_meta.chat_id>`. `--host` is the human-visible client, not the shell execution environment.
 2. Do not invent service IDs, variant IDs, checkout IDs, payment URLs, QR URLs,
    payment intent IDs, delivery IDs, or claim links.
 3. When the user asks for several compatible services, use one cart and one
@@ -234,18 +237,19 @@ 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
-agent/chat clients, prefer `--no-wait-payment`. In OpenClaw Telegram, if
-`agent_action` is present, execute `agent_action.command` or `agent_action.argv`
-exactly. It already contains `openclaw message send`, the chat target, QR
-media, exact human text, and `presentation.blocks[].type="buttons"` for
-Telegram native inline buttons. Do not rewrite it as a table or normal prose.
-In Codex or Claude Code app clients, send `agent_instruction.markdown` exactly
-before any next ItPay command.
+agent/chat clients, prefer `--no-wait-payment`. If `agent_action` is present,
+execute it exactly before normal prose. In OpenClaw Telegram it contains
+`openclaw message send`, the chat target, QR media, exact human text, and
+`presentation.blocks[].type="buttons"` for Telegram native inline buttons. In
+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 and asks to check status; then use
-`after_human_response.check_payment_command`.
+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.
 
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first