@itpay/cli 0.2.11 → 0.2.13

package/lib/buyer.js

@@ -3,8 +3,9 @@ import {
   readSessionToken, readState, safeErrorMessage, sleep, splitCSV, stripInternalBuyerFields, updateRun, writeConfig,
   writeCredentials, writeSessionCredentials, writeState
 } 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);
@@ -319,7 +320,8 @@ async function buyer(command, rest, flags) {
             })));
             return;
           }
-          const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
+          let intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
+          intent = await ensureTelegramPaymentDisplay(intent, flags);
           await renderItPayPaymentAction(intent, flags);
           output(buyerRunOutput({
             status: intent.status === "verified" ? "payment_verified" : "payment_handoff_required",
@@ -367,11 +369,14 @@ async function buyer(command, rest, flags) {
   if (command === "payment" && subcommand === "wait") {
     const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
     if (!paymentIntentID) throw new Error("payment_intent_id is required");
-    const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
+    let intent = await getBuyerPaymentIntent(paymentIntentID, flags);
     if (intent.status !== "verified" && shouldReturnPaymentHandoffBeforeWait(flags)) {
+      intent = await ensureTelegramPaymentDisplay(intent, flags);
       await renderItPayPaymentAction(intent, flags);
+      const context = await optionalBuyerPaymentContext(intent, flags);
       output(buyerRunOutput({
         status: "payment_handoff_required",
+        ...context,
         payment_intent: intent,
         ...paymentHandoffFields(intent, flags),
         payment_guidance: paymentRecoveryGuidance(intent, { event_type: "payment_display_required" }),
@@ -391,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;
   }
@@ -400,8 +405,10 @@ async function buyer(command, rest, flags) {
     if (!paymentIntentID) throw new Error("payment_intent_id is required");
     const refreshed = await refreshBuyerPaymentQR(paymentIntentID, flags);
     await renderItPayPaymentAction(refreshed, flags);
+    const context = refreshed.status === "verified" ? {} : await optionalBuyerPaymentContext(refreshed, flags);
     output(buyerRunOutput({
       status: refreshed.status === "verified" ? "payment_verified" : "payment_handoff_required",
+      ...context,
       payment_intent: refreshed,
       ...(refreshed.status === "verified" ? {} : paymentHandoffFields(refreshed, flags)),
       payment_guidance: paymentRecoveryGuidance(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
@@ -702,8 +709,44 @@ async function createBuyerCartFromSelections(selections, flags = {}) {
     idempotencyKey: flags.cart_idempotency_key || `idem_cli_cart_${cryptoRandom()}`,
     body
   }, flags);
+  rememberBuyerCartDisplayContext(cart, selections, lineItems);
   writeState({ ...readState(), last_core_cart_id: cart.cart_id || cart.id });
-  return cart;
+  return mergeBuyerCartDisplayContext(cart);
+}
+
+function rememberBuyerCartDisplayContext(cart = {}, selections = [], lineItems = []) {
+  const cartID = cart.cart_id || cart.id;
+  if (!cartID) return;
+  const state = readState();
+  const contexts = state.cart_display_contexts && typeof state.cart_display_contexts === "object" ? state.cart_display_contexts : {};
+  const entries = Object.entries({
+    ...contexts,
+    [cartID]: {
+      line_items: lineItems.map((line, index) => compactObject({
+        quantity: line.quantity,
+        input: line.input,
+        title: selections[index]?.title || selections[index]?.variant_title
+      }))
+    }
+  }).slice(-20);
+  writeState({ ...state, cart_display_contexts: Object.fromEntries(entries) });
+}
+
+function mergeBuyerCartDisplayContext(cart = {}) {
+  if (!cart || typeof cart !== "object") return cart;
+  const context = readState().cart_display_contexts?.[cart.cart_id || cart.id];
+  if (!context?.line_items?.length || !Array.isArray(cart.line_items)) return cart;
+  return {
+    ...cart,
+    line_items: cart.line_items.map((line, index) => ({
+      ...line,
+      input: line.input || context.line_items[index]?.input,
+      item: {
+        ...(line.item || {}),
+        title: line.item?.title || context.line_items[index]?.title
+      }
+    }))
+  };
 }
 
 function buyerCartSelectionIDs(rest, flags = {}) {
@@ -794,7 +837,7 @@ function splitInputParts(raw) {
 
 async function getBuyerCart(cartID, flags = {}) {
   if (!cartID) throw new Error("cart_id is required");
-  return await coreApi(`/v1/carts/${encodeURIComponent(cartID)}`, { method: "GET" }, flags);
+  return mergeBuyerCartDisplayContext(await coreApi(`/v1/carts/${encodeURIComponent(cartID)}`, { method: "GET" }, flags));
 }
 
 async function addBuyerCartLineItem(cartID, selection, flags = {}) {
@@ -1051,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 = {}) {
@@ -1103,23 +1111,66 @@ function shouldReturnPaymentHandoffBeforeWait(flags = {}) {
   return !Number.isFinite(timeout) || timeout > 5;
 }
 
+async function ensureTelegramPaymentDisplay(intent = {}, flags = {}) {
+  if (!isTelegramBuyerHost(flags) || paymentDisplayAvailable(intent) || !intent.qr_refresh_url) return intent;
+  try {
+    return await refreshBuyerPaymentQR(intent.payment_intent_id, flags);
+  } catch {
+    return intent;
+  }
+}
+
+function paymentDisplayAvailable(intent = {}) {
+  const action = intent.human_action || {};
+  return Boolean(
+    action.url ||
+    action.local_qr_path ||
+    action.qr_png_url ||
+    action.qr_image_url ||
+    action.preferred_qr_url ||
+    action.mobile_wallet_url ||
+    intent.payment_url ||
+    intent.payment_entry_url ||
+    intent.qr_png_url ||
+    intent.qr_image_url ||
+    intent.mobile_wallet_url
+  );
+}
+
+async function optionalBuyerPaymentContext(intent = {}, flags = {}) {
+  if (!isTelegramBuyerHost(flags) || !intent.checkout_id) return {};
+  try {
+    const checkout = await getBuyerCheckout(intent.checkout_id, flags);
+    return compactObject({
+      checkout,
+      cart: checkout.cart_id ? await getBuyerCart(checkout.cart_id, flags) : undefined
+    });
+  } catch {
+    return {};
+  }
+}
+
+function isTelegramBuyerHost(flags = {}) {
+  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."
   };
@@ -1491,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,
@@ -1505,19 +1556,11 @@ function buyerRunOutput(value = {}) {
   }));
 }
 
-function compactBuyerOutput(value = {}) {
+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);
@@ -1525,6 +1568,222 @@ function compactBuyerOutput(value = {}) {
   return result;
 }
 
+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;
+  const summary = buyerOrderSummary(value, plan.kind);
+  const rawMessage = selected.openclaw_message;
+  const presentation = telegramBuyerPresentation(plan.kind, rawMessage);
+  const media = rawMessage.command_args?.media || rawMessage.media || selected.media?.[0]?.local_path || selected.media?.[0]?.fallback_url || "";
+  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 || {};
+  return compactObject({
+    status: value.status,
+    must_send_to_human_before_next_command: true,
+    order_summary: summary,
+    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 才算付款成功。",
+      openclaw_message: {
+        command: "openclaw message send",
+        command_args: compactObject({
+          channel: "telegram",
+          target: clientTarget(flags) || undefined,
+          message: text,
+          media: media || undefined,
+          presentation
+        }),
+        telegram_rule: "Telegram 原生按钮必须通过 openclaw message send --presentation 发送；presentation.blocks[].type=\"buttons\" 才会生成 Inline Keyboard。",
+        callbacks
+      }
+    },
+    after_human_response: telegramAfterHumanResponse(value, callbacks),
+    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 里的命令。"
+    }
+  });
+}
+
+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 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+    }
+  });
+}
+
+function buyerOrderSummary(value = {}, kind = "") {
+  const cart = value.cart || {};
+  const checkout = value.checkout || {};
+  const intent = value.payment_intent || {};
+  const context = checkout.cart_id ? readState().cart_display_contexts?.[checkout.cart_id] : null;
+  const line = cart.line_items?.[0] || context?.line_items?.[0] || {};
+  const title = value.selection?.title || line.item?.title || line.title || "ItPay 服务";
+  const quantity = line.quantity || 1;
+  const amount = intent.amount ?? checkout.amount ?? cart.amount ?? value.selection?.expected_amount ?? value.selection?.amount;
+  const currency = intent.currency || checkout.currency || cart.currency || value.selection?.currency || "";
+  return compactObject({
+    kind,
+    title,
+    quantity,
+    input_summary: buyerInputSummary(line.input),
+    amount_display: buyerHumanAmount(amount, currency),
+    order_id: checkout.order_id || intent.order_id,
+    checkout_id: checkout.checkout_id || intent.checkout_id,
+    payment_intent_id: intent.payment_intent_id,
+    status: intent.status || checkout.status || value.status
+  });
+}
+
+function buyerInputSummary(input = {}) {
+  if (!input || typeof input !== "object") return "";
+  return input.company_name || input.company_name_or_credit_no || Object.values(input).find((value) => value && value !== "1" && value !== "0") || "";
+}
+
+function buyerHumanAmount(amount, currency = "") {
+  if (!Number.isFinite(Number(amount))) return "";
+  if (String(currency).toUpperCase() === "CNY") return `¥${(Number(amount) / 100).toFixed(2)}`;
+  return `${String(currency).toUpperCase()} ${(Number(amount) / 100).toFixed(2)}`.trim();
+}
+
+function telegramBuyerInstructionText(kind, summary = {}, hasHumanEntry = true) {
+  const amount = summary.amount_display ? `，金额 ${summary.amount_display}` : "";
+  if (!hasHumanEntry) {
+    return [
+      `购物车和结算已创建，但当前付款入口需要刷新${amount}。`,
+      "请点“支付遇到问题 / 刷新”，或运行 after_human_response.refresh_qr_command 后重新发送付款入口。",
+      "",
+      `摘要：${telegramOrderSummaryText(summary)}`
+    ].join("\n");
+  }
+  const action = kind === "auth_qr" ? "完成首次授权/付款" : "完成付款";
+  const open = kind === "auth_qr" ? "打开授权" : "打开付款页面";
+  const done = kind === "auth_qr" ? "我已完成，查询状态" : "我已付款，查询状态";
+  return [
+    `购物车和结算已创建。现在需要你${action}${amount}。`,
+    `可扫二维码，或点“${open}”进入页面。`,
+    `完成后点“${done}”，我会继续查支付和交付状态。`,
+    "",
+    `摘要：${telegramOrderSummaryText(summary)}`
+  ].join("\n");
+}
+
+function telegramOrderSummaryText(summary = {}) {
+  const input = summary.input_summary ? `，关键词「${summary.input_summary}」` : "";
+  const amount = summary.amount_display ? `，${summary.amount_display}` : "";
+  return `${summary.title} × ${summary.quantity || 1} 次${input}${amount}。`;
+}
+
+function telegramBuyerPresentation(kind, rawMessage = {}) {
+  const rawBlocks = rawMessage.command_args?.presentation?.blocks || rawMessage.presentation?.blocks || [];
+  const buttons = rawBlocks.find((block) => block.type === "buttons")?.buttons || [];
+  return {
+    blocks: [{
+      type: "buttons",
+      buttons: buttons.map((button) => telegramBuyerButton(kind, button)).filter(Boolean)
+    }]
+  };
+}
+
+function telegramBuyerButton(kind, button = {}) {
+  if (button.url) {
+    if (kind === "auth_qr") return { text: "🔓 打开授权", url: button.url };
+    if (button.text === "手机钱包打开") return { text: "📱 手机钱包打开", url: button.url };
+    return { text: "💳 打开付款页面", url: button.url };
+  }
+  if (button.callback_data?.includes("refresh_payment_qr")) return { text: "🔄 支付遇到问题 / 刷新", callback_data: button.callback_data };
+  if (button.callback_data?.includes("check_payment_status")) return { text: "✅ 我已付款，查询状态", callback_data: button.callback_data };
+  if (button.callback_data?.includes("check_checkout_status")) return { text: "✅ 我已完成，查询状态", callback_data: button.callback_data };
+  return button.text && button.callback_data ? { text: button.text, callback_data: button.callback_data } : null;
+}
+
+function telegramAfterHumanResponse(value = {}, callbacks = {}) {
+  return compactObject({
+    check_status_command: callbacks.check_payment_status || callbacks.check_checkout_status || value.after_human_response?.check_payment_command,
+    refresh_qr_command: callbacks.refresh_payment_qr || value.after_human_response?.refresh_qr_command,
+    help_command: cliCommand("docs", "show", "payment-qr", "--role", "buyer", "--json"),
+    instruction: "用户点击查询按钮或回复已完成后，运行 check_status_command。用户口头说已付款不是证明。"
+  });
+}
+
+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;
@@ -1698,7 +1957,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");
   }

package/lib/client-context.js

@@ -0,0 +1,126 @@
+const SUPPORTED_HOSTS = new Set(["codex", "claude-code", "telegram", "discord", "whatsapp", "terminal", "plain-chat"]);
+const RUNTIME_TARGETS = new Set(["codex", "claude-code", "openclaw", "generic"]);
+const EXEMPT_GROUPS = new Set(["", "--help", "-h", "help", "version", "docs", "skill", "doctor", "install"]);
+
+function clientContextGate(args = []) {
+  const group = args[0] || "";
+  if (EXEMPT_GROUPS.has(group)) return null;
+  const flags = parseArgFlags(args.slice(1));
+  const host = clientHost(flags);
+  if (!host) return clientContextRequired();
+  if (!SUPPORTED_HOSTS.has(host)) return unsupportedClientContext(host);
+  if (requiresTarget(host) && !clientTarget(flags)) return clientTargetRequired(host);
+  return null;
+}
+
+function clientHost(flags = {}) {
+  const raw = firstValue(
+    flags.host,
+    flags.client,
+    flags.channel,
+    argFlag("host"),
+    argFlag("client"),
+    argFlag("channel")
+  );
+  const host = normalizeHost(raw);
+  if (host === "openclaw" && flags.channel) return normalizeHost(flags.channel);
+  return host;
+}
+
+function clientTarget(flags = {}) {
+  const target = firstValue(flags.chat_target, flags.reply_target, argFlag("chat-target"), argFlag("reply-target"));
+  if (target) return target;
+  const flagTarget = flags.target || argFlag("target");
+  return flagTarget && !RUNTIME_TARGETS.has(normalizeHost(flagTarget)) ? String(flagTarget) : "";
+}
+
+function clientCommandArgs(flags = {}) {
+  const host = clientHost(flags);
+  const target = clientTarget(flags);
+  return [
+    ...(host ? ["--host", host] : []),
+    ...(target ? ["--target", target] : [])
+  ];
+}
+
+function requiresTarget(host) {
+  return host === "telegram" || host === "discord" || host === "whatsapp";
+}
+
+function clientContextRequired() {
+  return {
+    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.",
+    allowed_hosts: Array.from(SUPPORTED_HOSTS),
+    examples: {
+      codex: "itp ... --host codex --json",
+      claude_code: "itp ... --host claude-code --json",
+      telegram: "itp ... --host telegram --target telegram:<chat_id> --json",
+      terminal: "itp ... --host terminal --json"
+    }
+  };
+}
+
+function clientTargetRequired(host) {
+  return {
+    schema_version: "itp.client_context.v1",
+    status: "client_target_required",
+    must_rerun: true,
+    host,
+    instruction: "Rerun the same itp command with the current chat target. For OpenClaw Telegram group/private chat, pass inbound_meta.chat_id as --target.",
+    examples: {
+      telegram_private: "itp ... --host telegram --target telegram:5559456744 --json",
+      telegram_group: "itp ... --host telegram --target telegram:-1001234567890 --json",
+      discord: "itp ... --host discord --target discord:<channel_id> --json"
+    }
+  };
+}
+
+function unsupportedClientContext(host) {
+  return {
+    schema_version: "itp.client_context.v1",
+    status: "unsupported_client_context",
+    must_rerun: true,
+    host,
+    instruction: "Use one supported --host value so ItPay can return a single executable human-output instruction.",
+    allowed_hosts: Array.from(SUPPORTED_HOSTS)
+  };
+}
+
+function normalizeHost(value = "") {
+  const normalized = String(value || "").trim().toLowerCase().replaceAll("_", "-");
+  if (["tg", "openclaw-telegram"].includes(normalized)) return "telegram";
+  if (["codex-app", "codex-cli"].includes(normalized)) return "codex";
+  if (["claude", "claudecode", "claude-code-app"].includes(normalized)) return "claude-code";
+  if (["plain", "plain-chat", "chat"].includes(normalized)) return "plain-chat";
+  return normalized;
+}
+
+function parseArgFlags(args = []) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!String(arg).startsWith("--")) continue;
+    const key = String(arg).slice(2).replaceAll("-", "_");
+    const next = args[i + 1];
+    if (!next || String(next).startsWith("--")) {
+      flags[key] = true;
+    } else {
+      flags[key] = next;
+      i += 1;
+    }
+  }
+  return flags;
+}
+
+function argFlag(name) {
+  return parseArgFlags(process.argv.slice(2))[String(name).replaceAll("-", "_")] || "";
+}
+
+function firstValue(...values) {
+  return values.find((value) => value !== undefined && value !== null && value !== false && String(value).trim() !== "") || "";
+}
+
+export { clientCommandArgs, clientContextGate, clientHost, clientTarget };