@itpay/cli 0.2.12 → 0.2.14

package/docs/agent/buyer/quickstart.json

@@ -24,7 +24,7 @@
   "commands": [
     {
       "intent": "verify whether this agent/device already has a server-valid buyer session",
-      "command": "itp status --refresh --json",
+      "command": "itp status --refresh --host <client> --json",
       "success_signal": "response.status is idle when authenticated, or response.next.command tells the agent how to start human auth; if response.recoverable_context.found is true, compare it with the current user intent before continuing or ignoring it"
     },
     {
@@ -34,23 +34,26 @@
     },
     {
       "intent": "search the public catalog for the current user request",
-      "command": "itp buyer catalog search --query \"<user request>\" --json",
+      "command": "itp buyer catalog search --query \"<user request>\" --host <client> --json",
       "success_signal": "response.products contains public services and purchase options; response.catalog_guidance tells the agent how to compare and when to ask the human"
     },
     {
       "intent": "search standardized API services with category/facet filters when intent is clear",
-      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --json",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --host <client> --json",
       "success_signal": "response.products are narrowed by category/facet before recommendation"
     },
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
-      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; in OpenClaw Telegram, if agent_instruction is present, send response.agent_instruction.openclaw_message.command_args before any payment status check"
+      "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"
     }
   ],
   "agent_rules": [
     "Use --json for every ItPay command.",
-    "Use `itp status --refresh --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
+    "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>.",
+    "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.",
     "If `status --refresh` returns `recoverable_context.found=true`, do not blindly resume or blindly ignore it. Decide whether the old task is related to the current user intent; continue related tasks, ignore clearly unrelated tasks, and ask the human when unsure.",
     "If the catalog is unclear, read catalog-search docs and use buyer shelf manifest/snapshot as the shopping-list view before guessing keywords.",
     "Search and explain purchase options before buying unless the user already named a purchase option ID.",
@@ -63,12 +66,15 @@
     "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.",
-    "In OpenClaw Telegram, if response.agent_instruction is present, call openclaw message send with response.agent_instruction.openclaw_message.command_args. It includes the QR media, exact message, and native button presentation.",
+    "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.",
+    "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.",
+    "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.",
     "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.",
-    "For OpenClaw Telegram, root agent_instruction is the execution path. Do not use handwritten prose when agent_instruction.openclaw_message.command_args is present."
+    "For OpenClaw Telegram, root agent_action is the execution path. Do not use handwritten prose when agent_action is present."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/docs/agent/buyer/recovery.json

@@ -11,23 +11,29 @@
     "Checkout or delivery is pending."
   ],
   "required_state": {
-    "needs": ["last known checkout_id, payment_intent_id, or variant_id"],
-    "must_not_need": ["ops token", "provider raw payload", "claim token"]
+    "needs": [
+      "last known checkout_id, payment_intent_id, or variant_id"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider raw payload",
+      "claim token"
+    ]
   },
   "commands": [
     {
       "intent": "resume checkout state",
-      "command": "itp buyer checkout resume <checkout_id> --json",
+      "command": "itp buyer checkout resume <checkout_id> --host <client> --json",
       "success_signal": "response.status and agent_next_actions describe the safe next action"
     },
     {
       "intent": "wait again on the same payment intent",
-      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
     },
     {
       "intent": "refresh display QR only",
-      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --host <client> --json",
       "success_signal": "response.payment_intent.qr_image_url is present"
     }
   ],
@@ -62,5 +68,18 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["recover", "resume", "timeout", "lost", "retry", "stuck", "恢复", "重试", "卡住", "没返回", "断了", "找不到"]
+  "search_terms": [
+    "recover",
+    "resume",
+    "timeout",
+    "lost",
+    "retry",
+    "stuck",
+    "恢复",
+    "重试",
+    "卡住",
+    "没返回",
+    "断了",
+    "找不到"
+  ]
 }

package/docs/agent/buyer/safety-policy.json

@@ -10,8 +10,13 @@
     "The agent is deciding between buyer and ops commands."
   ],
   "required_state": {
-    "needs": ["role=buyer"],
-    "must_not_need": ["ops token", "raw secret access"]
+    "needs": [
+      "role=buyer"
+    ],
+    "must_not_need": [
+      "ops token",
+      "raw secret access"
+    ]
   },
   "commands": [
     {
@@ -52,5 +57,14 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["policy", "forbidden", "security", "secret", "ops", "安全", "禁止", "权限"]
+  "search_terms": [
+    "policy",
+    "forbidden",
+    "security",
+    "secret",
+    "ops",
+    "安全",
+    "禁止",
+    "权限"
+  ]
 }

package/docs/agent/buyer/secure-delivery.json

@@ -10,23 +10,30 @@
     "The user asks where the purchased key/content is."
   ],
   "required_state": {
-    "needs": ["checkout_id"],
-    "must_not_need": ["claim token", "claim link", "raw key", "storage ref"]
+    "needs": [
+      "checkout_id"
+    ],
+    "must_not_need": [
+      "claim token",
+      "claim link",
+      "raw key",
+      "storage ref"
+    ]
   },
   "commands": [
     {
       "intent": "check redacted delivery status",
-      "command": "itp buyer checkout status <checkout_id> --json",
+      "command": "itp buyer checkout status <checkout_id> --host <client> --json",
       "success_signal": "delivery.sensitive_content_redacted == true"
     },
     {
       "intent": "list agent-safe delivery state",
-      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.deliveries contains no raw content or claim token"
     },
     {
       "intent": "after the human says they granted agent access, discover the current agent's grants",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants contains only grants for this exact agent device"
     }
   ],
@@ -68,5 +75,16 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["delivery", "claim", "email", "key", "redeem", "secure delivery", "交付", "邮件", "领取", "密钥"]
+  "search_terms": [
+    "delivery",
+    "claim",
+    "email",
+    "key",
+    "redeem",
+    "secure delivery",
+    "交付",
+    "邮件",
+    "领取",
+    "密钥"
+  ]
 }

package/docs/agent/buyer/vault-agent-read.json

@@ -10,35 +10,45 @@
     "A checkout/order has delivered a vault artifact and the human granted agent-readable access."
   ],
   "required_state": {
-    "needs": ["checkout_id or authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
-    "must_not_need": ["human portal token", "claim token", "passkey credential", "raw protected payload", "grant id copied by the human"]
+    "needs": [
+      "checkout_id or authenticated buyer account session",
+      "current agent device binding",
+      "order_id or checkout_id or vault_artifact_id"
+    ],
+    "must_not_need": [
+      "human portal token",
+      "claim token",
+      "passkey credential",
+      "raw protected payload",
+      "grant id copied by the human"
+    ]
   },
   "commands": [
     {
       "intent": "check whether this agent has active human-approved grants for a checkout",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants is an array; count > 0 means the human has granted this exact agent access"
     },
     {
       "intent": "check whether this agent has active human-approved grants for one order or artifact",
-      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "only grants scoped to this logged-in agent device are returned"
     },
     {
       "intent": "read a discovered grant view",
-      "command": "itp buyer vault grants read <agent_read_grant_id> --json",
+      "command": "itp buyer vault grants read <agent_read_grant_id> --host <client> --json",
       "success_signal": "response.grant contains selected_fields, structured_view, or summary according to the human-approved scope"
     },
     {
       "intent": "convenience read by order/artifact without asking the human for grant id",
-      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "the CLI discovers the active grant and reads its scoped view"
     }
   ],
   "agent_rules": [
     "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
-    "Prefer `itp buyer vault grants list --checkout <checkout_id> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
-    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
+    "Prefer `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
+    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --host <client> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
     "Do not ask the human to copy or paste `agent_read_grant_id`; discover it with `buyer vault grants list`.",
     "If no grant is returned, tell the human to open their ItPay account portal, reveal with Passkey, choose fields, and confirm one-key agent authorization.",
     "If no grant is returned, explain likely causes: the human has not authorized yet, selected the wrong order/page, authorization has not synced yet, checkout/order/artifact does not match, buyer session expired, or the grant expired/revoked.",
@@ -46,7 +56,7 @@
     "Use only fields returned in the grant view. Do not infer that unreturned fields are accessible.",
     "When a grant view is returned, tell the user which fields are readable. If expires_at, ttl, or valid_until is present, tell the user the time limit; if no expiry is returned, say the response did not include an explicit expiry.",
     "If the returned fields are not enough for the user's task, ask the human to reopen Give to Agent and add the needed fields. Do not ask them to paste the missing raw content.",
-    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
+    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --host <client> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
   ],
   "forbidden": [
     "Do not open, click through, scrape, or automate the human web UI yourself.",
@@ -72,5 +82,14 @@
       "command": "itp docs show safety-policy --role buyer --json"
     }
   ],
-  "search_terms": ["vault", "agent read", "passkey grant", "one key agent", "授权给 agent", "可读授权", "字段授权", "查看报告"]
+  "search_terms": [
+    "vault",
+    "agent read",
+    "passkey grant",
+    "one key agent",
+    "授权给 agent",
+    "可读授权",
+    "字段授权",
+    "查看报告"
+  ]
 }

package/lib/buyer.js

@@ -1,10 +1,11 @@
 import {
   appendURLQuery, booleanFlag, cliCommand, cryptoRandom, csvValues, deleteSessionCredential, intFlag, output, positional, readConfig, readCredentials,
   readSessionToken, readState, safeErrorMessage, sleep, splitCSV, stripInternalBuyerFields, updateRun, writeConfig,
-  writeCredentials, writeSessionCredentials, writeState
+  writeCredentials, writeSessionCredentials, writeState, shellQuote
 } from "./env.js";
+import { clientCommandArgs, clientHost, clientTarget } from "./client-context.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { buildHumanActionRenderPlan, humanOutputFromRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -395,7 +396,7 @@ async function buyer(command, rest, flags) {
       agent_next_actions: event.agent_next_actions || intent.agent_next_actions || paymentAgentNextActions(intent, event),
       next: event.event_type === "payment_intent.verified"
         ? { command: intent.checkout_id ? cliCommand("buyer", "checkout", "status", intent.checkout_id, "--json") : undefined, safe_for_agent: true }
-        : { command: paymentStatusCheckCommand(paymentIntentID), safe_for_agent: true }
+        : { command: paymentStatusCheckCommand(paymentIntentID, flags), safe_for_agent: true }
     }));
     return;
   }
@@ -1093,49 +1094,14 @@ function paymentAgentNextActions(intent = {}, event = {}) {
 
 function paymentHandoffFields(intent = {}, flags = {}) {
   return {
-    payment_handoff: paymentHandoff(intent),
     render_plan: buildHumanActionRenderPlan(intent.human_action || {}, intent, flags),
-    after_human_response: paymentHandoffAfterHumanResponse(intent)
+    after_human_response: paymentHandoffAfterHumanResponse(intent, flags)
   };
 }
 
-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 || "";
-  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 }),
-    safe_for_agent: true,
-    instruction: "Render the QR/link to the human first. After the human responds or uses a platform button, query the same payment_intent_id. Only payment_intent.verified proves payment."
-  };
-}
-
-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("付款后回复“我已付款”，我会查询真实支付状态。");
-  return lines.join("\n\n");
-}
-
-function paymentStatusCheckCommand(paymentIntentID) {
+function paymentStatusCheckCommand(paymentIntentID, flags = {}) {
   if (!paymentIntentID) return "";
-  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", "--json");
+  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", ...clientCommandArgs(flags), "--json");
 }
 
 function shouldReturnPaymentHandoffBeforeWait(flags = {}) {
@@ -1185,36 +1151,26 @@ async function optionalBuyerPaymentContext(intent = {}, flags = {}) {
 }
 
 function isTelegramBuyerHost(flags = {}) {
-  const raw = String(
-    process.env.ITP_HOST ||
-    flags.host ||
-    flags.channel ||
-    process.env.OPENCLAW_CURRENT_CHANNEL_PROVIDER ||
-    process.env.OPENCLAW_CHANNEL ||
-    process.env.CURRENT_CHANNEL_PROVIDER ||
-    process.env.AGENT_CHANNEL ||
-    ""
-  ).toLowerCase().replaceAll("-", "_");
-  return raw === "telegram" || raw === "tg";
+  return clientHost(flags) === "telegram";
 }
 
 function paymentHandoffAgentNextActions() {
-  return ["show_human_visible_markdown"];
+  return ["send_agent_instruction_to_human"];
 }
 
 function paymentHandoffNext() {
   return {
     type: "reply_to_human",
     safe_for_agent: false,
-    instruction: "Send human_visible_markdown to the human now. Do not run payment wait until this message is visible to the human."
+    instruction: "Send agent_instruction to the human now. Do not run payment wait until this message is visible to the human."
   };
 }
 
-function paymentHandoffAfterHumanResponse(intent = {}) {
+function paymentHandoffAfterHumanResponse(intent = {}, flags = {}) {
   const paymentIntentID = intent.payment_intent_id || intent.human_action?.id || "";
   return {
-    check_payment_command: paymentStatusCheckCommand(paymentIntentID),
-    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", "--json") : "",
+    check_payment_command: paymentStatusCheckCommand(paymentIntentID, flags),
+    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", ...clientCommandArgs(flags), "--json") : "",
     safe_for_agent: true,
     instruction: "Use check_payment_command after the human says they paid or a platform button requests a status check. User text is not proof; only payment_intent.verified is."
   };
@@ -1586,8 +1542,8 @@ function isBuyerDeliveryComplete(result) {
     checkout.agent_next_actions?.includes("stop_check_email");
 }
 
-function buyerRunOutput(value = {}) {
-  const body = compactBuyerOutput(value);
+function buyerRunOutput(value = {}, flags = {}) {
+  const body = compactBuyerOutput(value, flags);
   return normalizeBuyerMoneyFields(stripInternalBuyerFields({
     schema_version: "itp.buyer.v1",
     ...body,
@@ -1600,21 +1556,11 @@ function buyerRunOutput(value = {}) {
   }));
 }
 
-function compactBuyerOutput(value = {}) {
-  const telegramInstruction = telegramBuyerInstruction(value);
-  if (telegramInstruction) return telegramInstruction;
+function compactBuyerOutput(value = {}, flags = {}) {
+  const clientInstruction = clientBuyerInstruction(value, flags);
+  if (clientInstruction) return clientInstruction;
   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;
-  }
-  const humanOutput = humanOutputFromRenderPlan(value.render_plan);
-  if (humanOutput) {
-    result.human_output_required = true;
-    result.must_send_human_output_before_next_command = true;
-    result.human_output = humanOutput;
-  }
   for (const [key, item] of Object.entries(value)) {
     if (["docs", "status"].includes(key)) continue;
     result[key] = compactBuyerField(key, item);
@@ -1622,7 +1568,20 @@ function compactBuyerOutput(value = {}) {
   return result;
 }
 
-function telegramBuyerInstruction(value = {}) {
+function clientBuyerInstruction(value = {}, flags = {}) {
+  const plan = value.render_plan || {};
+  const selected = plan.selected || {};
+  if (!plan.kind || !selected.platform) return null;
+  if (selected.platform === "telegram" && selected.openclaw_message) return telegramBuyerInstruction(value, flags);
+  if ((selected.platform === "codex_app" || selected.platform === "claude_code") && selected.markdown) {
+    return markdownBuyerInstruction(value, flags, selected.platform, selected.markdown);
+  }
+  if (selected.platform === "plain_chat") return plainChatBuyerInstruction(value, flags, selected);
+  if (selected.platform === "terminal") return terminalBuyerInstruction(value, flags);
+  return null;
+}
+
+function telegramBuyerInstruction(value = {}, flags = {}) {
   const plan = value.render_plan || {};
   const selected = plan.selected || {};
   if (selected.platform !== "telegram" || !selected.openclaw_message) return null;
@@ -1633,33 +1592,110 @@ function telegramBuyerInstruction(value = {}) {
   const hasHumanEntry = Boolean(media || presentation.blocks?.some((block) => block.type === "buttons" && block.buttons?.some((button) => button.url)));
   const text = telegramBuyerInstructionText(plan.kind, summary, hasHumanEntry);
   const callbacks = rawMessage.callbacks || {};
+  const commandArgs = compactObject({
+    channel: "telegram",
+    target: clientTarget(flags) || undefined,
+    message: text,
+    media: media || undefined,
+    presentation
+  });
+  const action = telegramAgentAction(commandArgs);
+  const instruction = "必须先执行顶层 agent_action.command 或 agent_action.argv，把二维码、说明和 Telegram 原生按钮发给用户。不要手写 Markdown 表格，不要只贴链接，不要先运行 wait/status；如果不能执行 openclaw message send，就停止并说明工具缺失。";
   return compactObject({
     status: value.status,
+    instruction,
     must_send_to_human_before_next_command: true,
+    must_execute_agent_action_before_reply: true,
     order_summary: summary,
+    agent_action: action,
     agent_instruction: {
       type: plan.kind === "auth_qr" ? "send_telegram_auth_handoff" : "send_telegram_payment_handoff",
       platform: "telegram",
       proof_rule: plan.proof_rule,
-      instruction: "必须使用 openclaw_message.command_args 发送给用户。不要用自然语言伪造按钮，不要先运行 wait/status。只有 payment_intent.verified 才算付款成功。",
+      instruction,
       openclaw_message: {
         command: "openclaw message send",
-        command_args: compactObject({
-          channel: "telegram",
-          message: text,
-          media: media || undefined,
-          presentation
-        }),
+        command_args: commandArgs,
         telegram_rule: "Telegram 原生按钮必须通过 openclaw message send --presentation 发送；presentation.blocks[].type=\"buttons\" 才会生成 Inline Keyboard。",
         callbacks
       }
     },
     after_human_response: telegramAfterHumanResponse(value, callbacks),
+    agent_next_actions: ["execute_agent_action"],
+    next: {
+      type: "reply_to_human",
+      safe_for_agent: false,
+      instruction: "先执行 agent_action.command/argv；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+    }
+  });
+}
+
+function telegramAgentAction(commandArgs = {}) {
+  const argv = ["openclaw", "message", "send"];
+  if (commandArgs.channel) argv.push("--channel", commandArgs.channel);
+  if (commandArgs.target) argv.push("--target", commandArgs.target);
+  if (commandArgs.message) argv.push("--message", commandArgs.message);
+  if (commandArgs.media) argv.push("--media", commandArgs.media);
+  if (commandArgs.presentation) argv.push("--presentation", JSON.stringify(commandArgs.presentation));
+  return {
+    type: "openclaw_message_send",
+    tool: "shell",
+    instruction: "现在立刻执行这个 shell 命令发送 Telegram 原生消息；不要改写为普通聊天回复。执行成功后再简短告诉用户已发出。",
+    command: argv.map((item) => shellQuote(String(item))).join(" "),
+    argv,
+    if_unavailable: "如果当前 agent 不能执行 openclaw message send，停止并告诉用户：当前 agent 缺少 Telegram 原生按钮发送工具；不要降级成 Markdown 表格或普通链接。"
+  };
+}
+
+function markdownBuyerInstruction(value = {}, flags = {}, platform = "codex_app", markdown = "") {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  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 才算付款成功。",
+    markdown
+  }, summary);
+}
+
+function plainChatBuyerInstruction(value = {}, flags = {}, selected = {}) {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  return handoffInstructionOutput(value, flags, {
+    type: plan.kind === "auth_qr" ? "send_plain_auth_handoff" : "send_plain_payment_handoff",
+    platform: "plain_chat",
+    proof_rule: plan.proof_rule,
+    instruction: "把 message 和 links 发给用户后停下，等用户回复再查状态。",
+    message: selected.text,
+    links: selected.links || []
+  }, summary);
+}
+
+function terminalBuyerInstruction(value = {}, flags = {}) {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  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 里的命令。",
+    print_terminal_qr: true
+  }, summary);
+}
+
+function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {}, summary = {}) {
+  return compactObject({
+    status: value.status,
+    must_send_to_human_before_next_command: true,
+    order_summary: summary,
+    agent_instruction: agentInstruction,
+    after_human_response: genericAfterHumanResponse(value, flags, summary),
     agent_next_actions: ["send_agent_instruction_to_human"],
     next: {
       type: "reply_to_human",
       safe_for_agent: false,
-      instruction: "先把 agent_instruction.openclaw_message.command_args 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+      instruction: "先把 agent_instruction 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
     }
   });
 }
@@ -1758,6 +1794,19 @@ function telegramAfterHumanResponse(value = {}, callbacks = {}) {
   });
 }
 
+function genericAfterHumanResponse(value = {}, flags = {}, summary = {}) {
+  const paymentIntentID = summary.payment_intent_id;
+  const checkoutID = summary.checkout_id;
+  return compactObject({
+    check_status_command: value.after_human_response?.check_payment_command ||
+      (paymentIntentID ? paymentStatusCheckCommand(paymentIntentID, flags) : undefined) ||
+      (checkoutID ? cliCommand("buyer", "checkout", "resume", checkoutID, ...clientCommandArgs(flags), "--json") : undefined),
+    refresh_qr_command: value.after_human_response?.refresh_qr_command,
+    help_command: cliCommand("docs", "show", "payment-qr", "--role", "buyer", "--json"),
+    instruction: "用户点击查询按钮或回复已完成后，运行 check_status_command。用户口头说已付款不是证明。"
+  });
+}
+
 function compactBuyerField(key, value) {
   if (key === "selection") return compactSelection(value);
   if (key === "selections") return Array.isArray(value) ? value.map(compactSelection) : value;
@@ -1931,7 +1980,7 @@ function buyerDocsFor(value = {}) {
     topics.add("cart-checkout");
     topics.add("payment-qr");
   }
-  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("show_human_visible_markdown") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
+  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("send_agent_instruction_to_human") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
     topics.add("payment-qr");
     topics.add("payment-wait");
   }