@itpay/cli 0.2.11 → 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 `human_output_required=true`, send root `human_output` before any next ItPay command. It is not optional UI decoration.
-- In OpenClaw Telegram, pass `human_output.message/media/presentation` to `openclaw message send`; buttons use native `text/url/callback_data`.
-- `render_plan` is diagnostic/compatibility detail. Do not choose a shorter fallback when root `human_output` is present.
+- 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_output_required is true; send response.human_output 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,10 +41,10 @@
     "Payment QR display requires both a valid/saved buyer session and payment_intent_id. If payment_intent_id appears before buyer_session is saved, run buyer checkout resume/status instead of showing payment QR.",
     "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
     "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
-    "If response.human_output_required is true, send response.human_output before any next ItPay command. It is the mandatory human-facing output, not decoration.",
-    "Do not rewrite response.human_output into a custom table. Use its text/markdown, media, links, and buttons as provided.",
-    "If human_output links or buttons include URLs, include the real URL. Do not only show the link label.",
-    "In OpenClaw Telegram, pass human_output.message/media/presentation to openclaw message send. Its presentation.blocks[].buttons[] uses native text/url/callback_data; do not simulate buttons in normal prose.",
+    "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.",

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

@@ -35,9 +35,9 @@
     }
   ],
   "agent_rules": [
-    "If payment wait returns payment_handoff_required, send response.human_output 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 human_output_required is true, send response.human_output 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 send human_output, then only check status after the human responds or uses a platform button.",
-    "If response.human_output_required is true, send response.human_output immediately in the same user-visible message. It includes the QR image/link/buttons.",
+    "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 response.human_output_required is true, root human_output is the execution path. render_plan is diagnostic/compatibility detail. In OpenClaw Telegram, pass human_output.message/media/presentation 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

@@ -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,6 +1601,8 @@ 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) {
@@ -1525,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

@@ -432,7 +432,7 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
 }
 
 function humanOutputFromRenderPlan(plan = {}) {
-  if (!plan || typeof plan !== "object") return null;
+  if (!plan || typeof plan !== "object" || !plan.kind || !plan.selected) return null;
   const selected = plan.selected || {};
   const platforms = plan.platforms || {};
   const base = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.11",
+  "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,13 +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 `human_output_required=true`,
-send root `human_output` before any next ItPay command. In Codex or Claude Code
-app clients, send `human_output.markdown` exactly. In OpenClaw Telegram, pass
-`human_output.message/media/presentation` to `openclaw message send` so media
-and native `text/url/callback_data` buttons are sent through the adapter.
-`render_plan` is diagnostic/compatibility detail. 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