@itpay/cli 0.2.10 → 0.2.12

package/README.md

@@ -239,9 +239,9 @@ Payment QR rules:
 - Otherwise render the ItPay-hosted `qr_png_url` / `preferred_qr_url`.
 - Use `mobile_wallet_url` only as a human mobile fallback.
 - Do not generate your own QR from payment URLs.
-- If you know the current chat channel and `render_plan.platforms.<channel>` exists, use that branch before `render_plan.selected`.
-- In OpenClaw Telegram, send `render_plan.platforms.telegram.openclaw_message.command_args` with `openclaw message send`; its `presentation.blocks[].buttons[]` uses native `text/url/callback_data`.
-- If the channel is unsupported, use `render_plan.selected.fallback` / plain chat. Do not rewrite the chosen plan into a custom table or omit the real URL.
+- In OpenClaw Telegram, use root `agent_instruction.openclaw_message.command_args` with `openclaw message send`; do not simulate buttons in normal prose.
+- Telegram native buttons require `presentation.blocks[].type="buttons"` with `text/url/callback_data`.
+- If `human_output_required=true` appears for another client, send root `human_output` before any next ItPay command.
 - 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

@@ -26,7 +26,7 @@
     {
       "intent": "create payment intent through the high-level buy flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status is payment_handoff_required; response.human_visible_markdown and response.render_plan are present; render the QR/link to the human before any status check"
+      "success_signal": "response.status is payment_handoff_required; for OpenClaw Telegram, send response.agent_instruction.openclaw_message.command_args with openclaw message send before any status check"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -41,14 +41,12 @@
     "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 you know the current chat channel and response.render_plan.platforms.<channel> exists, use that channel branch before response.render_plan.selected.",
-    "If response.render_plan.selected.platform is current_channel_required, choose the branch matching the current channel; selected.fallback is only for unsupported plain chat clients.",
-    "Do not rewrite the chosen render plan into a custom table. Use its text/markdown, media, links, and buttons as provided.",
-    "If selected.links exists, include the real URL. Do not only show the link label.",
-    "If selected.buttons exists but the current adapter cannot render native buttons, degrade to selected.links plus short text; do not fake payment success or skip the status check.",
-    "In OpenClaw Telegram, prefer response.render_plan.platforms.telegram.openclaw_message.command_args with openclaw message send. Its presentation.blocks[].buttons[] uses native text/url/callback_data; do not simulate buttons in normal prose.",
-    "In Codex or Claude Code app clients, send response.human_visible_markdown or response.render_plan.platforms.codex_app.markdown to the human first. Do not start a hidden long wait before the human-visible message is sent.",
-    "For Telegram-style message clients, use response.render_plan.platforms.telegram: send photo media first, include links, and expose native buttons for refresh/status when the adapter supports them.",
+    "In OpenClaw Telegram, if response.agent_instruction is present, it is the mandatory execution path. Use response.agent_instruction.openclaw_message.command_args with openclaw message send before any next ItPay command.",
+    "Do not rewrite response.agent_instruction.openclaw_message into a custom table. Use its message, media, and presentation as provided.",
+    "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 or human_output links/buttons include URLs, include the real URL. Do not only show the link label.",
+    "In Codex or Claude Code app clients, send response.human_output.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.human_visible_markdown 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.",
     "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.",

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

@@ -35,9 +35,9 @@
     }
   ],
   "agent_rules": [
-    "If payment wait returns payment_handoff_required, render response.render_plan.platforms.<current channel> when available; otherwise use response.render_plan.selected/fallback before running any later status check.",
+    "If payment wait returns payment_handoff_required with response.agent_instruction, send response.agent_instruction.openclaw_message.command_args before running 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 human_visible_markdown instead of long-polling.",
+    "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.",

package/docs/agent/buyer/quickstart.json

@@ -45,7 +45,7 @@
     {
       "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; if payment_handoff_required, render response.human_visible_markdown or response.render_plan to the human before any payment status check"
+      "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"
     }
   ],
   "agent_rules": [
@@ -62,13 +62,13 @@
     "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 show human_visible_markdown/render_plan, then only check status after the human responds or uses a platform button.",
-    "If response.human_visible_markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "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.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.",
-    "When a response includes render_plan, first use render_plan.platforms.<current channel> if it exists. If selected.platform is current_channel_required, selected.fallback is only for unsupported plain chat. In OpenClaw Telegram, pass render_plan.platforms.telegram.openclaw_message.command_args to openclaw message send instead of handwritten prose."
+    "For OpenClaw Telegram, root agent_instruction is the execution path. Do not use handwritten prose when agent_instruction.openclaw_message.command_args is present."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/lib/buyer.js

@@ -4,7 +4,7 @@ import {
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, humanOutputFromRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -319,7 +319,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 +368,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" }),
@@ -400,8 +404,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 +708,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 +836,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 = {}) {
@@ -1103,6 +1145,59 @@ 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 = {}) {
+  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";
+}
+
 function paymentHandoffAgentNextActions() {
   return ["show_human_visible_markdown"];
 }
@@ -1506,12 +1601,20 @@ function buyerRunOutput(value = {}) {
 }
 
 function compactBuyerOutput(value = {}) {
+  const telegramInstruction = telegramBuyerInstruction(value);
+  if (telegramInstruction) return telegramInstruction;
   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);
@@ -1519,6 +1622,142 @@ function compactBuyerOutput(value = {}) {
   return result;
 }
 
+function telegramBuyerInstruction(value = {}) {
+  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",
+          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 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 compactBuyerField(key, value) {
   if (key === "selection") return compactSelection(value);
   if (key === "selections") return Array.isArray(value) ? value.map(compactSelection) : value;

package/lib/render-human.js

@@ -286,8 +286,9 @@ function annotateHumanActionPresentation(action, qrImageURL) {
 function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
   if (!action || typeof action !== "object") return null;
   const kind = action.kind || (isPaymentIntentHandoff(intent) ? "payment_qr" : "human_action");
-  const planAction = action.kind === kind ? action : { ...action, kind };
   const entryURL = intent.payment_entry_url || intent.payment_url || action.url || action.web_url || "";
+  const checkoutID = intent.checkout_id || action.checkout_id || checkoutIDFromURL(entryURL);
+  const planAction = compactObject({ ...(action.kind === kind ? action : { ...action, kind }), checkout_id: checkoutID || undefined });
   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 || "";
@@ -371,7 +372,10 @@ function telegramRenderPlan(action = {}, { localQRPath = "", preferredQRURL = ""
       { text: "支付遇到问题 / 刷新", intent: "refresh_payment_qr" },
       { text: "我已付款，查询状态", intent: "check_payment_status" }
     ]
-    : entryURL ? [{ text: "打开授权页面", url: entryURL }] : [];
+    : [
+      ...(entryURL ? [{ text: "打开授权页面", url: entryURL }] : []),
+      ...(action.checkout_id ? [{ text: "我已完成，查询状态", intent: "check_checkout_status" }] : [])
+    ];
   return {
     format: action.kind === "payment_qr" ? "photo_text_inline_buttons" : "text_inline_buttons",
     media,
@@ -400,6 +404,9 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
       if (button.url && !presentationButtons.some((item) => item.url === button.url)) {
         presentationButtons.push(openclawURLButton(button.text || "打开链接", button.url));
       }
+      if (button.intent === "check_checkout_status") {
+        presentationButtons.push(openclawCallbackButton("我已完成，查询状态", "check_checkout_status", action));
+      }
     }
   }
   const presentation = {
@@ -420,10 +427,56 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
       media: mediaURL || undefined,
       presentation
     }),
-    callbacks: action.kind === "payment_qr" ? {
-      refresh_payment_qr: "收到 callback_data 后刷新或重新发送同一个 payment_intent 的付款入口。",
-      check_payment_status: "收到 callback_data 后运行 buyer payment wait/status，只信 payment_intent.verified。"
-    } : undefined
+    callbacks: openclawCallbackCommands(action)
+  });
+}
+
+function humanOutputFromRenderPlan(plan = {}) {
+  if (!plan || typeof plan !== "object" || !plan.kind || !plan.selected) return null;
+  const selected = plan.selected || {};
+  const platforms = plan.platforms || {};
+  const base = {
+    required: true,
+    kind: plan.kind,
+    proof_rule: plan.proof_rule,
+    instruction: "Send this human_output to the human before running the next ItPay command."
+  };
+  if (selected.platform === "telegram") return { ...base, ...openclawHumanOutput(selected.openclaw_message) };
+  if (selected.platform === "codex_app" || selected.platform === "claude_code") return { ...base, method: "markdown_reply", markdown: selected.markdown };
+  if (selected.platform === "terminal") return { ...base, method: "terminal_display", print_terminal_qr: true, print_links: true };
+  if (selected.platform && selected.platform !== "current_channel_required") return { ...base, ...plainChatHumanOutput(selected) };
+  return {
+    ...base,
+    method: "current_channel_required",
+    instruction: "Choose the branch matching the current chat platform, send it to the human, then stop until the human responds or clicks a platform button.",
+    channels: compactObject({
+      openclaw_telegram: openclawHumanOutput(platforms.telegram?.openclaw_message),
+      codex_app: { method: "markdown_reply", markdown: platforms.codex_app?.markdown },
+      claude_code: { method: "markdown_reply", markdown: platforms.claude_code?.markdown },
+      plain_chat: plainChatHumanOutput(platforms.plain_chat),
+      terminal: { method: "terminal_display", print_terminal_qr: true, print_links: true }
+    })
+  };
+}
+
+function openclawHumanOutput(message = {}) {
+  if (!message) return null;
+  return compactObject({
+    method: "openclaw_message_send",
+    channel: "telegram",
+    message: message.command_args?.message || message.message,
+    media: message.command_args?.media || message.media,
+    presentation: message.command_args?.presentation || message.presentation,
+    callbacks: message.callbacks
+  });
+}
+
+function plainChatHumanOutput(plan = {}) {
+  if (!plan) return null;
+  return compactObject({
+    method: "plain_chat_reply",
+    text: plan.text,
+    links: plan.links
   });
 }
 
@@ -432,10 +485,33 @@ function openclawURLButton(text, url) {
 }
 
 function openclawCallbackButton(text, intent, action = {}) {
-  const id = action.payment_intent_id || action.id || "current";
+  const id = action.payment_intent_id || action.checkout_id || action.id || "current";
   return { text, callback_data: `itp:${intent}:${id}` };
 }
 
+function openclawCallbackCommands(action = {}) {
+  if (action.kind === "payment_qr") {
+    const id = action.payment_intent_id || action.id || "";
+    return compactObject({
+      refresh_payment_qr: id ? `itp buyer payment refresh-qr ${id} --json` : undefined,
+      check_payment_status: id ? `itp buyer payment wait ${id} --timeout 1 --json` : undefined
+    });
+  }
+  if (action.checkout_id) {
+    return { check_checkout_status: `itp buyer checkout resume ${action.checkout_id} --json` };
+  }
+  return undefined;
+}
+
+function checkoutIDFromURL(value = "") {
+  try {
+    const url = new URL(value);
+    return url.pathname.match(/\/checkouts\/([^/]+)/)?.[1] || "";
+  } catch {
+    return String(value || "").match(/\/checkouts\/([^/?#]+)/)?.[1] || "";
+  }
+}
+
 function selectedRenderPlatform(host = "") {
   const normalized = String(host || "").toLowerCase().replaceAll("-", "_");
   if (["codex", "codex_app", "codex_cli"].includes(normalized)) return "codex_app";
@@ -704,4 +780,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };
+export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, humanOutputFromRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -211,14 +211,14 @@ 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`: if you know the current channel
-and `render_plan.platforms.<channel>` exists, use that branch first. In Codex
-or Claude Code app clients, send the platform markdown exactly. In OpenClaw
-Telegram, pass `render_plan.platforms.telegram.openclaw_message.command_args`
-to `openclaw message send` so media and native `text/url/callback_data` buttons
-are sent through the adapter. If `selected.platform` is
-`current_channel_required`, `selected.fallback` is only for unsupported plain
-chat clients. Do not invent a table or rewrite the UI plan.
+agent/chat clients, prefer `--no-wait-payment`. In OpenClaw Telegram, if
+`agent_instruction` is present, call `openclaw message send` with
+`agent_instruction.openclaw_message.command_args`. The `media` field is the QR
+image, `message` is the exact human text, and
+`presentation.blocks[].type="buttons"` creates Telegram native inline buttons.
+Do not rewrite it as a table or normal prose. In Codex or Claude Code app
+clients, if `human_output_required=true`, send `human_output.markdown` exactly
+before any next ItPay command.
 
 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